"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "docs/users_guide/language.rst" between
cheetah3-3.1.0.tar.gz and cheetah3-3.2.0.tar.gz

About: Cheetah3 is a template engine and code generation tool for e.g. for Web development or Java, SQL, LaTeX, form email ... (written in Python).

language.rst  (cheetah3-3.1.0):language.rst  (cheetah3-3.2.0)
.. role:: math(raw) .. role:: math(raw)
:format: html latex :format: html latex
Language Overview Language Overview
================= =================
(language)
Cheetah's basic syntax was inspired by the Java-based template Cheetah's basic syntax was inspired by the Java-based template
engines Velocity and WebMacro. It has two types of tags: { engines Velocity and WebMacro. It has two types of tags: {
$placeholders} and { #directives}. Both types are case-sensitive. $placeholders} and { #directives}. Both types are case-sensitive.
Placeholder tags begin with a dollar sign ({$varName}) and are Placeholder tags begin with a dollar sign ({$varName}) and are
similar to data fields in a form letter or to the {%(key)s} fields 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 on the left side of Python's {%} operator. When the template is
filled, the placeholders are replaced with the values they refer filled, the placeholders are replaced with the values they refer
to. to.
skipping to change at line 52 skipping to change at line 50
#if $country in ('Argentina', 'Uruguay', 'Peru', 'Colombia', #if $country in ('Argentina', 'Uruguay', 'Peru', 'Colombia',
'Costa Rica', 'Venezuela', 'Mexico') 'Costa Rica', 'Venezuela', 'Mexico')
<H1>Hola, senorita!</H1> <H1>Hola, senorita!</H1>
#else #else
<H1>Hey, baby!</H1> <H1>Hey, baby!</H1>
#end if #end if
Language Constructs - Summary Language Constructs - Summary
----------------------------- -----------------------------
(language.constructs)
#. Comments and documentation strings #. Comments and documentation strings
#. {## single line} #. {## single line}
#. {#\* multi line \*#} #. {#\* multi line \*#}
#. Generation, caching and filtering of output #. Generation, caching and filtering of output
#. plain text #. plain text
skipping to change at line 174 skipping to change at line 170
{#encoding} {#encoding}
#. set the sh-bang line of compiled template modules: {#shBang} #. set the sh-bang line of compiled template modules: {#shBang}
The use of all these constructs will be covered in the next several The use of all these constructs will be covered in the next several
chapters. chapters.
Placeholder Syntax Rules Placeholder Syntax Rules
------------------------ ------------------------
(language.placeholders.syntax)
- Placeholders follow the same syntax rules as Python variables - Placeholders follow the same syntax rules as Python variables
except that they are preceded by {$} (the short form) or enclosed except that they are preceded by {$} (the short form) or enclosed
in {${}} (the long form). Examples: in {${}} (the long form). Examples:
:: ::
$var $var
${var} ${var}
$var2.abc['def']('gh', $subplaceholder, 2) $var2.abc['def']('gh', $subplaceholder, 2)
${var2.abc['def']('gh', $subplaceholder, 2)} ${var2.abc['def']('gh', $subplaceholder, 2)}
skipping to change at line 261 skipping to change at line 255
These are not $placeholders but are treated as literal text: These are not $placeholders but are treated as literal text:
:: ::
$@var $^var $15.50 $$ $@var $^var $15.50 $$
Where can you use placeholders? Where can you use placeholders?
------------------------------- -------------------------------
(language.placeholders.positions)
There are three places you can use placeholders: top-level There are three places you can use placeholders: top-level
position, expression position and LVALUE position. Each has position, expression position and LVALUE position. Each has
slightly different syntax rules. slightly different syntax rules.
Top-level position means interspersed in text. This is the only Top-level position means interspersed in text. This is the only
place you can use the placeholder long form: {${var}}. place you can use the placeholder long form: {${var}}.
{ Expression position} means inside a Cheetah expression, which is { Expression position} means inside a Cheetah expression, which is
the same as a Python expression. The placeholder names a searchList the same as a Python expression. The placeholder names a searchList
or other variable to be read. Expression position occurs inside () or other variable to be read. Expression position occurs inside ()
skipping to change at line 307 skipping to change at line 299
99 bottles of beer on the wall. 99 bottles of beer! 99 bottles of beer on the wall. 99 bottles of beer!
Take one down, pass it around. 98 bottles of beer on the wall. Take one down, pass it around. 98 bottles of beer on the wall.
98 bottles of beer on the wall. 98 bottles of beer! 98 bottles of beer on the wall. 98 bottles of beer!
Take one down, pass it around. 97 bottles of beer on the wall. Take one down, pass it around. 97 bottles of beer on the wall.
... ...
Are all those dollar signs really necessary? Are all those dollar signs really necessary?
-------------------------------------------- --------------------------------------------
(language.placeholders.dollar-signs)
{$} is a "smart variable prefix". When Cheetah sees {$}, it {$} is a "smart variable prefix". When Cheetah sees {$}, it
determines both the variable's position and whether it's a determines both the variable's position and whether it's a
searchList value or a non-searchList value, and generates the searchList value or a non-searchList value, and generates the
appropriate Python code. appropriate Python code.
In top-level position, the {$} is { required}. Otherwise there's In top-level position, the {$} is { required}. Otherwise there's
nothing to distinguish the variable from ordinary text, and the nothing to distinguish the variable from ordinary text, and the
variable name is output verbatim. variable name is output verbatim.
In expression position, the {$} is { required} if the value comes In expression position, the {$} is { required} if the value comes
skipping to change at line 345 skipping to change at line 335
#set $theRange = [x ** 2 for x in $range(10)] #set $theRange = [x ** 2 for x in $range(10)]
{$theRange} is a regular {#set} variable. {$range} is a Python {$theRange} is a regular {#set} variable. {$range} is a Python
built-in function. But {x} is a scratch variable internal to the built-in function. But {x} is a scratch variable internal to the
list comprehension: if you type {$x}, Cheetah will miscompile it. list comprehension: if you type {$x}, Cheetah will miscompile it.
NameMapper Syntax NameMapper Syntax
----------------- -----------------
(language.namemapper)
One of our core aims for Cheetah was to make it easy for One of our core aims for Cheetah was to make it easy for
non-programmers to use. Therefore, Cheetah uses a simplified syntax non-programmers to use. Therefore, Cheetah uses a simplified syntax
for mapping placeholders in Cheetah to values in Python. It's known for mapping placeholders in Cheetah to values in Python. It's known
as the { NameMapper syntax} and allows for non-programmers to use as the { NameMapper syntax} and allows for non-programmers to use
Cheetah without knowing (a) the difference between an instance and Cheetah without knowing (a) the difference between an instance and
a dictionary, (b) what functions and methods are, and (c) what a dictionary, (b) what functions and methods are, and (c) what
'self' is. A side benefit is that you can change the underlying 'self' is. A side benefit is that you can change the underlying
data structure (e.g., instance to dictionary or vice-versa) without data structure (e.g., instance to dictionary or vice-versa) without
having to modify the templates. having to modify the templates.
NameMapper syntax is used for all variables in Cheetah placeholders NameMapper syntax is used for all variables in Cheetah placeholders
and directives. If desired, it can be turned off via the {Template} and directives. If desired, it can be turned off via the {Template}
class' {'useNameMapper'} compiler setting. But it's doubtful you'd class' {'useNameMapper'} compiler setting. But it's doubtful you'd
ever want to turn it off. ever want to turn it off.
Example Example
~~~~~~~ ~~~~~~~
(language.namemapper.example)
Consider this scenario: Consider this scenario:
You are building a customer information system. The designers with You are building a customer information system. The designers with
you want to use information from your system on the client's you want to use information from your system on the client's
website -AND- they want to understand the display code and so they website -AND- they want to understand the display code and so they
can maintian it themselves. can maintian it themselves.
You write a UI class with a 'customers' method that returns a You write a UI class with a 'customers' method that returns a
dictionary of all the customer objects. Each customer object has an dictionary of all the customer objects. Each customer object has an
'address' method that returns the a dictionary with information 'address' method that returns the a dictionary with information
skipping to change at line 417 skipping to change at line 403
with PSP. with PSP.
This is a rather extreme example and, of course, you could also This is a rather extreme example and, of course, you could also
just implement {$getCustomer($ID).city} and obey the Law of Demeter just implement {$getCustomer($ID).city} and obey the Law of Demeter
(search Google for more on that). But good object orientated design (search Google for more on that). But good object orientated design
isn't the point of this example. isn't the point of this example.
Dictionary Access Dictionary Access
~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
(language.namemapper.dict)
NameMapper syntax allows access to dictionary items with the same NameMapper syntax allows access to dictionary items with the same
dotted notation used to access object attributes in Python. This dotted notation used to access object attributes in Python. This
aspect of NameMapper syntax is known as 'Unified Dotted Notation'. aspect of NameMapper syntax is known as 'Unified Dotted Notation'.
For example, with Cheetah it is possible to write: For example, with Cheetah it is possible to write:
:: ::
$customers()['kerr'].address() --OR-- $customers().kerr.address() $customers()['kerr'].address() --OR-- $customers().kerr.address()
where the second form is in NameMapper syntax. where the second form is in NameMapper syntax.
This works only with dictionary keys that also happen to be valid This works only with dictionary keys that also happen to be valid
Python identifiers. Python identifiers.
Autocalling Autocalling
~~~~~~~~~~~ ~~~~~~~~~~~
(language.namemapper.autocalling)
Cheetah automatically detects functions and methods in Cheetah Cheetah automatically detects functions and methods in Cheetah
$variables and calls them if the parentheses have been left off. $variables and calls them if the parentheses have been left off.
Our previous example can be further simplified to: Our previous example can be further simplified to:
:: ::
$customers.kerr.address $customers.kerr.address
As another example, if 'a' is an object, 'b' is a method As another example, if 'a' is an object, 'b' is a method
skipping to change at line 495 skipping to change at line 477
{.\_\_call\_\_()} method to {.\_\_str\_\_}. {.\_\_call\_\_()} method to {.\_\_str\_\_}.
- Autocalling can be disabled via Cheetah's 'useAutocalling' - Autocalling can be disabled via Cheetah's 'useAutocalling'
compiler setting. You can also disable it for one placeholder by compiler setting. You can also disable it for one placeholder by
using the syntax {$getVar('varName', 'default value', False)}. using the syntax {$getVar('varName', 'default value', False)}.
({.getVar()} works only with searchList values.) ({.getVar()} works only with searchList values.)
Namespace cascading and the searchList Namespace cascading and the searchList
-------------------------------------- --------------------------------------
(language.searchList)
When Cheetah maps a variable name in a template to a Python value, When Cheetah maps a variable name in a template to a Python value,
it searches several namespaces in order: it searches several namespaces in order:
#. { Local variables:} created by {#set}, {#for}, or predefined by #. { Local variables:} created by {#set}, {#for}, or predefined by
Cheetah. Cheetah.
#. The { searchList}, consisting of: #. The { searchList}, consisting of:
#. {#set global} variables. #. {#set global} variables.
skipping to change at line 560 skipping to change at line 540
If your template will be used as a Webware servlet, do not override If your template will be used as a Webware servlet, do not override
methods 'name' and 'log' in the {Template} instance or it will methods 'name' and 'log' in the {Template} instance or it will
interfere with Webware's logging. However, it { is} OK to use those interfere with Webware's logging. However, it { is} OK to use those
variables in a higher namespace, since Webware doesn't know about variables in a higher namespace, since Webware doesn't know about
Cheetah namespaces. Cheetah namespaces.
Missing Values Missing Values
-------------- --------------
(language.namemapper.missing)
If NameMapper can not find a Python value for a Cheetah variable If NameMapper can not find a Python value for a Cheetah variable
name, it will raise the NameMapper.NotFound exception. You can use name, it will raise the NameMapper.NotFound exception. You can use
the {#errorCatcher} directive (section errorHandling.errorCatcher) the {#errorCatcher} directive (section errorHandling.errorCatcher)
or { errorCatcher} Template constructor argument (section or { errorCatcher} Template constructor argument (section
howWorks.constructing) to specify an alternate behaviour. BUT BE howWorks.constructing) to specify an alternate behaviour. BUT BE
AWARE THAT errorCatcher IS ONLY INTENDED FOR DEBUGGING! AWARE THAT errorCatcher IS ONLY INTENDED FOR DEBUGGING!
To provide a default value for a placeholder, write it like this: To provide a default value for a placeholder, write it like this:
{$getVar('varName', 'default value')}. If you don't specify a {$getVar('varName', 'default value')}. If you don't specify a
default and the variable is missing, {NameMapper.NotFound} will be default and the variable is missing, {NameMapper.NotFound} will be
raised. raised.
Directive Syntax Rules Directive Syntax Rules
---------------------- ----------------------
(language.directives.syntax)
Directive tags begin with a hash character (#) and are used for Directive tags begin with a hash character (#) and are used for
comments, loops, conditional blocks, includes, and all other comments, loops, conditional blocks, includes, and all other
advanced features. Cheetah uses a Python-like syntax inside advanced features. Cheetah uses a Python-like syntax inside
directive tags and understands any valid Python expression. { directive tags and understands any valid Python expression. {
However, unlike Python, Cheetah does not use colons (:) and However, unlike Python, Cheetah does not use colons (:) and
indentation to mark off multi-line directives.} That doesn't work indentation to mark off multi-line directives.} That doesn't work
in an environment where whitespace is significant as part of the in an environment where whitespace is significant as part of the
text. Instead, multi-line directives like {#for} have corresponding text. Instead, multi-line directives like {#for} have corresponding
closing tags ({#end for}). Most directives are direct mirrors of closing tags ({#end for}). Most directives are direct mirrors of
Python statements. Python statements.
 End of changes. 12 change blocks. 
24 lines changed or deleted 0 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)