From: Josh Grams <josh@qualdan.com>
Date: Mon, 3 Aug 2009 10:57:13 +0000 (-0400)
Subject: * template.php: doc fixes.
X-Git-Url: https://jasonwoof.com/gitweb/?p=wfpl.git;a=commitdiff_plain;h=ab02f499da7918c55edc4d17c88ec7a39ea887b8

* template.php: doc fixes.
---

diff --git a/template.php b/template.php
index 5b7e631..da05621 100644
--- a/template.php
+++ b/template.php
@@ -19,12 +19,23 @@
 # This is a simple template-handling system.  You pass it a big data 
 # structure with key/value pairs, and a template string to fill out.
 #
-# Within a template, it recognizes tags delimited by tildes (~).  When 
-# the template is filled out, the tags will be replaced with the 
-# corresponding data.  Tags ending with '?' and '.' mark the start and 
-# end of a sub-template (for optional or repeated text), and can be 
-# wrapped in HTML comments (which will be removed along with the tags
-# when the template is filled out).
+# Within a template, it recognizes tags of the form ~name [arg...]~, 
+# optionally wrapped in HTML comments (which will be removed along with 
+# the tag markers when the template is filled out).
+#
+# { and } as the final argument mark those tags as being the start and 
+# end of a sub-template (for optional or repeated sections).  All other 
+# tags represent slots to be directly filled by data values.  On a } 
+# tag, the name is optional, but must match the corresponding { tag if 
+# present.
+#
+# For a value tag, arguments represent encodings to be applied 
+# successively.  For instance, ~foo html~ will encode it to be safe in 
+# HTML ('&' to '&amp;', '<' to '&lt;', and so on).
+#
+# { tags can take one argument, which will call the corresponding 
+# tem_auto_* function to munge the data, automating certain common use 
+# cases.  See the comments on the tem_auto functions for more details.
 
 require_once('code/wfpl/encode.php');
 require_once('code/wfpl/file.php');
@@ -46,9 +57,9 @@ function parse_template_file($filename) {
 	return parse_template(file_get_contents($filename));
 }
 
-# First we take the template string and break it up into an array 
-# of strings and sub-arrays.  The first item in a sub-array is the name
-# of the value or sub-template.
+# First we take the template string and convert it into a tree of
+# strings and sub-templates.  A template is a hash with a name string,
+# a pieces array, and possibly an args array.
 
 function parse_template($string) {
 	# Don't mess with the $stack/$tem assignments!  Since
@@ -104,7 +115,9 @@ function fill_template($data, $template, $context = NULL, $keychain = NULL) {
 					array_pop($keychain);
 				}
 				array_pop($keychain);
-			} else $output .= tem_get_enc($piece, $context);
+			} else {  # variable
+				$output .= tem_get_enc($piece, $context);
+			}
 		}
 	}
 	return $output;