\section{Language Overview}
\label{language}

Cheetah's basic syntax was inspired by the Java-based template engines Velocity
and WebMacro. It has two types of tags: {\bf \$placeholders} and {\bf
\#directives}.  Both types are case-sensitive.  

Placeholder tags begin with a dollar sign (\code{\$varName}) and are similar to
data fields in a form letter or to the \code{\%(key)s} fields on the left side
of Python's \code{\%} 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. 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 \code{\#for} have  corresponding closing tags
 (\code{\#end for}).  Most directives are direct mirrors of Python statements.

Cheetah does not use HTML/XML-style tags like some other template languages for
the following reasons:
 Cheetah is not limited to HTML,
 HTML-style tags are hard to distinguish from real HTML tags,
 HTML-style tags are not visible in rendered HTML when something goes wrong,
 HTML-style tags often lead to invalid HTML (e.g., 
\code{<img src="<template-directive>">}),
Cheetah tags are less verbose and easier to understand than HTML-style tags, 
and HTML-style tags aren't compatible with most WYSIWYG editors

Besides being much more compact, Cheetah also has some advantages over
languages that put information inside the HTML tags, such as Zope Page
Templates or PHP:
 HTML or XML-bound languages do not work well with other languages,
 While ZPT-like syntaxes work well in many ways with WYSIWYG HTML editors,
     they also give up a significant advantage of those editors -- concrete
     editing of the document.  When logic is hidden away in (largely
     inaccessible) tags it is hard to understand a page simply by viewing it,
     and it is hard to confirm or modify that logic.

Placeholders and directives can be escaped by putting a backslash before them.
\verb+\$var+ and \verb+\#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 (\verb+\+) 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.

\begin{verbatim}
#if $this_is_a_very_long_line and $has_lots_of_conditions \
    and $more_conditions:
<h1>bla</h1>
#elif $country in ('Argentina', 'Uruguay', 'Brazil', 'Peru', 'Colombia',
    'Costa Rica', 'Venezuela', 'Mexico')
<h1>hola, senorita!</h1>
#end if
\end{verbatim}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Language Constructs -- Summary}
\label{language.constructs}

\begin{enumerate}
\item Comments and documentation strings
     \begin{enumerate}
     \item \code{\#\# single line}
     \item \code{\#* multi line *\#}
     \end{enumerate}

\item Generation, caching and filtering of output
     \begin{enumerate}
     \item plain text
     \item output from simple expressions: \code{\$placeholders}
     \item output from more complex expressions: \code{\#echo} \ldots
     \item silencing output from expressions: \code{\#silent} \ldots
     \item gobble the EOL: \code{\#slurp}
     \item parsed file includes: \code{\#include} \ldots
     \item raw file includes: \code{\#include raw} \ldots
     \item verbatim output of Cheetah code: \code{\#raw} \ldots \code{\#end raw}
     \item cached placeholders: \code{\$*var}, \code{\$*<interval>*var}
     \item cached regions: \code{\#cache} \ldots \code{\#cache}
     \item set the output filter: \code{\#filter} \ldots
     \end{enumerate}
          
\item Importing Python modules and objects: \code{\#import} \ldots,
     \code{\#from} \ldots

\item Inheritance 
     \begin{enumerate}
     \item set the base classes to inherit from: \code{\#extends}
     \item set the name of the main method to implement: \code{\#implements} \ldots
     \end{enumerate}

\item Compile-time declaration
     \begin{enumerate}
     \item define class attributes: \code{\#attr} \ldots
     \item define class methods: \code{\#def} \ldots \code{\#end def}
     \item \code{\#block} \ldots \code{\#end block} provides a simplified
          interface to \code{\#def} \ldots \code{\#end def}
     \end{enumerate}

\item Run-time assignment
     \begin{enumerate}
     \item local vars: \code{\#set} \ldots
     \item global vars: \code{\#set global} \ldots
     \end{enumerate}

\item Flow control
     \begin{enumerate}
     \item \code{\#if} \ldots \code{\#else} \ldots \code{\#else if} (aka
          \code{\#elif}) \ldots \code{\#end if}
     \item \code{\#unless} \ldots \code{\#end unless}
     \item \code{\#for} \ldots \code{\#end for}
     \item \code{\#repeat} \ldots \code{\#end repeat}
     \item \code{\#while} \ldots \code{\#end while}
     \item \code{\#break}
     \item \code{\#continue}
     \item \code{\#pass}
     \item \code{\#return}
     \item \code{\#stop}
     \end{enumerate}

\item error/exception handling
     \begin{enumerate}
     \item \code{\#assert}
     \item \code{\#raise}
     \item \code{\#try} \ldots \code{\#except} \ldots \code{\#else} \ldots
          \code{\#end try} 
     \item \code{\#try} \ldots \code{\#finally} \ldots \code{\#end try}
     \item \code{\#errorCatcher} \ldots sets a default exception
          catcher/handler for exceptions raised by \$placeholder calls.
     \end{enumerate}

\item Instructions to the parser/compiler
     \begin{enumerate}
     \item \code{\#breakpoint}
     \item \code{\#compiler-settings} \ldots \code{\#end compiler-settings}
     \end{enumerate}
\end{enumerate}

Cheetah also supports two PSP (Python Server Pages) style tags as escapes to
pure Python code. These are not part of Cheetah's core language, but are
included to facilitate migration from PSP-style markup languages to Cheetah.
These tags may not be used inside other Cheetah tags.
\begin{enumerate}
\item evalute expression and print the output: \code{<\%=} \ldots \code{\%>} 
\item execute code and discard output: \code{<\%} \ldots \code{\%>}
\end{enumerate}

The use of all these directives will be covered in the next few chapters.

%% @@MO: TODO: reconcile the order of this summary with the order in the
%% detail sections.

% @@MO: PSP chapter with examples.  What does write() do?  Print?

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Placeholder Syntax Rules}
\label{language.placeholders.syntax}

\begin{itemize} 

\item Placeholders follow the same syntax rules as Python variables except
     that they are preceded by \code{\$} (the short form) or enclosed in
     \code{\$\{\}} (the long form).
     Examples:
\begin{verbatim}
$var                                        
${var}                                      
$var2.abc['def']('gh', $subplaceholder, 2)  
${var2.abc['def']('gh', $subplaceholder, 2)}
\end{verbatim}
     We recommend \code{\$} in simple cases, and \code{\$\{\}} when followed
     directly by a letter or when Cheetah or a human template maintainer might
     get confused about where the placeholder ends.  Cheetah also allows you
     to enclose the placeholder in \verb+$()+ or \verb+$[]+, although this may
     make it harder for the maintainer to see where the placeholder begins and
     ends:
\begin{verbatim}
$(var)                                      
$[var]                                      
$(var2.abc['def']('gh', $subplaceholder, 2))
$[var2.abc['def']('gh', $subplaceholder, 2)]
\end{verbatim}
     {\em Note:} Advanced users can change the delimiters to anything they
     want via the \code{\#compiler} directive.

     {\em Note 2:} The long form can be used only when the placeholder is
     in ordinary text (called ``placeholder position'' below), not when it's
     part of a directive argument or expression.

\item To reiterate Python's rules, placeholders consist of one or more
     components separated by periods.  Each component must start with a letter
     or an underCheetah Developers' Guidescore, and the subsequent characters must be letters, digits or
     underscores.  Any component may be followed by argument sets enclosed in
     \verb+()+ and/or key/subscript arguments in \verb+[]$+.

\item Components are case sensitive. \code{\$var} does not equal \code{\$Var}
     or \code{\$vAr} or \code{\$VAR}.     
     
\item Arguments inside \verb+()+ or \verb+$[]$+ 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
    \code{\$}.  This also applies to the *arg and **kw forms.  However, you do
    {\em not} need the \code{\$} with the special Python constants \code{None},
    \code{True} and \code{False}.
     Examples:
\begin{verbatim}
$hex($myVar)
$func($arg=1234)
$func2($*args, $**kw)
$func3(3.14159, $arg2, None, True)
$myList[$mySubscript]
\end{verbatim}
    
\item Trailing periods are ignored.  Cheetah will recognize that the placeholder
     name in \code{\$varName.} is \code{varName}, and the period will be left
     alone in the template output.
     
\item The syntax \code{\$\{placeholderName, arg1="val1"\}} passes arguments to
     the output filter (see \code{\#filter}, section \ref{output.filter}.
     The braces and comma are required in this case.  Note that you don't need
     the \code{\$} prefix in this case since filter arguments are not ordinary
     method arguments, and omiting the \code{\$} reminds you of this fact.
     However, you may use \code{\$} anyway if you wish.

\item EXCEPTION: You must {\em not} use the \code{\$} 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:
\begin{verbatim}
#set $theRange = [x ** 2 for x in $range(10)]
\end{verbatim}
     \code{\$theRange} is a regular \code{\#set} variable.  \code{\$range} is a
     Python built-in function.  But \code{x} is a scratch variable internal to
     the list comprehension: if you type \code{\$x}, Cheetah will miscompile it.

\item Cheetah ignores all dollar signs (\code{\$}) that are not followed by a
     letter or an underscore.
     
\end{itemize} 

The following are valid \$placeholders:
\begin{verbatim}
$a $_ $var $_var $var1 $_1var $var2_ $dict.key $list[3]
$object.method $object.method() $object.method
$nest($nest($var))
\end{verbatim}

These are not \$placeholders but are treated as literal text:
\begin{verbatim}
$@var $^var $15.50 $$
\end{verbatim}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Where can you use placeholders?}
\label{language.placeholders.positions}

There are three places you can use placeholders.  One is {\em placeholder
position}, which means interspersed in ordinary text.  (This is the only place
you can use the placeholder long form: \code{\$\{var\}}.)  The other two positions
are expression position and LVALUE position.

{\em Expression position} means inside a Cheetah expression, which is the same
as a Python expression.  The placeholder names a searchList or other variable
which is read.  Expression position occurs inside () and $[]$ arguments within
placeholder tags (i.e., a placeholder inside a placeholder), and in several
directive tags.

{\em LVALUE position} means naming a variable which will be written to.  LVALUE
is a computer science term meaning ``the left side of an assignment 
statement''.  The first argument of directives \code{\#set}, \code{\#for},
\code{\#def}, \code{\#block} and \code{\#attr} is an LVALUE.

This stupid example shows the three positions.  Placeholder position is shown
in \code{courier}, expression position is {\em italic}, and LVALUE position is
{\bf bold}.

\begin{quote}
\#for {\bf \$count} in {\em \$range}({\em \$ninetyNine}, 0, -1)\\
\#set {\bf \$after} = {\em \$count} - 1\\
\code{\$count} bottles of beer on the wall.  \code{\$count} bottles of beer!\\
~~~~Take one down, pass it around.  \code{\$after} bottles of beer on the wall.\\
\#end for\\
\code{\$hex}({\em \$myVar}, {\bf \$default}={\em None})
\end{quote}

The output of course is:
\begin{verbatim}
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.
...
\end{verbatim}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Are all those dollar signs really necessary?}
\label{language.placeholders.dollar-signs}

If you value simplicity, just follow the \code{\$} rules above and skip this
section.  If you don't like that many dollar signs, read on.

\code{\$} is a ``smart variable prefix''.  When Cheetah sees \code{\$}, 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 placeholder position, the \code{\$} is {\em required}.  Otherwise there's
nothing to distinguish the variable from ordinary text, and the variable name
is output verbatim.

In expression position, the \code{\$} is {\em required} if the value comes from
the searchList, {\em recommended} for local/global/builtin variables, and 
{\em not necessary} for the special constants \code{None}, \code{True} and
\code{False}.  This works because Cheetah generates a function call for a
searchList placeholder, but a bare variable name for a local/global/builtin
variable.  The bare variable name happens to be what you get if you remove the
delimiters from the placeholder, so this works.

In LVALUE position, the \code{\$} is {\em recommended}.  Cheetah knows where
an LVALUE is expected, so it can handle your variable name whether it has
\code{\$} or not.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{NameMapper Syntax}
\label{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 variable
names in Cheetah to values in Python. It's known as the{\bf NameMapper syntax}
and allows for non-programmers to use Cheetah without knowing (a)
the difference between an object and a dictionary, (b) what functions
and methods are, and (c) what 'self' is. A side benefit is that NameMapper
syntax insulates the code in Cheetah templates from changes in the implementation
of the Python data structures behind them.

NameMapper syntax is used for all variables in Cheetah placeholders and
directives. If desired, it can be turned off via the \code{Template} class'
\code{'useNameMapper'} compiler setting.  But it's doubtful you'd ever want to
turn it off.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Example}
\label{language.namemapper.example}

Consider this scenario:

You've been hired as a consultant to design and implement a customer information
system for your client. The class you create has 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 working for your client want to use information from your system
on the client's website --AND-- they want to maintain the display code
themselves.

Using PSP, the display code for the website would look something like this,
assuming your servlet is a subclass of your customer class:


\begin{verbatim}
  <%= self.customer()[ID].address()['city'] %>   (42 chars)
\end{verbatim}

With Cheetah's NameMapper syntax, you can use any of the following:

\begin{verbatim}
   $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
   --OR--
   $customers[$ID].address.city                   (27 chars)                     
\end{verbatim}   

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
\code{\$customer(\$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.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Dictionary Access}
\label{language.namemapper.dict}

NameMapper syntax allows access to dictionary items using 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:
\begin{verbatim}
   $customers()['kerr'].address()  --OR--  $customers().kerr.address()
\end{verbatim}
where the second form is in NameMapper syntax.

This works only with dictionary keys that are also valid Python components.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Autocalling}
\label{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:
\begin{verbatim}
  $customers.kerr.address
\end{verbatim}

As another example, if 'a' is an object, 'b' is a method
\begin{verbatim}
  $a.b
\end{verbatim}

is equivalent to

\begin{verbatim}
  $a.b()
\end{verbatim}

If b returns a dictionary, then following variations are possible
\begin{verbatim}
  $a.b.c  --OR--  $a.b().c  --OR--  $a.b()['c']
\end{verbatim}
where 'c' is a key in the dictionary that a.b() returns.

Further notes:
\begin{itemize}
\item When Cheetah autocalls a function/method, it calls it without any
arguments.  Thus, the function/method must have been declared without arguments
(except \code{self} for methods) or to provide default values for all arguments.
If the function requires arguments, you must use the \code{()}.

\item Cheetah autocalls only functions and methods.  Classes and other callable
objects are not autocalled.  The reason is that the primary purpose of a
function/method is to call it, whereas the primary purpose of an instance is to
look up its attributes or call its methods, not to call the instance itself.
And calling a class may allocate large sums of memory uselessly or have other
side effects, depending on the class.  For instance, consider
\code{\$myInstance.fname}.
Do we want to look up \code{fname} in the namespace of \code{myInstance} or
in the namespace of whatever \code{myinstance} returns?  It could go either way,
and Cheetah can't tell.  So Cheetah follows the principle of least surprise and
doesn't autocall instances.  If you {\em do} want to call the instance, do
{\em \$myInstance.\_\_call\_\_}.  If that's too inconvenient/ugly for you,
rename the method to \code{.\_\_str\_\_}, and it will be invoked any time 
\code{\$myInstance} is used as a placeholder.  Note, however, that if
\code{\$myInstance} is in an expression rather than being a placeholder,
\code{.\_\_str\_\_} will not be invoked.  Of course, you can always use
\code{()} to force the calling in any case: \code{\$myInstance()}.

\item Autocalling can be disabled via Cheetah's 'useAutocalling' compiler
setting.
\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Underscored attributes}
\label{language.namemapper.underscore}

If a 'name' in Cheetah doesn't correspond to a valid object attribute name in
Python, but there is an attribute in the form '\_name', NameMapper will return
the underscored attribute.

This removes the need to change all placeholders like \code{\$clients.list} to
\code{\$clients.\_list} when the 'list' attribute of 'clients' is changed to or
from an underscored attribute.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Namespace cascading and the searchList}
\label{language.searchList}

When Cheetah maps a variable name in a template to a Python value, it searches
through a list of namespaces known as the Template object's \code{searchList}.
By default, the only namespace in the \code{searchList} is the template object
itself. This means that its attributes or methods can be accessed in templates
via \code{\$placeholders} without needing to include 'self' in the reference as
you do in Python. 

The looked-up values are called {\bf placeholder values}, because they are what
a placeholder evaluates to.  If the value comes from the searchList, it's called
a \code{searchList} variable.

The \code{searchList} can be used to override or supplement the variables in the
template object's namespace without needing to create a subclass.  When Cheetah
fills in \code{\$myVar} it searches sequentially through the searchList until it
finds a value for \code{myVar}.  Thus, if three namespaces are loaded and two of
them contain a value for \code{\$myVar}, the value for \code{myVar} from the
namespace that is closest to the start of the searchList will be returned.

If you add a Python object to the searchList, its attributes and methods will
be accessible as \$placeholder names.  If the object is a dictionary, its keys
are accessible as if they were attributes.  For example, \code{myObject}
contains \code{myAttrib} and \code{myMethod}.  If \code{myObject} is added to
the searchList, \code{\$myAttrib} and \code{\$myMethod} can be used as
placeholder names.

The\code{\_\_init\_\_} method of the \code{Template} class, and the subclasses
generated by the Cheetah compiler, accept a list of namespaces that will be
added to the start of the \code{searchList}.  Extra namespaces can be added to
the end of the searchList at at any time using the
\code{.addToSearchList()} method, and to the beginning by
\code{.prependToSearchList()}, both defined in \code{Template}.

Note that if you place an object on the searchList, you cannot look up that
object itself by name.  You can only look up the attributes/keys {\em inside}
that object.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Local variables}
\label{language.localVariables}

The following names are accessible by \code{\$placeholders}, even though they
are not in the searchList:  

\begin{enumerate}
\item \code{\#set} variables and \code{\#set global} variables.
\item \code{\#for} loop counters.
\item the template object's \code{self} (i.e., \code{\$self.attrib1}).
\item Python's built-in functions and objects (everything in module
     \code{\_\_builtin\_\_}, \code{None}, etc).
\end{enumerate}

These are in fact local variables in the generated class method.  The compiler
can tell by context which \code{\$placeholders} should be looked up in the
searchList and which are local variables, so it generates the appropriate
Python lookup code for either case.  The compiler can also tell when to do
NameMapper lookup on a local variable; e.g.:
\begin{verbatim}
#for $client in $clients 
$client.name
#end for
\end{verbatim}
The compiler knows that \code{\$client} is a local variable because it's a
\code{\#for} loop counter.  The compiler also knows it has to do NameMapper
lookup on the \code{.name} suffix in case it's a dictionary key or 
autocallable.  So the compiler generates the appropriate Python code.

If you want to make absolutely sure that you are accessing an attribute or
method of the template object, include 'self' in the reference:
\code{\$self.attrib1} instead of \code{\$attrib1}.  (\code{\$self.attrib1}, it's
a local variable lookup followed by universal dotted notation.  But for
\code{\$attrib1}, Cheetah consults the searchList.  Since \code{self} is the
{\em last} element in the searchList, any other 'attrib1' in the searchList
will override that one.

{\em Note:} you cannot override builtin variables and functions; that is, you
cannot access a searchList value of the same name.  This sometimes causes
surprises when Python adds a new builtin to the language.  For instance, Python
2.2 added a new builtin \code{property}.  This tripped up a user with a 
\code{\$property} variable in his application.  Not only did Cheetah look up
the wrong variable, but it raised an error because the \code{property} function
requires arguments.  Since we do not know what builtins might be added to future
versions of Python, the best one can do is to be aware of the situation and to
be on the lookout for new builtins that might cause a name conflict in your
templates.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Missing values}
\label{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 \code{\#errorCatcher}
directive (section \ref{errorHandling.errorCatcher}) or {\bf errorCatcher}
Template constructor argument (section \ref{howWorks.constructing}) to specify
an alternate behaviour.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Directive closures and whitespace handling}
\label{language.directives.closures}
Directive tags can be closed explicitly with \code{\#}, or implicitly with the
end of the line if you're feeling lazy.

\begin{verbatim}
#block testBlock #
Text in the body of the
block directive
#end block testBlock #
\end{verbatim}
is identical to:
\begin{verbatim}
#block testBlock
Text in the body of the
block directive
#end block testBlock
\end{verbatim}

When a directive tag is closed explicitly, it can be followed with other text on
the same line:

\begin{verbatim}
bah, bah, #if $sheep.color == 'black'# black#end if # sheep.
\end{verbatim}

When a directive tag is closed implicitly with the end of the line, all trailing
whitespace is gobbled, including the newline character:
\begin{verbatim}
"""
foo #set $x = 2 
bar
"""
outputs 
"""
foo bar
"""

while 
"""
foo #set $x = 2 #
bar
"""
outputs 
"""
foo 
bar
"""
\end{verbatim}

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:
\begin{verbatim}
"""
foo 
   #set $x = 2 
bar
"""
outputs 
"""
foo
bar
"""

while 
"""
foo 
 - #set $x = 2
bar
"""
outputs 
"""
foo 
 - bar
"""
\end{verbatim}

The \code{\#slurp} directive (section \ref{output.slurp}) also gobbles up
whitespace.

Whitespace handling around comment directives is discussed in the next
chapter.



% Local Variables:
% TeX-master: "users_guide"
% End:      

% # vim: expandtab
