# -*- coding: utf-8 -*-
<%inherit file="content_layout.html"/>
<%page args="toc, extension, paged"/>
<%namespace  name="formatting" file="formatting.html"/>
<%namespace  name="nav" file="nav.html"/>
<%def name="title()">Mako Documentation - Syntax</%def>
<%!
    filename = 'syntax'
%>
## This file is generated.  Edit the .txt files instead of this one.


<%call expr="formatting.section(toc=toc,paged=paged,extension=extension,path='syntax')">

<p>A Mako template is parsed from a text stream containing any kind of content, XML, HTML, email text, etc.  The template can further contain Mako-specific directives which represent variable and/or expression substitutions, control structures (i.e. conditionals and loops), server-side comments, full blocks of Python code, as well as various tags that offer additional functionality.  All of these constructs compile into real Python code.  This means that you can leverage the full power of Python in almost every aspect of a Mako template.
</p>

<%call expr="formatting.section(toc=toc,paged=paged,extension=extension,path='syntax_expression')">

<p>The simplest expression is just a variable substitution.  The syntax for this is the <code><%text filter='h'>${}</%text></code> construct, which is inspired by Perl, Genshi, JSP EL, and others:
</p>
<%call expr="formatting.code()"><%text>this is x: ${x}
</%text></%call><p>Above, the string representation of <code><%text filter='h'>x</%text></code> is applied to the template's output stream.  If you're wondering where <code><%text filter='h'>x</%text></code> comes from, its usually from the <code><%text filter='h'>Context</%text></code> supplied to the template's rendering function.  If <code><%text filter='h'>x</%text></code> was not supplied to the template and was not otherwise assigned locally, it evaluates to a special value <code><%text filter='h'>UNDEFINED</%text></code>.  More on that later.
</p>
<p>The contents within the <code><%text filter='h'>${}</%text></code> tag are evaluated by Python directly, so full expressions are OK:
</p>
<%call expr="formatting.code()"><%text>pythagorean theorem:  ${pow(x,2) + pow(y,2)}
</%text></%call><p>The results of the expression are evaluated into a string result in all cases before being rendered to the output stream, such as the above example where the expression produces a numeric result.
</p>

<%call expr="formatting.section(toc=toc,paged=paged,extension=extension,path='syntax_expression_expression')">

<p>Mako includes a number of built-in escaping mechanisms, including HTML, URI and XML escaping, as well as a "trim" function.  These escapes can be added to an expression substituion using the <code><%text filter='h'>|</%text></code> operator:
</p>
<%call expr="formatting.code()"><%text>${"this is some text" | u}
</%text></%call><p>The above expression applies URL escaping to the expression, and produces <code><%text filter='h'>this+is+some+text</%text></code>.  The <code><%text filter='h'>u</%text></code> name indicates URL escaping, whereas <code><%text filter='h'>h</%text></code> represents HTML escaping, <code><%text filter='h'>x</%text></code> represents XML escaping, and <code><%text filter='h'>trim</%text></code> applies a trim function.
</p>
<p>Read more about built in filtering functions, including how to make your own filter functions, in <%call expr="nav.toclink(toc=toc,paged=paged,extension=extension,path='filtering')"></%call>.
</p>

</%call>
</%call>
<%call expr="formatting.section(toc=toc,paged=paged,extension=extension,path='syntax_control')">

<p>A control structure refers to all those things that control the flow of a program - conditionals (i.e. if/else), loops (like while and for), as well as things like <code><%text filter='h'>try/except</%text></code>.  In Mako, control structures are written using the <code><%text filter='h'>%</%text></code> marker followed by a regular Python control expression, and are "closed" by using another <code><%text filter='h'>%</%text></code> marker with the tag "<code><%text filter='h'>end<name></%text></code>", where "<code><%text filter='h'><name></%text></code>" is the keyword of the expression:
</p>
<%call expr="formatting.code()"><%text>% if x==5:
    this is some output
% endif
</%text></%call><p>The <code><%text filter='h'>%</%text></code> can appear anywhere on the line as long as no text precedes it; indentation is not signficant.  The full range of Python "colon" expressions are allowed here, including <code><%text filter='h'>if/elif/else</%text></code>, <code><%text filter='h'>while</%text></code>, <code><%text filter='h'>for</%text></code>, and even <code><%text filter='h'>def</%text></code>, although Mako has a built-in tag for defs which is more full-featured.
</p>
<%call expr="formatting.code()"><%text>% for a in ['one', 'two', 'three', 'four', 'five']:
    % if a[0] == 't':
     its two or three
    % elif a[0] == 'f':
    four/five
    % else:
    one
    %endif
% endfor
</%text></%call><p>The <code><%text filter='h'>%</%text></code> sign can also be "escaped", if you actually want to emit a percent sign as the first non whitespace character on a line, by escaping it as in <code><%text filter='h'>%%</%text></code>:
</p>
<%call expr="formatting.code()"><%text>%% some text

    %% some more text
</%text></%call>
</%call>
<%call expr="formatting.section(toc=toc,paged=paged,extension=extension,path='syntax_comments')">

<p>Comments come in two varieties.  The single line comment uses <code><%text filter='h'>##</%text></code> as the first non-space characters on a line:
</p>
<%call expr="formatting.code()"><%text>## this is a comment.
...text ...
</%text></%call><p>A multiline version exists using <code><%text filter='h'><%doc>  ...text... </%doc></%text></code>:
</p>
<%call expr="formatting.code()"><%text><%doc>
    these are comments
    more comments
</%doc>
</%text></%call>
</%call>
<%call expr="formatting.section(toc=toc,paged=paged,extension=extension,path='syntax_newline')">

<p>The backslash ("<code><%text filter='h'>\</%text></code>") character, placed at the end of any line, will consume the newline character before continuing to the next line:
</p>
<%call expr="formatting.code()"><%text>here is a line that goes onto \
another line.
</%text></%call><p>The above text evaluates to:
</p>
<%call expr="formatting.code()"><%text>here is a line that goes onto another line.
</%text></%call>
</%call>
<%call expr="formatting.section(toc=toc,paged=paged,extension=extension,path='syntax_python')">

<p>Any arbitrary block of python can be dropped in using the <code><%text filter='h'><% %></%text></code> tags:
</p>
<%call expr="formatting.code()"><%text>this is a template
<%
    x = db.get_resource('foo')
    y = [z.element for z in x if x.frobnizzle==5]
%>
% for elem in y:
    element: ${elem}
% endfor
</%text></%call><p>Within <code><%text filter='h'><% %></%text></code>, you're writing a regular block of Python code.  While the code can appear with an arbitrary level of preceding whitespace,  it has to be consistently formatted with itself.  Mako's compiler will adjust the block of Python to be consistent with the surrounding generated Python code.
</p>

<%call expr="formatting.section(toc=toc,paged=paged,extension=extension,path='syntax_python_module-level')">

<p>A variant on <code><%text filter='h'><% %></%text></code> is the module-level code block, denoted by <code><%text filter='h'><%! %></%text></code>.  Code within these tags is executed at the module level of the template, and not within the rendering function of the template.  Therefore, this code does not have access to the template's context and is only executed when the template is loaded into memory (which can be only once per application, or more, depending on the runtime environment).  Use the <code><%text filter='h'><%! %></%text></code> tags to declare your template's imports, as well as any pure-Python functions you might want to declare:
</p>
<%call expr="formatting.code()"><%text><%!
    import mylib
    import re

    def filter(text):
        return re.sub(r'^@', '', text)
%>
</%text></%call><p>Any number of <code><%text filter='h'><%! %></%text></code> blocks can be declared anywhere in a template; they will be rendered in the resulting module in the order that they appear.
</p>

</%call>
</%call>
<%call expr="formatting.section(toc=toc,paged=paged,extension=extension,path='syntax_tags')">

<p>The rest of what Mako offers takes place in the form of tags.  All tags use the same syntax, which is similar to an XML tag except that the first character of the tag name is a <code><%text filter='h'>%</%text></code> character.  The tag is closed either by a contained slash character, or an explicit closing tag:
</p>
<%call expr="formatting.code()"><%text><%include file="foo.txt"/>

<%def name="foo" buffered="True">
    this is a def
</%def>
</%text></%call><p>All tags have a set of attributes which are defined for each tag.  Some of these attributes are required.  Also, many attributes support <strong>evaluation</strong>, meaning you can embed an expression (using <code><%text filter='h'>${}</%text></code>) inside the attribute text:
</p>
<%call expr="formatting.code()"><%text><%include file="/foo/bar/${myfile}.txt"/>
</%text></%call><p>Whether or not an attribute accepts runtime evaluation depends on the type of tag and how that tag is compiled into the template.  The best way to find out if you can stick an expression in is to try it !  The lexer will tell you if its not valid.
</p>
<p>Heres a quick summary of all the tags:
</p>

<%call expr="formatting.section(toc=toc,paged=paged,extension=extension,path='syntax_tags_page')">

<p>This tag defines general characteristics of the template, including caching arguments, and optional lists of arguments which the template expects when invoked.
</p>
<%call expr="formatting.code()"><%text><%page args="x, y, z='default'"/>
</%text></%call><p>Or a page tag that defines caching characteristics:
</p>
<%call expr="formatting.code()"><%text><%page cached="True" cache_type="memory"/>
</%text></%call><p>Currently, only one <code><%text filter='h'><%page></%text></code> tag gets used per template, the rest get ignored.  While this will be improved in a future release, for now make sure you have only one <code><%text filter='h'><%page></%text></code> tag defined in your template, else you may not get the results you want.  The details of what <code><%text filter='h'><%page></%text></code> is used for are described further in <%call expr="nav.toclink(toc=toc,paged=paged,extension=extension,path='namespaces_body')"></%call> as well as <%call expr="nav.toclink(toc=toc,paged=paged,extension=extension,path='caching')"></%call>.
</p>

</%call>
<%call expr="formatting.section(toc=toc,paged=paged,extension=extension,path='syntax_tags_include')">

<p>A tag that is familiar from other template languages, %include is a regular joe that just accepts a file argument and calls in the rendered result of that file:
</p>
<%call expr="formatting.code()"><%text><%include file="header.html"/>

    hello world

<%include file="footer.html"/>
</%text></%call><p>Include also accepts arguments which are available as <code><%text filter='h'><%page></%text></code> arguments in the receiving template:
</p>
<%call expr="formatting.code()"><%text><%include file="toolbar.html" args="current_section='members', username='ed'"/>
</%text></%call>
</%call>
<%call expr="formatting.section(toc=toc,paged=paged,extension=extension,path='syntax_tags_def')">

<p>The <code><%text filter='h'>%def</%text></code> tag defines a Python function which contains a set of content, that can be called at some other point in the template.  The basic idea is simple:
</p>
<%call expr="formatting.code()"><%text><%def name="myfunc(x)">
    this is myfunc, x is ${x}
</%def>

${myfunc(7)}
</%text></%call><p>The %def tag is a lot more powerful than a plain Python def, as the Mako compiler provides many extra services with %def that you wouldn't normally have, such as the ability to export defs as template "methods", automatic propagation of the current <code><%text filter='h'>Context</%text></code>, buffering/filtering/caching flags, and def calls with content, which enable packages of defs to be sent as arguments to other def calls (not as hard as it sounds).  Get the full deal on what %def can do in <%call expr="nav.toclink(toc=toc,paged=paged,extension=extension,path='defs')"></%call>.
</p>

</%call>
<%call expr="formatting.section(toc=toc,paged=paged,extension=extension,path='syntax_tags_namespace')">

<p>%namespace is Mako's equivalent of Python's <code><%text filter='h'>import</%text></code> statement.  It allows access to all the rendering functions and metadata of other template files, plain Python modules, as well as locally defined "packages" of functions.
</p>
<%call expr="formatting.code()"><%text><%namespace file="functions.html" import="*"/>
</%text></%call><p>The underlying object generated by %namespace, an instance of <code><%text filter='h'>mako.runtime.Namespace</%text></code>, is a central construct used in templates to reference template-specific information such as the current URI, inheritance structures, and other things that are not as hard as they sound right here.  Namespaces are described in <%call expr="nav.toclink(toc=toc,paged=paged,extension=extension,path='namespaces')"></%call>.
</p>

</%call>
<%call expr="formatting.section(toc=toc,paged=paged,extension=extension,path='syntax_tags_inherit')">

<p>Inherit allows templates to arrange themselves in <strong>inheritance chains</strong>.  This is a concept familiar in many other template languages.
</p>
<%call expr="formatting.code()"><%text><%inherit file="base.html"/>
</%text></%call><p>When using the %inherit tag, control is passed to the topmost inherited template first, which then decides how to handle calling areas of content from its inheriting templates.  Mako offers a lot of flexbility in this area, including dynamic inheritance, content wrapping, and polymorphic method calls.  Check it out in <%call expr="nav.toclink(toc=toc,paged=paged,extension=extension,path='inheritance')"></%call>.
</p>

</%call>
<%call expr="formatting.section(toc=toc,paged=paged,extension=extension,path='syntax_tags_namespacename:defname')">

<p>As of Mako 0.2.3, any user-defined "tag" can be created against a namespace by using a tag with a name of the form <em>namespacename</em>:<em>defname</em>.  The closed and open formats of such a tag are equivalent to an inline expression and the <code><%text filter='h'><%call></%text></code> tag, respectively.
</p>
<%call expr="formatting.code()"><%text><%mynamespace:somedef param="some value">
    this is the body
</%mynamespace:somedef>
</%text></%call><p>To create custom tags which accept a body, see <%call expr="nav.toclink(toc=toc,paged=paged,extension=extension,path='defs_defswithcontent')"></%call>.
</p>

</%call>
<%call expr="formatting.section(toc=toc,paged=paged,extension=extension,path='syntax_tags_call')">

<p>The call tag is the "classic" form of a user-defined tag, and is roughly equiavlent to the <code><%text filter='h'><%namespacename:defname></%text></code> syntax described above.  This tag is also described in <%call expr="nav.toclink(toc=toc,paged=paged,extension=extension,path='defs_defswithcontent')"></%call>.
</p>

</%call>
<%call expr="formatting.section(toc=toc,paged=paged,extension=extension,path='syntax_tags_doc')">

<p>The doc tag handles multiline comments:
</p>
<%call expr="formatting.code()"><%text><%doc>
    these are comments
    more comments
</%doc>
</%text></%call><p>Also the <code><%text filter='h'>##</%text></code> symbol as the first non-space characters on a line can be used for single line comments.
</p>

</%call>
<%call expr="formatting.section(toc=toc,paged=paged,extension=extension,path='syntax_tags_text')">

<p>This tag suspends the Mako lexer's normal parsing of Mako template directives, and returns its entire body contents as plain text.  It is used pretty much to write documentation about Mako:
</p>
<%call expr="formatting.code()"><%text><%text filter="h">
    heres some fake mako ${syntax}
    <%def name="x()">${x}</%def>
%CLOSETEXT
</%text></%call>
</%call>
</%call>
<%call expr="formatting.section(toc=toc,paged=paged,extension=extension,path='syntax_returning')">

<p>Sometimes you want to stop processing a template or <code><%text filter='h'><%def></%text></code> method in the middle and just use the text you've accumulated so far.  You can use a <code><%text filter='h'>return</%text></code> statement inside a Python block to do that.
</p>
<%call expr="formatting.code()"><%text>% if not len(records):
    No records found.
    <% return %>
% endif
</%text></%call><p>Or perhaps:
</p>
<%call expr="formatting.code()"><%text><%
    if not len(records):
        return
%>
</%text></%call>

</%call>
</%call>
</html>