diff options
Diffstat (limited to 'docs/users_guide_2_src/09_flowControl.txt')
-rwxr-xr-x | docs/users_guide_2_src/09_flowControl.txt | 414 |
1 files changed, 414 insertions, 0 deletions
diff --git a/docs/users_guide_2_src/09_flowControl.txt b/docs/users_guide_2_src/09_flowControl.txt new file mode 100755 index 0000000..75a5845 --- /dev/null +++ b/docs/users_guide_2_src/09_flowControl.txt @@ -0,0 +1,414 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Flow Control} +\label{flowControl} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#for ... \#end for} +\label{flowControl.for} + +Syntax: +\begin{verbatim} +#for $var in EXPR +#end for +\end{verbatim} + + +The \code{\#for} directive iterates through a sequence. The syntax is the same +as Python, but 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} + +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} + +Although to just put a separator between strings, you don't need a for loop: +\begin{verbatim} +#echo ', '.join($names) +\end{verbatim} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#repeat ... \#end repeat} +\label{flowControl.repeat} + +Syntax: +\begin{verbatim} +#repeat EXPR +#end repeat +\end{verbatim} + + +Do something a certain number of times. +The argument may be any numeric expression. +If it's zero or negative, the loop will execute zero times. +\begin{verbatim} +#repeat $times + 3 +She loves me, she loves me not. +#repeat +She loves me. +\end{verbatim} + + +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} + + +A previous implementation used a local variable \code{\$i} as the repeat +counter. However, this prevented instances of \code{\#repeat} from +being nested. The current implementation does not have this problem as it +uses a new local variable for every instance of \code{\#repeat}. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#while ... \#end while} +\label{flowControl.while} + +Syntax: +\begin{verbatim} +#while EXPR +#end while +\end{verbatim} + + +\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} + +Syntax: +\begin{verbatim} +#if EXPR +#else if EXPR +#elif EXPR +#else +#end if +\end{verbatim} + + +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 \code{\#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} + +See section \ref{output.oneLineIf} for the one-line \code{\#if} directive, +which is equivalent to Perl's and C's \code{?:} operator. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#unless ... \#end unless} +\label{flowControl.unless} + +Syntax: +\begin{verbatim} +#unless EXPR +#end unless +\end{verbatim} + + +\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} + +Syntax: +\begin{verbatim} +#break +#continue +\end{verbatim} + + +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 iteration 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 == 'Joe' + #break +#end if +$name - #slurp +#end for +\end{verbatim} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#pass} +\label{flowControl.pass} + +Syntax: +\begin{verbatim} +#pass +\end{verbatim} + + +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. + +The following example does nothing if only \$A is true +\begin{verbatim} +#if $A and $B + do something +#elif $A + #pass +#elif $B + do something +#else + do something +#end if +\end{verbatim} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#stop} +\label{flowControl.stop} + +Syntax: +\begin{verbatim} +#stop +\end{verbatim} + + +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} +A cat +#if 1 + sat on a mat + #stop + watching a rat +#end if +in a flat. +\end{verbatim} + +will print +\begin{verbatim} +A cat + sat on a mat +\end{verbatim} + +And +\begin{verbatim} +A cat +#block action + sat on a mat + #stop + watching a rat +#end block +in a flat. +\end{verbatim} + +will print + +\begin{verbatim} +A cat + sat on a mat +in a flat. +\end{verbatim} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#return} +\label{flowControl.return} + +Syntax: +\begin{verbatim} +#return +\end{verbatim} + + +This is used as in Python. \code{\#return} will exit the current method with a +default return value of \code{None} or the value specified. It may be used +only inside a \code{\#def} or a \code{\#block}. + +Note that \code{\#return} is different from the \code{\#stop} directive, +which returns the sum of all text output from the method in which it is called. +The following examples illustrate this point: + +\begin{verbatim} +1 +$test[1] +3 +#def test +1.5 +#if 1 +#return '123' +#else +99999 +#end if +#end def +\end{verbatim} + +will produce +\begin{verbatim} +1 +2 +3 +\end{verbatim} + +while +\begin{verbatim} +1 +$test +3 +#def test +1.5 +#if 1 +#stop +#else +99999 +#end if +#end def +\end{verbatim} + +will produce +\begin{verbatim} +1 +1.5 +3 +\end{verbatim} + +% Local Variables: +% TeX-master: "users_guide" +% End: |