It’s sometimes good to have a mental model of the Python code that Kajiki generates 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.
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.
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
This can be quite inconvient, however. 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.
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'
%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'
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."
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?
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