.. _syntax_toplevel:

======
Syntax
======

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.

Expression Substitution
=======================

The simplest expression is just a variable substitution. The
syntax for this is the ``${}`` construct, which is inspired by
Perl, Genshi, JSP EL, and others:

.. sourcecode:: mako

    this is x: ${x}

Above, the string representation of ``x`` is applied to the
template's output stream. If you're wondering where ``x`` comes
from, it's usually from the :class:`.Context` supplied to the
template's rendering function. If ``x`` was not supplied to the
template and was not otherwise assigned locally, it evaluates to
a special value ``UNDEFINED``. More on that later.

The contents within the ``${}`` tag are evaluated by Python
directly, so full expressions are OK:

.. sourcecode:: mako

    pythagorean theorem:  ${pow(x,2) + pow(y,2)}

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.

Expression Escaping
===================

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
substitution using the ``|`` operator:

.. sourcecode:: mako

    ${"this is some text" | u}

The above expression applies URL escaping to the expression, and
produces ``this+is+some+text``. The ``u`` name indicates URL
escaping, whereas ``h`` represents HTML escaping, ``x``
represents XML escaping, and ``trim`` applies a trim function.

Read more about built-in filtering functions, including how to
make your own filter functions, in :ref:`filtering_toplevel`.

Control Structures
==================

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 ``try``/``except``. In Mako,
control structures are written using the ``%`` marker followed
by a regular Python control expression, and are "closed" by
using another ``%`` marker with the tag "``end<name>``", where
"``<name>``" is the keyword of the expression:

.. sourcecode:: mako

    % if x==5:
        this is some output
    % endif

The ``%`` can appear anywhere on the line as long as no text
precedes it; indentation is not significant. The full range of
Python "colon" expressions are allowed here, including
``if``/``elif``/``else``, ``while``, ``for``, ``with``, and even ``def``,
although Mako has a built-in tag for defs which is more full-featured.

.. sourcecode:: mako

    % 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

The ``%`` 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 ``%%``:

.. sourcecode:: mako

    %% some text

        %% some more text

The Loop Context
----------------

The **loop context** provides additional information about a loop
while inside of a ``% for`` structure:

.. sourcecode:: mako

    <ul>
    % for a in ("one", "two", "three"):
        <li>Item ${loop.index}: ${a}</li>
    % endfor
    </ul>

See :ref:`loop_context` for more information on this feature.

.. versionadded:: 0.7

Comments
========

Comments come in two varieties. The single line comment uses
``##`` as the first non-space characters on a line:

.. sourcecode:: mako

    ## this is a comment.
    ...text ...

A multiline version exists using ``<%doc> ...text... </%doc>``:

.. sourcecode:: mako

    <%doc>
        these are comments
        more comments
    </%doc>

Newline Filters
===============

The backslash ("``\``") character, placed at the end of any
line, will consume the newline character before continuing to
the next line:

.. sourcecode:: mako

    here is a line that goes onto \
    another line.

The above text evaluates to:

.. sourcecode:: text

    here is a line that goes onto another line.

Python Blocks
=============

Any arbitrary block of python can be dropped in using the ``<%
%>`` tags:

.. sourcecode:: mako

    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

Within ``<% %>``, 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.

Module-level Blocks
===================

A variant on ``<% %>`` is the module-level code block, denoted
by ``<%! %>``. 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 ``<%! %>``
tags to declare your template's imports, as well as any
pure-Python functions you might want to declare:

.. sourcecode:: mako

    <%!
        import mylib
        import re

        def filter(text):
            return re.sub(r'^@', '', text)
    %>

Any number of ``<%! %>`` blocks can be declared anywhere in a
template; they will be rendered in the resulting module
in a single contiguous block above all render callables,
in the order in which they appear in the source template.

Tags
====

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 ``%``
character. The tag is closed either by a contained slash
character, or an explicit closing tag:

.. sourcecode:: mako

    <%include file="foo.txt"/>

    <%def name="foo" buffered="True">
        this is a def
    </%def>

All tags have a set of attributes which are defined for each
tag. Some of these attributes are required. Also, many
attributes support **evaluation**, meaning you can embed an
expression (using ``${}``) inside the attribute text:

.. sourcecode:: mako

    <%include file="/foo/bar/${myfile}.txt"/>

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 it's not
valid.

Heres a quick summary of all the tags:

``<%page>``
-----------

This tag defines general characteristics of the template,
including caching arguments, and optional lists of arguments
which the template expects when invoked.

.. sourcecode:: mako

    <%page args="x, y, z='default'"/>

Or a page tag that defines caching characteristics:

.. sourcecode:: mako

    <%page cached="True" cache_type="memory"/>

Currently, only one ``<%page>`` 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 ``<%page>`` tag
defined in your template, else you may not get the results you
want. The details of what ``<%page>`` is used for are described
further in :ref:`namespaces_body` as well as :ref:`caching_toplevel`.

``<%include>``
--------------

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:

.. sourcecode:: mako

    <%include file="header.html"/>

        hello world

    <%include file="footer.html"/>

Include also accepts arguments which are available as ``<%page>`` arguments in the receiving template:

.. sourcecode:: mako

    <%include file="toolbar.html" args="current_section='members', username='ed'"/>

``<%def>``
----------

The ``%def`` 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:

.. sourcecode:: mako

    <%def name="myfunc(x)">
        this is myfunc, x is ${x}
    </%def>

    ${myfunc(7)}

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
:class:`.Context`, 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 :ref:`defs_toplevel`.

``<%block>``
------------

``%block`` is a tag that is close to a ``%def``,
except executes itself immediately in its base-most scope,
and can also be anonymous (i.e. with no name):

.. sourcecode:: mako

    <%block filter="h">
        some <html> stuff.
    </%block>

Inspired by Jinja2 blocks, named blocks offer a syntactically pleasing way
to do inheritance:

.. sourcecode:: mako

    <html>
        <body>
        <%block name="header">
            <h2><%block name="title"/></h2>
        </%block>
        ${self.body()}
        </body>
    </html>

Blocks are introduced in :ref:`blocks` and further described in :ref:`inheritance_toplevel`.

.. versionadded:: 0.4.1

``<%namespace>``
----------------

``%namespace`` is Mako's equivalent of Python's ``import``
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.

.. sourcecode:: mako

    <%namespace file="functions.html" import="*"/>

The underlying object generated by ``%namespace``, an instance of
:class:`.mako.runtime.Namespace`, 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 :ref:`namespaces_toplevel`.

``<%inherit>``
--------------

Inherit allows templates to arrange themselves in **inheritance
chains**. This is a concept familiar in many other template
languages.

.. sourcecode:: mako

    <%inherit file="base.html"/>

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 flexibility in this area, including dynamic
inheritance, content wrapping, and polymorphic method calls.
Check it out in :ref:`inheritance_toplevel`.

``<%``\ nsname\ ``:``\ defname\ ``>``
-------------------------------------

Any user-defined "tag" can be created against
a namespace by using a tag with a name of the form
``<%<namespacename>:<defname>>``. The closed and open formats of such a
tag are equivalent to an inline expression and the ``<%call>``
tag, respectively.

.. sourcecode:: mako

    <%mynamespace:somedef param="some value">
        this is the body
    </%mynamespace:somedef>

To create custom tags which accept a body, see
:ref:`defs_with_content`.

.. versionadded:: 0.2.3

``<%call>``
-----------

The call tag is the "classic" form of a user-defined tag, and is
roughly equivalent to the ``<%namespacename:defname>`` syntax
described above. This tag is also described in :ref:`defs_with_content`.

``<%doc>``
----------

The ``%doc`` tag handles multiline comments:

.. sourcecode:: mako

    <%doc>
        these are comments
        more comments
    </%doc>

Also the ``##`` symbol as the first non-space characters on a line can be used for single line comments.

``<%text>``
-----------

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:

.. sourcecode:: mako

    <%text filter="h">
        heres some fake mako ${syntax}
        <%def name="x()">${x}</%def>
    </%text>

.. _syntax_exiting_early:

Exiting Early from a Template
=============================

Sometimes you want to stop processing a template or ``<%def>``
method in the middle and just use the text you've accumulated so
far.  This is accomplished by using ``return`` statement inside
a Python block.   It's a good idea for the ``return`` statement
to return an empty string, which prevents the Python default return
value of ``None`` from being rendered by the template.  This
return value is for semantic purposes provided in templates via
the ``STOP_RENDERING`` symbol:

.. sourcecode:: mako

    % if not len(records):
        No records found.
        <% return STOP_RENDERING %>
    % endif

Or perhaps:

.. sourcecode:: mako

    <%
        if not len(records):
            return STOP_RENDERING
    %>

In older versions of Mako, an empty string can be substituted for
the ``STOP_RENDERING`` symbol:

.. sourcecode:: mako

    <% return '' %>

.. versionadded:: 1.0.2 - added the ``STOP_RENDERING`` symbol which serves
   as a semantic identifier for the empty string ``""`` used by a
   Python ``return`` statement.