(language)
Cheetah’s basic syntax was inspired by the Java-based template engines Velocity and WebMacro. It has two types of tags: { $placeholders} and { #directives}. Both types are case-sensitive.
Placeholder tags begin with a dollar sign ({$varName}) and are similar to data fields in a form letter or to the {%(key)s} fields on the left side of Python’s {%} operator. When the template is filled, the placeholders are replaced with the values they refer to.
Directive tags begin with a hash character (#) and are used for comments, loops, conditional blocks, includes, and all other advanced features. ({ Note:} you can customize the start and end delimeters for placeholder and directive tags, but in this Guide we’ll assume you’re using the default.)
Placeholders and directives can be escaped by putting a backslash before them. \$var and \#if will be output as literal text.
A placeholder or directive can span multiple physical lines, following the same rules as Python source code: put a backslash (\) at the end of all lines except the last line. However, if there’s an unclosed parenthesis, bracket or brace pending, you don’t need the backslash.
#if $this_is_a_very_long_line and $has_lots_of_conditions \
and $more_conditions:
<H1>bla</H1>
#end if
#if $country in ('Argentina', 'Uruguay', 'Peru', 'Colombia',
'Costa Rica', 'Venezuela', 'Mexico')
<H1>Hola, senorita!</H1>
#else
<H1>Hey, baby!</H1>
#end if
(language.constructs)
The use of all these constructs will be covered in the next several chapters.
(language.placeholders.syntax)
Placeholders follow the same syntax rules as Python variables except that they are preceded by {$} (the short form) or enclosed in {${}} (the long form). Examples:
$var
${var}
$var2.abc['def']('gh', $subplaceholder, 2)
${var2.abc['def']('gh', $subplaceholder, 2)}
We recommend {$} in simple cases, and {${}} when followed directly by a letter or when Cheetah or a human template maintainer might get confused about where the placeholder ends. You may alternately use $() or $[], although this may confuse the (human) template maintainer:
$(var)
$[var]
$(var2.abc['def']('gh', $subplaceholder, 2))
$[var2.abc['def']('gh', $subplaceholder, 2)]
{ Note:} Advanced users can change the delimiters to anything they want via the {#compiler} directive.
{ Note 2:} The long form can be used only with top-level placeholders, not in expressions. See section language.placeholders.positions for an elaboration on this.
To reiterate Python’s rules, placeholders consist of one or more identifiers separated by periods. Each identifier must start with a letter or an underscore, and the subsequent characters must be letters, digits or underscores. Any identifier may be followed by arguments enclosed in () and/or keys/subscripts in [].
Identifiers are case sensitive. {$var} does not equal {$Var} or {$vAr} or {$VAR}.
Arguments inside () or [] are just like in Python. Strings may be quoted using any Python quoting style. Each argument is an expression and may use any of Python’s expression operators. Variables used in argument expressions are placeholders and should be prefixed with {$}. This also applies to the *arg and **kw forms. However, you do { not} need the {$} with the special Python constants {None}, {True} and {False}. Examples:
$hex($myVar)
$func($arg=1234)
$func2($*args, $**kw)
$func3(3.14159, $arg2, None, True)
$myList[$mySubscript]
Trailing periods are ignored. Cheetah will recognize that the placeholder name in {$varName.} is {varName}, and the period will be left alone in the template output.
The syntax {${placeholderName, arg1=”val1”}} passes arguments to the output filter (see {#filter}, section output.filter. The braces and comma are required in this case. It’s conventional to omit the {$} before the keyword arguments (i.e. {arg1}) in this case.
Cheetah ignores all dollar signs ({$}) that are not followed by a letter or an underscore.
The following are valid $placeholders:
$a $_ $var $_var $var1 $_1var $var2_ $dict.key $list[3]
$object.method $object.method() $object.method
$nest($nest($var))
These are not $placeholders but are treated as literal text:
$@var $^var $15.50 $$
(language.placeholders.positions)
There are three places you can use placeholders: top-level position, expression position and LVALUE position. Each has slightly different syntax rules.
Top-level position means interspersed in text. This is the only place you can use the placeholder long form: {${var}}.
{ Expression position} means inside a Cheetah expression, which is the same as a Python expression. The placeholder names a searchList or other variable to be read. Expression position occurs inside () and $[]$ arguments within placeholder tags (i.e., a placeholder inside a placeholder), and in several directive tags.
{ LVALUE position} means naming a variable that will be written to. LVALUE is a computer science term meaning “the left side of an assignment statement”. The first argument of directives {#set}, {#for}, {#def}, {#block} and {#attr} is an LVALUE.
This stupid example shows the three positions. Top-level position is shown in {courier}, expression position is { italic}, and LVALUE position is { bold}.
#for { $count} in { $range}({ $ninetyNine}, 0, -1) #set { $after} = { $count} - 1 {$count} bottles of beer on the wall. {$count} bottles of beer! Take one down, pass it around. {$after} bottles of beer on the wall. #end for {$hex}({ $myVar}, { $default}={ None})
The output of course is:
99 bottles of beer on the wall. 99 bottles of beer!
Take one down, pass it around. 98 bottles of beer on the wall.
98 bottles of beer on the wall. 98 bottles of beer!
Take one down, pass it around. 97 bottles of beer on the wall.
...
(language.placeholders.dollar-signs)
{$} is a “smart variable prefix”. When Cheetah sees {$}, it determines both the variable’s position and whether it’s a searchList value or a non-searchList value, and generates the appropriate Python code.
In top-level position, the {$} is { required}. Otherwise there’s nothing to distinguish the variable from ordinary text, and the variable name is output verbatim.
In expression position, the {$} is { required} if the value comes from the searchList or a “#set global” variable, { recommended} for local/global/builtin variables, and { not necessary} for the special constants {None}, {True} and {False}. This works because Cheetah generates a function call for a searchList placeholder, but a bare variable name for a local/global/builtin variable.
In LVALUE position, the {$} is { recommended}. Cheetah knows where an LVALUE is expected, so it can handle your variable name whether it has {$} or not.
EXCEPTION: Do { not} use the {$} prefix for intermediate variables in a Python list comprehensions. This is a limitation of Cheetah’s parser; it can’t tell which variables in a list comprehension are the intermediate variables, so you have to help it. For example:
#set $theRange = [x ** 2 for x in $range(10)]
{$theRange} is a regular {#set} variable. {$range} is a Python built-in function. But {x} is a scratch variable internal to the list comprehension: if you type {$x}, Cheetah will miscompile it.
(language.namemapper)
One of our core aims for Cheetah was to make it easy for non-programmers to use. Therefore, Cheetah uses a simplified syntax for mapping placeholders in Cheetah to values in Python. It’s known as the { NameMapper syntax} and allows for non-programmers to use Cheetah without knowing (a) the difference between an instance and a dictionary, (b) what functions and methods are, and (c) what ‘self’ is. A side benefit is that you can change the underlying data structure (e.g., instance to dictionary or vice-versa) without having to modify the templates.
NameMapper syntax is used for all variables in Cheetah placeholders and directives. If desired, it can be turned off via the {Template} class’ {‘useNameMapper’} compiler setting. But it’s doubtful you’d ever want to turn it off.
(language.namemapper.example)
Consider this scenario:
You are building a customer information system. The designers with you want to use information from your system on the client’s website -AND- they want to understand the display code and so they can maintian it themselves.
You write a UI class with a ‘customers’ method that returns a dictionary of all the customer objects. Each customer object has an ‘address’ method that returns the a dictionary with information about the customer’s address. The designers want to be able to access that information.
Using PSP, the display code for the website would look something like the following, assuming your servlet subclasses the class you created for managing customer information:
<%= self.customer()[ID].address()['city'] %> (42 chars)
With Cheetah’s NameMapper syntax, you can use any of the following:
$self.customers()[$ID].address()['city'] (39 chars)
--OR--
$customers()[$ID].address()['city']
--OR--
$customers()[$ID].address().city
--OR--
$customers()[$ID].address.city
--OR--
$customers[$ID].address.city (27 chars)
Which of these would you prefer to explain to the designers, who have no programming experience? The last form is 15 characters shorter than the PSP version and - conceptually - far more accessible. With PHP or ASP, the code would be even messier than with PSP.
This is a rather extreme example and, of course, you could also just implement {$getCustomer($ID).city} and obey the Law of Demeter (search Google for more on that). But good object orientated design isn’t the point of this example.
(language.namemapper.dict)
NameMapper syntax allows access to dictionary items with the same dotted notation used to access object attributes in Python. This aspect of NameMapper syntax is known as ‘Unified Dotted Notation’. For example, with Cheetah it is possible to write:
$customers()['kerr'].address() --OR-- $customers().kerr.address()
where the second form is in NameMapper syntax.
This works only with dictionary keys that also happen to be valid Python identifiers.
(language.namemapper.autocalling)
Cheetah automatically detects functions and methods in Cheetah $variables and calls them if the parentheses have been left off. Our previous example can be further simplified to:
$customers.kerr.address
As another example, if ‘a’ is an object, ‘b’ is a method
$a.b
is equivalent to
$a.b()
If b returns a dictionary, then following variations are possible
$a.b.c --OR-- $a.b().c --OR-- $a.b()['c']
where ‘c’ is a key in the dictionary that a.b() returns.
Further notes:
(language.searchList)
When Cheetah maps a variable name in a template to a Python value, it searches several namespaces in order:
The first matching name found is used.
Remember, these namespaces apply only to the { first} identifier after the {$}. In a placeholder like {$a.b}, only ‘a’ is looked up in the searchList and other namespaces. ‘b’ is looked up only inside ‘a’.
A searchList container can be any Python object with attributes or keys: dictionaries, instances, classes or modules. If an instance contains both attributes and keys, its attributes are searched first, then its keys.
Because the {Template} instance is part of the searchList, you can access its attributes/methods without ‘self’: {$myAttr}. However, use the ‘self’ if you want to make sure you’re getting the {Template} attribute and not a same-name variable defined in a higher namespace: {$self.myAttr}. This works because “self” itself is a local variable.
The final resulting value, after all lookups and function calls (but before the filter is applied) is called the { placeholder value}, no matter which namespace it was found in.
{ { Note carefully:}} if you put an object ‘myObject’ in the searchList, you { cannot} look up {$myObject}! You can look up only the attributes/keys { inside} ‘myObject’.
Earlier versions of Cheetah did not allow you to override Python builtin names, but this was fixed in Cheetah 0.9.15.
If your template will be used as a Webware servlet, do not override methods ‘name’ and ‘log’ in the {Template} instance or it will interfere with Webware’s logging. However, it { is} OK to use those variables in a higher namespace, since Webware doesn’t know about Cheetah namespaces.
(language.namemapper.missing)
If NameMapper can not find a Python value for a Cheetah variable name, it will raise the NameMapper.NotFound exception. You can use the {#errorCatcher} directive (section errorHandling.errorCatcher) or { errorCatcher} Template constructor argument (section howWorks.constructing) to specify an alternate behaviour. BUT BE AWARE THAT errorCatcher IS ONLY INTENDED FOR DEBUGGING!
To provide a default value for a placeholder, write it like this: {$getVar(‘varName’, ‘default value’)}. If you don’t specify a default and the variable is missing, {NameMapper.NotFound} will be raised.
(language.directives.syntax)
Directive tags begin with a hash character (#) and are used for comments, loops, conditional blocks, includes, and all other advanced features. Cheetah uses a Python-like syntax inside directive tags and understands any valid Python expression. { However, unlike Python, Cheetah does not use colons (:) and indentation to mark off multi-line directives.} That doesn’t work in an environment where whitespace is significant as part of the text. Instead, multi-line directives like {#for} have corresponding closing tags ({#end for}). Most directives are direct mirrors of Python statements.
Many directives have arguments after the opening tag, which must be in the specified syntax for the tag. All end tags have the following syntax:
#end TAG_NAME [EXPR]
The expression is ignored, so it’s essentially a comment.
(language.directives.closures) Directive tags can be closed explicitly with {#}, or implicitly with the end of the line if you’re feeling lazy.
#block testBlock #
Text in the body of the
block directive
#end block testBlock #
is identical to:
#block testBlock
Text in the body of the
block directive
#end block testBlock
When a directive tag is closed explicitly, it can be followed with other text on the same line:
bah, bah, #if $sheep.color == 'black'# black#end if # sheep.
When a directive tag is closed implicitly with the end of the line, all trailing whitespace is gobbled, including the newline character:
"""
foo #set $x = 2
bar
"""
outputs
"""
foo bar
"""
while
"""
foo #set $x = 2 #
bar
"""
outputs
"""
foo
bar
"""
When a directive tag is closed implicitly AND there is no other text on the line, the ENTIRE line is gobbled up including any preceeding whitespace:
"""
foo
#set $x = 2
bar
"""
outputs
"""
foo
bar
"""
while
"""
foo
- #set $x = 2
bar
"""
outputs
"""
foo
- bar
"""
The {#slurp} directive (section output.slurp) also gobbles up whitespace.
Spaces outside directives are output { exactly} as written. In the black sheep example, there’s a space before “black” and another before “sheep”. So although it’s legal to put multiple directives on one line, it can be hard to read.
#if $a# #echo $a + 1# #end if
- There's a space between each directive,
or two extra spaces total.
#if $a##echo $a + 1##end if
- No spaces, but you have to look closely
to verify none of the ``##'' are comment markers.
#if $a##echo $a + 1##end if ### A comment.
- In ``###'', the first ``#'' ends the directive,
the other two begin the comment. (This also shows
how you can add extra whitespace in the directive
tag without affecting the output.)
#if $a##echo $a + 1##end if # ## A comment.
- More readable, but now there's a space before the
comment.