"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

---