From 50a48fd4d07a7bf5f72efc36b71809ddb10d98b9 Mon Sep 17 00:00:00 2001
From: Angel Ortega <angel@triptico.com>
Date: Mon, 22 Sep 2008 12:37:25 +0200
Subject: [PATCH] The remaining parts have been documented (Closes: #1001).

This includes the 'foreach' and 'set' templates. Also, a brief
paragraph about escaping has been added.
---
 Artemus.pm | 52 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 TODO       |  5 +++--
 2 files changed, 54 insertions(+), 3 deletions(-)

diff --git a/Artemus.pm b/Artemus.pm
index c197624..0ddcc1e 100644
--- a/Artemus.pm
+++ b/Artemus.pm
@@ -202,7 +202,7 @@ Don't use it.
  {-ifeq|term1|term2|text_if_true|text_unless_true}
 
 If I<term1> is equal to I<term2>, this template returns I<text>, or nothing
-otherwise. in the 3 argument version, returns I<text_if_true> or
+otherwise. in the 4 argument version, returns I<text_if_true> or
 I<text_unless_true>.
 
 =item B<ifneq>
@@ -261,6 +261,42 @@ the empty string.
 
 Returns the negation of I<condition>.
 
+=item B<set>
+
+ {-set|template_name|value}
+
+Assigns a value to a template. Same as setting a value from the 'vars'
+argument to B<new>, but from Artemus code.
+
+If you must change a variable from inside an I<if> directive, don't
+forget to escape the I<set> directive, as in
+
+ {-ifeq|{-user}|admin|\{-set\|powers\|EVERYTHING\}}
+
+IF you don't escape it, the I<powers> variable will be inevitably set
+to EVERYTHING.
+
+=item B<foreach>
+
+ {-foreach|list:of:colon:separated:values|output_text|separator}
+
+Iterates the list of colon separated values and returns I<output_text>
+for each one of the values, separating each of them with I<separator>
+(if one is defined). Each element itself can be a list of comma
+separated values that will be split and assigned to the $0, $1... etc
+parameters set to I<output_text>. For example, to create a I<select>
+HTML tag:
+
+ <select name = 'work_days'>
+ {-foreach|Monday,1:Tuesday,2:Wednesday,3:Thursday,4:Friday,5|
+ <option value = '\$1'>\$0</option>
+ }
+ </select>
+
+Remember to escape the dollar signs to avoid being expanded too early,
+and if the I<output_text> include calls to other Artemus templates,
+to escape them as well.
+
 =item B<\CACHE>
 
  {-\CACHE|time}
@@ -282,6 +318,20 @@ prepended (\END) to the text being processed.
 
 =back
 
+=head2 Escaping
+
+Escaping has been briefly mentioned above; this is a way to avoid
+prematurely expanding and executing Artemus templates, and a direct
+derivative of the simple text substitution approach of the Artemus
+engine.
+
+To escape an Artemus template call you must escape ALL characters
+that has special meaning to the uber-simple Artemus parser (that is,
+the opening and closing braces, the pipe argument separator and
+the optional dollar prefixes for arguments). If you nest some
+directives (for example, two I<foreach> calls), you must
+double-escape everything. Yes, this can get really cumbersome.
+
 =head1 FUNCTIONS AND METHODS
 
 =cut
diff --git a/TODO b/TODO
index ea6da4b..458d20d 100644
--- a/TODO
+++ b/TODO
@@ -4,7 +4,7 @@ Artemus TODO / Bug List
 Release Critical Bugs
 ---------------------
 
- * 1001: Document all function templates.
+None!
 
 Open Bugs
 ---------
@@ -20,6 +20,7 @@ Pending Enhancements
 Closed
 ------
 
-None!
+ * 1001: Document all function templates
+   (Mon, 22 Sep 2008 12:36:29 +0200).
 
 Email bugs to angel@triptico.com
-- 
2.11.4.GIT