path: root/docs/users_guide_src/flowControl.tex

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Flow Control}
\label{flowControl}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\#for ... \#end for}
\label{flowControl.for}

The \code{\#for} directive iterates through a sequence.  The syntax is very
similar to Python.  Remember the \code{\$} before variables.

Here's a simple client listing:
\begin{verbatim}
<TABLE>
#for $client in $service.clients
<TR>
<TD>$client.surname, $client.firstname</TD>
<TD><A HREF="mailto:$client.email" >$client.email</A></TD>
</TR>
#end for
</TABLE>
\end{verbatim}

Here's how to loop through the  keys and values of a dictionary:
\begin{verbatim}
<PRE>
#for $key, $value in $dict.items()
$key: $value
#end for
</PRE>
\end{verbatim}

Here's how to create list of numbers separated by hyphens. This ``\#end for''
tag shares the last line to avoid introducing a newline character after each
hyphen.  
\begin{verbatim}
#for $i in range(15)
$i - #end for
\end{verbatim}

If the location of the \code{\#end for} offends your sense of indentational
propriety, you can do this instead:
\begin{verbatim}
#for $i in range(15)
$i - #slurp
#end for
\end{verbatim}

%% @@MSO: I thought builtins require a preceding $ but it only worked without it

The previous two examples will put an extra hyphen after last number.  Here's
how to get around that problem, using the \code{\#set} directive, which will be
dealt with in more detail below.
\begin{verbatim}
#set $sep = '' 
#for $name in $names 
$sep$name 
#set $sep = ', ' 
#end for 
\end{verbatim}

(If you don't like that \code{\#set} variable, you can replace the
\code{\#for} loop with this Python trick:
\code{\#echo ', '.join(\$names)}).

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\#repeat ... \#end repeat}
\label{flowControl.repeat}

Do something a certain number of times.
\begin{verbatim}
#repeat 3
My bonnie lies over the ocean
#end repeat
O, bring back my bonnie to me!
\end{verbatim}

The argument may be any numeric expression:
\begin{verbatim}
#repeat $times + 3
She loves me, she loves me not.
#repeat
She loves me.
\end{verbatim}

If the argument is zero or negative, the loop will execute zero times.

Inside the loop, there's no way to tell which iteration you're on.  If you
need a counter variable, use \code{\#for} instead with Python's \code{range}
function.  Since Python's ranges are base 0 by default, there are two ways
to start counting at 1.  Say we want to count from 1 to 5, and that
\code{\$count} is 5.
\begin{verbatim}
#for $i in $range($count)
#set $step = $i + 1
$step.  Counting from 1 to $count.
#end for


#for $i in $range(1, $count + 1)
$i.  Counting from 1 to $count.
#end for
\end{verbatim}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\#while ... \#end while}
\label{flowControl.while}

\code{\#while} is the same as Python's \code{while} statement.  It may be
followed by any boolean expression:
\begin{verbatim}
#while $someCondition('arg1', $arg2)
The condition is true.
#end while
\end{verbatim}

Be careful not to create an infinite loop.  \code{\#while 1} will loop until
the computer runs out of memory.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\#if ... \#else if ... \#else ... \#end if}
\label{flowControl.if}

The \code{\#if} directive and its kin are used to display a portion of text
conditionally. \code{\#if} and \code{\#else if} should be followed by a
True/False expression, while \code{\#else} should not.  Any valid Python 
expression is allowed.  As in Python, the expression is true unless it evaluates
to 0, '', None, an empty list, or an empty dictionary.  In deference to Python,
\code{\#elif} is accepted as a synonym for {\#else if}.

Here are some examples:
\begin{verbatim}
#if $size >= 1500
It's big
#else if $size < 1500 and $size > 0 
It's small
#else
It's not there
#end if
\end{verbatim}

\begin{verbatim}
#if $testItem($item)
The item $item.name is OK.
#end if
\end{verbatim}

Here's an example that combines an \code{\#if} tag with a \code{\#for} tag.
\begin{verbatim}
#if $people
<TABLE>
<TR>
<TH>Name</TH>
<TH>Address</TH>
<TH>Phone</TH>
</TR>
#for $p in $people
<TR>
<TD>$p.name</TD>
<TD>$p.address</TD>
<TD>$p.phone</TD>
</TR>
#end for
</TABLE>
#else
<P> Sorry, the search did not find any people. </P>
#end if
\end{verbatim}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\#unless ... \#end unless}
\label{flowControl.unless}

\code{\#unless} is the opposite of \code{\#if}: the text is executed if the
condition is {\bf false}.  Sometimes this is more convenient.
\code{\#unless EXPR} is equivalent to \code{\#if not (EXPR)}.

\begin{verbatim}
#unless $alive
This parrot is no more!  He has ceased to be!
'E's expired and gone to meet 'is maker! ...
THIS IS AN EX-PARROT!!
#end unless
\end{verbatim}

You cannot use \code{\#else if} or \code{\#else} inside an \code{\#unless}
construct.  If you need those, use \code{\#if} instead.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\#break and \#continue}
\label{flowControl.break}

These directives are used as in Python. \code{\#break} will
exit a \code{\#for} loop prematurely, while \code{\#continue} will immediately
jump to the next step in the \code{\#for} loop.

In this example the output list will not contain ``10 - ''. 
\begin{verbatim}
#for $i in range(15)
#if $i == 10
  #continue
#end if
$i - #slurp
#end for
\end{verbatim}

In this example the loop will exit if it finds a name that equals 'Joe':
\begin{verbatim}
#for $name in $names
#if $name == 10
  #break
#end if
$name - #slurp
#end for
\end{verbatim}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\#pass}
\label{flowControl.break}

The \code{\#pass} directive is identical to Python \code{pass} statement: it
does nothing. It can be used when a statement is required syntactically but the
program requires no action.

In this example the output list will not contain ``10 - ''. 
\begin{verbatim}
#if $A and $B:
   do something
#elif $A:
  #pass
#elif $B: 
  do something
#else:
  do something
#end if
\end{verbatim}

@@ MSO: Are the colons really allowed?  We've been telling people not to use
@@ colons.  In any case, Greg Czajkowski <gregczajkowski@yahoo.com> tried to
@@ use colons and got an error on the #else directive but not on the others.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\#stop}
\label{flowControl.stop}

The \code{\#stop} directive is used to stop processing of a template at a
certain point.  The output will show {\em only} what has been processed up to
that point.  

When \code{\#stop} is called inside an \code{\#include} it skips the rest of
the included code and continues on from after the \code{\#include} directive.
stop the processing of the included code.  Likewise, when \code{\#stop} is
called inside a \code{\#def} or \code{\#block}, it stops only the \code{\#def}
or \code{\#block}.

\begin{verbatim}
the beginning
#if 1
  inside the if block
  #stop
#end if
the end
\end{verbatim}

will print 
\begin{verbatim}
the beginning
  inside the if block
\end{verbatim}

instead of 
\begin{verbatim}
the beginning
  inside the if block
the end
\end{verbatim}



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