# Kajiki Runtime

It’s sometimes good to have a mental model of the Python code that Kajiki creates in order to generate your templates. This document uses several examples taken from the text templating language to illustrate the semantics of Kajiki templates. If in doubt, you can always view the Python text generated for a template by examining the py_text attribute of the generated Template class.

`xml_template.``XMLTemplate`(source=None, filename=None, mode=None, is_fragment=False, encoding=u'utf-8', autoblocks=None, cdata_scripts=True, strip_text=False, base_globals=None)

  Given XML source code of a Kajiki Templates parses and returns a template class.

  The source code is parsed to its DOM representation by `_Parser`, which is then expanded to separate directives from tags by `_DomTransformer` and then compiled to the Intermediate Representation tree by `_Compiler`.

  The Intermediate Representation generates the Python code which creates a new `kajiki.template._Template` subclass through `kajiki.template.Template()`.

  The generated code is then executed to return the newly created class.

  Calling `.render()` on an instance of the generate class will then render the template.

class `kajiki.ir.``TemplateNode`(mod_py=None, defs=None)

  Represents the root Intermediate Representation node of a template.

  Iterating over this will generate the Python code for the class that provides all the functions that are part of the template including the `__main__` function that represents the template code itself.

  The generated class will then be passed to `kajiki.template.Template()` to create a `kajiki.template._Template` subclass that has the `render` method to render the template.

`template.``Template`(ns)

  Creates a new `_Template` subclass from an entity with `exposed` functions.

  Kajiki uses classes as containers of the exposed functions for convenience, but any object that can have the functions as attributes works.

  To be a valid template the original entity must provide at least a `__main__` function:

      class Example:
          @kajiki.expose
          def __main__():
              yield 'Hi'

      t = kajiki.Template(Example)
      output = t().render()

      print(output)
      'Hi'

class `kajiki.template.``_Template`(context=None)

  Base Class for all compiled Kajiki Templates.

  All kajiki templates created from a `kajiki.ir.TemplateNode` will be subclasses of this class.

  As the template body code runs inside `__main__` method of this class, the instance of this class is always available as `self` inside the template code.

  This class also makes available some global object inside the template code itself:

  > - `local` which is the instance of the template
  > - `defined` which checks if the given variable is defined inside the template scope.
  > - `Markup` which marks the passed object as markup code and prevents escaping for its content.
  > - `__kj__` which is a special object used by generated code providing features like keeping track of py:with stack or or the gettext function used to translate text.

  `defined`(name)

    Check if a variable was provided to the template or not

  `render`()

    Render the template to a string.

class `kajiki.xml_template.``_Compiler`(filename, doc, mode=None, is_fragment=False, autoblocks=None, cdata_scripts=True)

  Compiles a DOM tree into Intermediate Representation `kajiki.ir.TemplateNode`.

  Intermediate Representation is a tree of nodes that represent Python Code that should be generated to execute the template.

  `compile`()

    Compile the document provided by `_Parser`.

    Returns as `kajiki.ir.TemplateNode` instance representing the whole tree of nodes as their intermediate representation.

    The returned template will include at least a `__main__` function which is the document itself including a DOCTYPE and any function declared through `py:def` or as a `py:block`.

    The `TemplateNode` will also include the module level code specified through `<?py %`.

    If the compiled document didn’t specify a DOCTYPE provides one at least for HTML5.

    Note

    As this alters the functions and mode wide code registries of the compiler `compile` should never be called twice or might lead to unexpected results.

class `kajiki.xml_template.``_Parser`(filename, source)

  Parse an XML template into a Tree of DOM Nodes.

  Nodes should then be passed to a _Compiler to be converted into the intermediate representation and then to Python Code.

  `parse`()

    Parse an XML/HTML document to its DOM representation.

class `kajiki.xml_template.``_DomTransformer`(doc, strip_text=True)

  Applies standard Kajiki transformations to a parsed document.

  Given a document generated by `Parser` it applies some node transformations that are necessary before applying the compilation steps to achieve result we usually expect.

  This includes things like squashing consecutive text nodes and expanding `py:` directives.

  The Transformer mutates the original document.

  `transform`()

    Applies all the DOM transformations to the document.

    Calling this twice will do nothing as the result is persisted.

## Basic Expressions

Let’s start with a hello world template:

    Hello, World!

This converts to the equivalent Python:

    @kajiki.expose
    def __call__():
        yield 'Hello, World!\n'

Slightly more verbose “hello_name.txt”:

    Hello, $name!

This converts to the equivalent Python:

    @kajiki.expose
    def __call__():
         yield 'Hello, '
         yield name
         yield '!\n'

By default, the $-syntax picks up any identifiers following it, as well as any periods. If you want something more explicit, use the extended expression form as in “hello_arithmetic.txt”:

    Hello, 2 + 2 is ${2+2}!

This converts to:

    @kajiki.expose
    def __call__():
        yield 'Hello, 2 + 2 is '
        yield 2+2
        yield '!'

If you wish to include a literal $, simply prefix it with a backslash.

## Control Flow

Kajiki provides several tags that affect the rendering of a template. The following template “control_flow.txt” illustrates:

    A{%for i in range(5)%}
        {%if i < 2%}Low{%elif i < 4%}Mid{%else%}High{%end%}$i
        {%switch i % 2%}
            {%case 0%}
                even
            {%default%}
                odd
            {%end%}{%end%}{%end%}

This yields the following Python:

    @kajiki.expose
    def __call__():
        yield 'A\n' # from the {%for... line
        for i in range(10):
            yield '\n        ' # from the newline and initial indent of next line
            if i < 2:
                yield 'Low'
            elif i < 4:
                yield 'Mid'
            else:
                yield 'High'
            yield i
            yield '\n        ' # from the {%if... newline and next indent
            local.__kj__.push_switch(i%2)
            # whitespace after {%switch is always stripped
            if local.__kj__.case(0):
                yield '\n            even\n        '
            else:
                yield '\n            odd\n        '
            local.__kj__.pop_switch()

Which would in turn generate the following text:

    A
        Low0

            even

        Low1

            odd

        Mid2

            even

        Mid3

            odd

        High4

            even

If you want to strip whitespace before or after a tag, just replace `{%` with `{%-` (for stripping leading whitespace) or `%}` with `-%}` (for stripping trailing whitespace). If you would like to remove newlines, just end a line with a backslash. Here is the equivalent template with whitespace removed, “control_flow_ws.txt”:

    A{%-for i in range(5) -%}\
        {%-if i < 2%}Low{%elif i < 4%}Mid{%else%}High{%end%}$i
        {%-switch i % 2%}\
            {%-case 0%}\
                even
            {%-default%}\
                odd
            {%-end%}\
        {%-end%}\
    {%-end%}\

This would generate the following Python:

    @kajiki.expose
    def __call__():
        yield 'A'
        for i in range(10):
            if i < 2:
                yield 'Low'
            elif i < 4:
                yield 'Mid'
            else:
                yield 'High'
            yield i
            yield '\n'
            local.__kj__.push_switch(i % 2)
            if local.__kj__.case(0):
                yield 'even\n'
            else:
                yield 'odd\n'
            local.__kj__.pop_switch()

Which would generate the following text:

    ALow0
    even
    Low1
    odd
    Mid2
    even
    Mid3
    odd
    High4
    even

which is probably closer to what you wanted. There is also a shorthand syntax that allows for line-oriented control flow as seen in “control_flow_ws_short.txt”:

    A\
    %for i in range(5)
        %if i < 2
            Low\
        %elif i < 4
            Mid\
        %else
            High\
        {%-end%}$i
        %switch i % 2
            %case 0
                even
            %default
                odd
            %end
        %end
    %end

This syntax yields exactly the same results as “control_flow_ws.txt” above.

## Python Blocks

You can insert literal Python code into your template using the following syntax in “simple_py_block.txt”:

    {%py%}\
        yield 'Prefix'
    {%end%}\
    Body

or alternatively:

    %py
        yield 'Prefix'
    %end
    Body

or even more succinctly:

    %py yield 'Prefix'
    Body

all of which will generate the following Python:

    def __call__():
        yield 'Prefix'
        yield 'Body'

Note in particular that the Python block can have any indentation, as long as it
  is consistent (the amount of leading whitespace in the first non-empty line of the block is stripped from all lines within the block). You can insert module-level Python (imports, etc.) by using the %py% directive (or {%py%%} as in “module_py_block.txt”:

    %py%
        import sys
        import re
    %end
    Hello
    %py% import os
    %end

This yields the following Python:

    import sys
    import re

    import os

    @kajiki.expose
    def __call__():
        yield 'Hello'

## Functions and Imports

Kajiki provides for code reuse via the %def and %import directives. First, let’s see %def in action in “simple_function.txt”:

    %def evenness(n)
        %if n % 2 == 0
            even\
        %else
            odd\
        %end
    %end
    %for i in range(5)
    $i is ${evenness(i)}
    %end

This compiles to the following Python:

    @kajiki.expose
    def evenness(n):
        if n % 2:
            yield 'even'
        else:
            yield 'odd'

    @kajiki.expose
    def __call__():
        for i in range(5):
            yield i
            yield ' is '
            yield evenness(i)

The %import directive allows you to package up your functions for reuse in another template file (or even in a Python package). For instance, consider the following file “import_test.txt”:

    %import "simple_function.txt" as simple_function
    %for i in range(5)
    $i is ${simple_function.evenness(i)}
    %end

This would then compile to the following Python:

    @kajiki.expose
    def __call__():
        simple_function = local.__kj__.import_("simple_function.txt")
        for i in range(5):
            yield i
            yield ' is '
            yield simple_function.evenness(i)

Note that when using the %import directive, any “body” in the imported template is ignored and only functions are imported. If you actually wanted to insert the body of the imported template, you would simply call the imported template as a function itself (e.g. ${simple_function()}).

Sometimes it is convenient to pass the contents of a tag to a function. In this case, you can use the %call directive as shown in “call.txt”:

    %def quote(caller, speaker)
        %for i in range(5)
    Quoth $speaker, "${caller(i)}."
        %end
    %end
    %call(n) quote('the raven')
    Nevermore $n\
    %end

This results in the following Python:

    @kajiki.expose
    def quote(caller, speaker):
        for i in range(5):
            yield 'Quoth '
            yield speaker
            yield ', "'
            yield caller(i)
            yield '."'

    @kajiki.expose
    def __call__():
        @kajiki.expose
        def _fpt_lambda(n):
            yield 'Nevermore '
            yield n
        yield quote(_fpt_lambda, 'the raven')
        del _fpt_lambda

Which in turn yields the following output:

    Quoth the raven, "Nevermore 0."
    Quoth the raven, "Nevermore 1."
    Quoth the raven, "Nevermore 2."
    Quoth the raven, "Nevermore 3."
    Quoth the raven, "Nevermore 4."

## Includes

Sometimes you just want to pull the text of another template into your template verbatim. For this, you use the %include directive as in “include_example.txt”:

    This is my story:
    %include "call.txt"
    Isn't it good?

which yields the following Python:

    @kajiki.expose
    def __call__():
        yield 'This is my story:\n'
        yield _fpt.import("simple_function.txt")()
        yield 'Isn't it good?\n'

Which of course yields:

    This is my story:
    Quoth the raven, "Nevermore 0."
    Quoth the raven, "Nevermore 1."
    Quoth the raven, "Nevermore 2."
    Quoth the raven, "Nevermore 3."
    Quoth the raven, "Nevermore 4."
    Isn't it good?

## Inheritance

Kajiki supports a concept of inheritance whereby child templates can extend parent templates, replacing their methods and “blocks” (to be defined below). For instance, consider the following template “parent.txt”:

    %def greet(name)
    Hello, $name!\
    %end
    %def sign(name)
    Sincerely,
    $name\
    %end
    ${greet(to)}

    %block body
    It was good seeing you last Friday.  Thanks for the gift!
    %end

    ${sign(from)}

This would generate the following Python:

    @kajiki.expose
    def greet(name):
        yield 'Hello, '
        yield name
        yield '!'

    @kajiki.expose
    def sign(name):
        yield 'Sincerely,\n'
        yield name

    @kajiki.expose
    def _fpt_block_body():
        yield 'It was good seeing you last Friday! Thanks for the gift!\n'

    @kajiki.expose
    def __call__():
        yield greet(to)
        yield '\n\n'
        yield self._fpt_block_body()
        yield '\n\n'
        yield sign(from)

Here is the corresponding “child.txt”:

    %extends "parent.txt"
    %def greet(name)
    Dear $name:\
    %end
    %block body
    ${parent_block()}\\

    And don't forget you owe me money!
    %end

This would then yield the following Python:

    @kajiki.expose
    def greet(name):
        yield 'Dear '
        yield name
        yield ':'

    @kajiki.expose
    def _fpt_block_body():
        yield parent._fpt_block_body()
        yield '\n\n'
        yield 'And don\'t forget you owe me money!\n'

    @kajiki.expose
    def __call__():
        yield local.__kj__.extend(local.__kj__.import_('parent.txt')).__call__()

The final text would be (assuming context had to=’Mark’ and from=’Rick’:

    Dear Mark:

    It was good seeing you last Friday! Thanks for the gift!

    And don't forget you owe me money!

    Sincerely,
    Rick