Squashed 'third_party/ctemplate/' content from commit 6742f62
Change-Id: I828e4e4c906f13ba19944d78a8a78652b62949af
git-subtree-dir: third_party/ctemplate
git-subtree-split: 6742f6233db12f545e90baa8f34f5c29c4eb396a
diff --git a/doc/auto_escape.html b/doc/auto_escape.html
new file mode 100644
index 0000000..2b5dd12
--- /dev/null
+++ b/doc/auto_escape.html
@@ -0,0 +1,424 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+ <title>Guide to using Auto Escape</title>
+
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <link href="designstyle.css" type="text/css" rel="stylesheet">
+ <style type="text/css">
+ ol.bluelist li {
+ color: #3366ff;
+ font-family: sans-serif;
+ }
+ ol.bluelist li p {
+ color: #000;
+ font-family: "Times Roman", times, serif;
+ }
+ ul.blacklist li {
+ color: #000;
+ font-family: "Times Roman", times, serif;
+ }
+ </style>
+</head>
+<body>
+
+<h1><a name="Guide_Auto_Escape"></a>Guide to using Auto Escape</h1>
+
+<h2>Introduction</h2>
+
+<p>Auto Escape is an optional mode of execution in the Template System
+developed to provide a better defense against cross-site scripting (XSS)
+in web applications. In this mode, the Template System assumes
+responsibility for applying the proper escaping modifiers for each
+variable in your template (and templates it may include). As such, the
+template developer no longer needs to manually apply escaping modifiers
+to each variable, a process which is repetitive and error-prone
+particularly in larger and more complex applications.</p>
+
+<p>In order for the Template System to properly determine the escaping
+modifiers to apply to variables, it activates a built-in HTML-aware
+parser during template initialization. The parser scans the template
+to determines the context in which each variable is being emitted.
+The scanning is performed at initialization-time only hence does not
+contribute to processing costs at template expansion time.</p>
+
+<p>Refer to <a href="guide.html#security">Security Considerations</a>
+for additional security information on escaping directives and their
+use according to the context in which content is being expanded.</p>
+
+<h2>Current Status</h2>
+
+<p>Auto Escape currently supports well <code>HTML</code> and
+<code>Javascript</code> templates. It also provides very basic support
+for <code>CSS</code>, <code>JSON</code> and <code>XML</code> templates
+where it applies the corresponding escaping modifier but without
+utilizing a parser. We may in the future provide parsers specific
+to these contexts and modifiers for them that are finer-grained.</p>
+
+<h2>Overview</h2>
+
+This section provides more background on Auto Escape.
+Refer to <a href="guide.html#auto_escape">How to Auto Escape</a>
+for information on how to leverage this mode in your application.
+
+<h3>Using template modifiers</h3>
+
+<p>In the simplest case, where you only want to use template-modifiers
+to achieve html-safety (that is, you only use
+<code>html_escape</code>, <code>url_query_escape</code>, and so
+forth), you can stop specifying template-modifiers in your template at
+all. The Auto Escape mode will generate the modifiers on its own and
+perform the correct escaping.</p>
+
+<p>If you need other types of modifiers, including your own custom
+modifiers, you can still specify them in your template and they will
+continue to work just the same. The Auto Escape mode will simply apply
+the appropriate escaping modifiers after your own.</p>
+
+<p>Other reasons for manually specifying variable modifiers include:</p>
+<ol>
+ <li> To indicate a variable is safe. You may add the
+ <code>:none</code> modifier as the last modifier for a given
+ variable, in which case the Auto Escape mode will leave it
+ untouched and not apply escaping directives to it. Use only
+ when you are sure the variable is trusted to be safe from XSS.
+ </li>
+
+ <li> To select a different escaping modifier from a list of
+ equivalent modifiers. Certain modifiers are equivalent from
+ an escaping point of view in that they would all ensure given
+ content is safe when escaped in a specific context. The
+ Auto Escape mode choses the most common escaping modifier for
+ that use but allows you to indicate a different choice as shown
+ below:
+
+ <table border="1" cellpadding="3" summary="Alternatives to modifiers">
+ <tr><th>TemplateContext</th><th>Primary Modifier</th>
+ <th>Accepted alternatives</th></tr>
+
+ <tr>
+ <td><code>TC_HTML</code></td>
+ <td><code>:html_escape</code></td>
+ <td><ul>
+ <li><code>:pre_escape</code></li>
+ <li><code>:html_escape_with_arg=snippet</code></li>
+ <li><code>:html_escape_with_arg=attribute</code></li>
+ <li><code>:html_escape_with_arg=url</code></li>
+ <li><code>:url_query_escape</code></li>
+ <li><code>:url_escape_with_arg=html</code></li>
+ <li><code>:img_src_url_escape_with_arg=html</code></li>
+ </ul></td>
+ </tr>
+
+ <tr>
+ <td><code>TC_HTML</code> and <code>TC_CSS</code></td>
+ <td><code>:cleanse_css</code></td>
+ <td><ul>
+ <li><code>:url_escape_with_arg=css</code></li>
+ <li><code>:img_src_url_escape_with_arg=css</code></li>
+ </ul></td>
+ </tr>
+
+ <tr>
+ <td><code>TC_XML</code></td>
+ <td><code>:xml_escape</code></td>
+ <td><ul>
+ <li><code>:html_escape</code></li>
+ <li><code>:html_escape_with_arg=attribute</code></li>
+ </ul></td>
+ </tr>
+
+ <tr>
+ <td><code>TC_JS</code></td>
+ <td><code>:javascript_escape</code></td>
+ <td><ul>
+ <li><code>:url_escape_with_arg=javascript</code></li>
+ <li><code>:img_src_url_escape_with_arg=javascript</code></li>
+ </ul></td>
+ </tr>
+
+ <tr>
+ <td><code>TC_JSON</code></td>
+ <td><code>:javascript_escape</code></td>
+ <td><ul>
+ <li><code>:json_escape</code></li>
+ </ul></td>
+ </tr>
+
+ </table></li>
+
+ <li> To add additional escaping modifiers. The Template System will
+ never remove escaping directives you explicitly specify. </li>
+</ol>
+
+<h3><A name="EscapeContext">Escaping Contexts</A>
+</h3>
+
+
+<p>The table belows indicates which modifier Auto-Escape selects to
+escape a given variable, based on the context of the variable being
+inserted and, possibly, on more specific information such as whether
+the variable is inside quotation marks. The table only applies for
+the well-supported TemplateContext values (currently
+<code>TC_HTML</code> and <code>TC_JS</code>).</p>
+
+<p>In a few cases, we do not have
+a modifier that is both safe against XSS and respecting of
+the semantics of the variable therefore we fail the template
+initialization. An error is logged indicating the cause of
+the failure.</p>
+
+<table border="1" cellpadding="3" summary="Contexts for using modifiers">
+<tr bgcolor="#4169E1">
+ <th>Context</th><th>HTML Quoted?</th>
+ <th>Examples</th><th>Action Performed</th>
+</tr>
+
+<tr bgcolor="#F0F8FF">
+ <td>Regular HTML Body and HTML comments</td><td>Any</td>
+ <td><pre><p>Hello {{USER}}</p>
+ </pre></td>
+ <td>Escape <code>USER</code> using
+ <code>:html_escape</code></td>
+</tr>
+
+<tr bgcolor="#FAEBD7">
+ <td>In URL attribute: Starts at pos 0</td><td>Yes</td>
+ <td><pre><a href="{{URL}}">;</pre></td>
+ <td>Escape <code>URL</code> using
+ <code>:url_escape_with_arg=html</code></td>
+</tr>
+
+<tr bgcolor="#FAEBD7">
+ <td>In URL attribute: Other</td><td>Yes</td>
+ <td><pre><a href="/foo?q={{QUERY}}"></pre></td>
+ <td>Escape <code>QUERY</code> using
+ <code>:html_escape</code></td>
+</tr>
+
+<tr bgcolor="#FAEBD7">
+ <td>In URL attribute: Starting at pos 0</td><td>No</td>
+ <td><pre><form action={{URL}}></pre></td>
+ <td><em>Fail template initialization</em></td>
+</tr>
+
+<tr bgcolor="#FAEBD7">
+ <td>In URL attribute: Other</td><td>No</td>
+ <td><pre><a href=/foo?q={{QUERY}}>My Link</a></pre></td>
+ <td>Escape <code>QUERY</code> using
+ <code>:url_query_escape</code></td>
+</tr>
+
+<tr bgcolor="#F0F8FF">
+ <td>In STYLE attribute</td><td>Yes</td>
+ <td><pre><div style="color:{{COLOR}};"></pre></td>
+ <td>Escape <code>COLOR</code> using
+ <code>:cleanse_css</code></td>
+</tr>
+
+<tr bgcolor="#F0F8FF">
+ <td>In STYLE attribute</td><td>No</td>
+ <td><pre><div style=color:{{COLOR}};></pre></td>
+ <td><em>Fail template initialization</em></td>
+</tr>
+
+<tr bgcolor="#FAEBD7">
+ <td>In Javascript attribute: String literal</td><td>Yes</td>
+ <td><pre><a href="url" onclick="doFoo('{{ARG}}');"></pre></td>
+ <td>Escape <code>ARG</code> using
+ <code>:javascript_escape</code></td>
+</tr>
+
+<tr bgcolor="#FAEBD7">
+ <td>In Javascript attribute: Non-string literal</td><td>Yes</td>
+ <td><pre><a href="url" onclick="doFoo({{ARG}});"></pre></td>
+ <td>Escape <code>ARG</code> using
+ <code>:javascript_escape_with_arg=number</code></td>
+</tr>
+
+<tr bgcolor="#FAEBD7">
+ <td>In Javascript attribute: Any</td><td>No</td>
+ <td><pre><a href="url" onclick=doFoo('{{ARG}}');></pre></td>
+ <td><em>Fail template initialization.</em></td>
+</tr>
+
+<tr bgcolor="#F0F8FF">
+ <td>In all other attributes</td><td>Yes</td>
+ <td><pre><b class="{{CLASS}}"></pre></td>
+ <td>Escape <code>CLASS</code> using
+ <code>:html_escape</code></td>
+</tr>
+
+<tr bgcolor="#F0F8FF">
+ <td>In all other attributes</td><td>No</td>
+ <td><pre><table border={{BORDER}}></pre></td>
+ <td>Escape <code>BORDER</code> using
+ <code>:html_escape_with_arg=attribute</code></td>
+</tr>
+
+<tr bgcolor="#FAEBD7">
+ <td>In Javascript code: In a string literal</td><td>Any</td>
+ <td><pre><script>var a = '{{VALUE}}';</script></pre></td>
+ <td>Escape <code>VALUE</code> using
+ <code>:javascript_escape</code></td>
+</tr>
+
+<tr bgcolor="#FAEBD7">
+ <td>In Javascript code: Non-string literal</td><td>Any</td>
+ <td><pre><script>var a = {{VALUE}};</script></pre></td>
+ <td>Escape <code>VALUE</code> using
+ <code>:javascript_escape_with_arg=number</code></td>
+</tr>
+
+<tr bgcolor="#F0F8FF">
+ <td>In a <style> tag</td><td>Any</td>
+ <td><pre><style>font-size={{FONTSIZE}};</style></pre></td>
+ <td>Escape <code>FONTSIZE</code> using
+ <code>:cleanse_css</code></td>
+</tr>
+
+</table>
+
+<h4>Comments:</h4>
+<ul>
+ <li>For values of URL-accepting attributes, we apply a different
+ modifier if the variable is at the beginning of the attribute
+ value or not because in the former case we consider the
+ variable to represent a complete URL and hence also check
+ that its scheme is safe (<code>HTTP</code> or
+ <code>HTTPS</code>).</li>
+ <li>We recommend that you enclose attribute values in quotes
+ in particular:
+ <ol>
+ <li>Under some conditions outlined in the table above, when
+ variables are present in attribute values that are not
+ enclosed in quotes, we may fail template initialization
+ because we do not have escaping modifiers that are safe to
+ use.</li>
+ <li>Also the determination of which escaping modifier
+ to apply for unquoted attribute values specifically
+ is likely to change in the future.</li>
+ </ol>
+</ul>
+
+<p>The Auto Escape mode is designed to be simple to use and to produce
+correct correct escaping with minimal input. It does however come with
+restrictions governing the use of this template system.</p>
+
+<h3><a name="Limitations">Limitations</a></h3>
+
+<ul>
+ <li> <p>Templates may only be included in regular HTML
+ text. Including a template within HTML comments or inside an
+ HTML tag is currently not supported. In the example below,
+ <code>HEADER</code> and <code>FOOTER</code> are properly
+ included but <code>TAG</code> and <code>COMMENT</code> are
+ not.</p>
+ <pre>
+ <html><head>{{>HEADER}}</head><body>
+ <{{>TAG}}>
+ <p>
+ <!-- {{>COMMENT}} -->
+ <p>{{>FOOTER}}
+ </body></html>
+ </pre>
+ <p>If the template system detects that you are including a
+ template in another HTML context, it will log a warning.</p></li>
+
+ <li> <p>Included templates may not cross HTML boundaries. They
+ cannot start with one <code>TemplateContext</code> and end in
+ another. For example, the template below crosses boundaries --
+ it starts in HTML and ends in Javascript -- and is therefore
+ not a valid included template for auto-escaping.</p>
+ <pre>
+ <html>
+ <head>
+ </head>
+ <body>
+ Hello USER.
+ <script>
+ var a = 'not a nice template';
+ </pre>
+ <p>To rectify this violation, continue the template by
+ completing the javascript code and terminating it with a
+ <code></script></code> tag.</p> </li>
+
+ <li> <p>Error reporting. We currently report errors by logging
+ a warning or an error during initial template
+ initialization and parsing if we suspect something is
+ incorrect. Please check for them, as they indicate an error
+ that may cause auto-escaping to work improperly.</p> </li>
+
+ <li> <p>Beware of double escaping. When you use the Auto Escape mode,
+ you surrender all variable escaping to the template system.
+ If you also perform your own escaping in your source code, you may
+ face situations where content was escaped multiple times.</p>
+ <p>In particular, do not use any of the legacy methods below or
+ others that perform variable escaping.</p>
+ <ul>
+ <li> <code>SetEscapedValue</code> </li>
+ <li> <code>SetEscapedFormatttedValue</code> </li>
+ <li> <code>SetEscapedValueAndShowSection</code> </li>
+ </ul>
+ </li>
+
+ <li> <p>Supported HTML contexts. HTML (<code>TC_HTML</code>) and
+ Javascript (<code>TC_JS</code>) templates are well supported.
+ Other template contexts have only basic support.
+ For these contexts, variables are escaped as follows:</p>
+ <table border="1" cellpadding="3" summary="HTML contexts for modifiers">
+ <tr><th>TemplateContext</th><th>Escaping Applied</th></tr>
+ <tr><td>TC_JSON</td>
+ <td><code>:javascript_escape</code></td></tr>
+ <tr><td>TC_XML</td>
+ <td><code>:xml_escape</code></td></tr>
+ <tr><td>TC_CSS</td>
+ <td><code>:cleanse_css</code></td></tr>
+ </table></li>
+
+ <li> <p>New restrictions on the use of <code>BI_SPACE</code> and
+ <code>BI_NEWLINE</code>. These system variables may not be
+ re-assigned to a semantically different value via
+ <code>dict->SetValue</code> or related methods, and they may
+ not have modifiers attached to them in templates. For
+ instance: it's ok to redefine <code>BI_NEWLINE</code> from
+ <code>\n</code> to <code>\r\n</code>, since html treats them
+ identically. But changing it to <code>hello, world!</code> is
+ not allowed.</p> </li>
+</ul>
+
+<h4> A new filename convention </h4>
+
+<p>The Auto Escape feature codifies simple conventions
+of template filenames: </p>
+<ol>
+ <li> CSS templates optionally include, in their filename, the
+ keywords <code>style</code> or <code>stylesheet</code> or
+ <code>css</code>. </li>
+ <li> Javascript templates optionally include, in their filename, the
+ keywords <code>js</code> or <code>javascript</code>. </li>
+</ol>
+
+<p>If we find one of these keywords in the filename but
+it does not match the template type given, we log a warning.</p>
+
+<hr>
+<ul>
+ <li> <A HREF="guide.html">User's Guide</A> </li>
+ <li> <A HREF="reference.html">Reference Manual</A> </li>
+<!--
+ <li> <A HREF="auto_escape.html">Auto Escape</A> </li>
+-->
+ <li> <A HREF="tips.html">Tips</A> </li>
+ <li> <A HREF="example.html">Example</A> </li>
+</ul>
+
+
+
+<hr>
+<address>
+Jad Boutros<br>
+</address>
+
+</body>
+</html>
diff --git a/doc/designstyle.css b/doc/designstyle.css
new file mode 100644
index 0000000..29299af
--- /dev/null
+++ b/doc/designstyle.css
@@ -0,0 +1,109 @@
+body {
+ background-color: #ffffff;
+ color: black;
+ margin-right: 1in;
+ margin-left: 1in;
+}
+
+
+h1, h2, h3, h4, h5, h6 {
+ color: #3366ff;
+ font-family: sans-serif;
+}
+@media print {
+ /* Darker version for printing */
+ h1, h2, h3, h4, h5, h6 {
+ color: #000080;
+ font-family: helvetica, sans-serif;
+ }
+}
+
+h1 {
+ text-align: center;
+ font-size: 18pt;
+}
+h2 {
+ margin-left: -0.5in;
+}
+h3 {
+ margin-left: -0.25in;
+}
+h4 {
+ margin-left: -0.125in;
+}
+hr {
+ margin-left: -1in;
+}
+
+/* Definition lists: definition term bold */
+dt {
+ font-weight: bold;
+}
+
+address {
+ text-align: right;
+}
+/* Use the <code> tag for bits of code and <var> for variables and objects. */
+code,pre,samp,var {
+ color: #006000;
+}
+/* Use the <file> tag for file and directory paths and names. */
+file {
+ color: #905050;
+ font-family: monospace;
+}
+/* Use the <kbd> tag for stuff the user should type. */
+kbd {
+ color: #600000;
+}
+div.note p {
+ float: right;
+ width: 3in;
+ margin-right: 0%;
+ padding: 1px;
+ border: 2px solid #6060a0;
+ background-color: #fffff0;
+}
+
+UL.nobullets {
+ list-style-type: none;
+ list-style-image: none;
+ margin-left: -1em;
+}
+
+/* pretty printing styles. See prettify.js */
+.str { color: #080; }
+.kwd { color: #008; }
+.com { color: #800; }
+.typ { color: #606; }
+.lit { color: #066; }
+.pun { color: #660; }
+.pln { color: #000; }
+.tag { color: #008; }
+.atn { color: #606; }
+.atv { color: #080; }
+pre.prettyprint { padding: 2px; border: 1px solid #888; }
+
+.embsrc { background: #eee; }
+
+@media print {
+ .str { color: #060; }
+ .kwd { color: #006; font-weight: bold; }
+ .com { color: #600; font-style: italic; }
+ .typ { color: #404; font-weight: bold; }
+ .lit { color: #044; }
+ .pun { color: #440; }
+ .pln { color: #000; }
+ .tag { color: #006; font-weight: bold; }
+ .atn { color: #404; }
+ .atv { color: #060; }
+}
+
+/* Table Column Headers */
+.hdr {
+ color: #006;
+ font-weight: bold;
+ background-color: #dddddd; }
+.hdr2 {
+ color: #006;
+ background-color: #eeeeee; }
\ No newline at end of file
diff --git a/doc/example.html b/doc/example.html
new file mode 100644
index 0000000..91464c5
--- /dev/null
+++ b/doc/example.html
@@ -0,0 +1,345 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<title>Template Examples</title>
+
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<link href="designstyle.css" type="text/css" rel="stylesheet">
+<style type="text/css">
+ ol.bluelist li {
+ color: #3366ff;
+ font-family: sans-serif;
+ }
+ ol.bluelist li p {
+ color: #000;
+ font-family: "Times Roman", times, serif;
+ }
+ ul.blacklist li {
+ color: #000;
+ font-family: "Times Roman", times, serif;
+ }
+</style>
+</head>
+
+<body>
+
+<h1>Template Examples</h1>
+
+
+<h2> Simple Example </h2>
+
+<p>One reason this example is so simple is that it doesn't even
+require a separate template file, but instead uses
+<code>StringToTemplateCache()</code>. It also doesn't use sections or
+template-includes.</p>
+
+<pre class=example>
+
+int main() {
+ static const char template_text[] =
+ "ERROR: {{FUNCTION}}({{ARGS}}) returned {{ERROR_CODE}}: {{ERROR_MESSAGE}}\n";
+ ctemplate::StringToTemplateCache("mytpl", template_text, ctemplate::DO_NOT_STRIP);
+ FILE* fp = fopen(argv[1], "r");
+ if (fp == NULL) {
+ int err_no = errno; // squirrel this away
+ ctemplate::TemplateDictionary dict("error_msg: fopen()");
+ dict.SetValue("FUNCTION", "fopen");
+ dict.SetValue("ARGS", argv[1]);
+ dict.SetIntValue("ERROR_CODE", err_no);
+ dict.SetValue("ERROR_MESSAGE", strerror(err_no));
+
+ string error_text;
+ ctemplate::ExpandTemplate("mytpl", ctemplate::DO_NOT_STRIP, &dict, &error_text);
+ puts(error_text.c_str());
+ }
+}
+
+</pre>
+
+Note: If this template was intended to run in a web application, you can
+leverage the functionality provided by the auto-escape mode. Simply add
+the AUTOESCAPE pragma directive at the top of the template text and your
+variables will be automatically escaped for the context you specify.
+
+For example, if your template is returned in an HTML context,
+change the <code>template_text</code> declaration as follows:
+
+<pre class=example>
+ static const char template_text[] =
+ "{{%AUTOESCAPE context=\"HTML\"}}"
+ "ERROR: {{FUNCTION}}({{ARGS}}) returned {{ERROR_CODE}}: {{ERROR_MESSAGE}}\n";
+</pre>
+
+<p>This example is only slightly more complicated: we only print the
+": <error message>" part when the error message isn't the empty
+string.</p>
+
+<pre class=example>
+
+int main() {
+ static const char template_text[] =
+ "ERROR: {{FUNCTION}}({{ARGS}}) returned {{ERROR_CODE}}"
+ "{{#MSG_SECTION}}: {{ERROR_MESSAGE}}{{/MSG_SECTION}}\n";
+ ctemplate::StringToTemplateCache("mytpl", template_text, ctemplate::DO_NOT_STRIP);
+ FILE* fp = fopen(argv[1], "r");
+ if (fp == NULL) {
+ int err_no = errno; // squirrel this away
+ ctemplate::TemplateDictionary dict("file_error_message");
+ dict.SetValue("FUNCTION", "fopen");
+ dict.SetValue("ARGS", argv[1]);
+ dict.SetIntValue("ERROR_CODE", err_no);
+ if (err_no > 0)
+ dict.SetValueAndShowSection("ERROR_MESSAGE", strerror(err_no),
+ "MSG_SECTION");
+
+ string error_text;
+ ctemplate::ExpandTemplate("mytpl", ctemplate::DO_NOT_STRIP, &dict, &error_text);
+ puts(error_text.c_str());
+ }
+ delete tpl;
+}
+
+</pre>
+
+<p>This maybe-show-text functionality is one way the template
+machinery is more powerful than just using <code>printf</code>.
+Another nice property of templates is you can reuse the same variable
+multiple times in your template string. You can also define the
+variable values in any order.</p>
+
+
+<h2> Search Results Page </h2>
+
+<p>Here is an example template that could be used to format a Google
+search results page:</p>
+
+<pre class=example>
+
+{{>HEADER}}
+<body bgcolor=white>
+
+{{>PAGE_HEADING}}{{!The following div must be on the same line}}<div>
+
+{{!The ONE_RESULT section displays a single search item}}
+{{#ONE_RESULT}}
+ {{! Note: there are two SUBITEM_SECTIONs. They both show or hide together}}
+ {{#SUBITEM_SECTION}}<blockquote>{{/SUBITEM_SECTION}}
+ {{! LEAD_LINE is received HTML-escaped from the backend.}}
+ <p><a href="{{JUMP_TO_URL:html_escape}}" target=nw>{{LEAD_LINE}}</a><font size=-1>
+
+ {{! SNIPPET1, SNIPPET2 are HTML-escaped in the snippet generator.}}
+ {{#SNIPPET1_SECTION}}
+ <br>{{SNIPPET1}}
+ {{/SNIPPET1_SECTION}}
+
+ {{#SNIPPET2_SECTION}}
+ <br>{{SNIPPET2}}
+ {{/SNIPPET2_SECTION}}
+
+ {{#DESCRIPTION_SECTION}}
+ {{! DESC is received HTML-escaped from the backend.}}
+ <br><span class=f>Description:</span> {{DESC}}
+ {{/DESCRIPTION_SECTION}}
+
+ {{#CATEGORY_SECTION}}
+ <br><span class=f>Category:</span> <a href="{{CAT_URL:html_escape}}" class=f>
+ {{CATEGORY:html_escape}}</a>
+ {{/CATEGORY_SECTION}}
+
+ {{#LASTLINE_SECTION}}
+ <br><font color="{{ALT_TEXT_COLOR:h}}">{{URL:h}}
+ {{#KS_SECTION}}} - {{KSIZE:h}}{{/KS_SECTION}}}
+ {{#CACHE_SECTION}}} - <a href="{{CACHE_URL:h}}" class=f>Cached</A>
+ {{/CACHE_SECTION}}}
+ {{#SIM_SECTION}}} - <a href="{{SIM_PAGES_URL:h}}" class=f>Similar pages</A>
+ {{/SIM_SECTION}}}
+
+ {{#STOCK_SECTION}}
+ - <a href="{{STOCK_URL:h}}" class=f>Stock quotes: {{STOCK_SYMBOL:h}}</a>
+ {{/STOCK_SECTION}}
+ </font>
+ {{/LASTLINE_SECTION}}
+
+ {{#MORE_SECTION}}
+ <br>[ <a href="{{MORE_URL:h}}" class=f>More results from {{MORE_LABEL:h}}</a> ]
+ {{/MORE_SECTION}}
+
+ </font><br>
+ {{! Note: there are two SUBITEM_SECTIONs. They both show or hide together}}
+ {{#SUBITEM_SECTION}}</blockquote>{{/SUBITEM_SECTION}}
+{{/ONE_RESULT}}
+</div> {{! this /div closes the div at the top of this file}}
+{{>PAGE_FOOTING}}
+
+</pre>
+
+<p> Here is a sample procedure that could populate a dictionary for
+expanding that template. The "one procedure" entry point is
+<code>fill_search_results_dictionary</code>. The
+<code>SetTemplateValues</code> function is a separate entry point for
+initializing each top-level template with some standard values.</p>
+
+<pre class=example>
+#include "template.h"
+
+RegisterTemplateFilename(SEARCH_RESULTS_FN, "search_results.tpl");
+#include "search_results.tpl.varnames.h" // defines ksr_HEADER, etc.
+
+using ctemplate::TemplateDictionary;
+using ctemplate::ExpandTemplate;
+using ctemplate::STRIP_WHITESPACE;
+
+// IsEmpty
+// A simple utility function
+static bool IsEmpty(const string &str) {
+ return str.empty();
+}
+
+// SetTemplateValues
+// Use the TemplateDictionary object to set template-wide values that
+// may be used in the top-level template and all its sub-sections
+// and included templates. The template-wide values are all
+// colors from the Palette object
+void SetTemplateValues(TemplateDictionary *dictionary, const Palette* colors) {
+ // better would be to use ksr_LINK_COLOR, etc, assuming those are
+ // defined in search_results.tpl.varnames.h. But using literal
+ // text, as here, is legal as well.
+ dictionary->SetValue("LINK_COLOR", colors->link_color);
+ dictionary->SetValue("BAR_TEXT_COLOR", colors->bar_text_color);
+ dictionary->SetValue("TEXT_COLOR", colors->text_color);
+ dictionary->SetValue("FAINT_COLOR", colors->faint_color);
+ dictionary->SetValue("IMPORTANT_COLOR", colors->important_color);
+ dictionary->SetValue("BAR_COLOR", colors->bar_color);
+ dictionary->SetValue("ALT_TEXT_COLOR", colors->alt_text_color);
+ dictionary->SetValue("ALINK_COLOR", colors->alink_color);
+ dictionary->SetValue("VLINK_COLOR", colors->vlink_color);
+}
+
+// fill_search_results_dictionary
+// Iterates through all the QueryResults contained in the Query object.
+// For each one, it sets corresponding template dictionary values
+// (or hides sections containing their variables, if appropriate) in
+// a sub-dictionary and then adds that dictionary to the parent
+void fill_search_results_dictionary(TemplateDictionary *dictionary,
+ const Query *query) {
+ dictionary->SetFilename(SEARCH_RESULTS_FN);
+
+ // These two functions are defined elsewhere
+ fill_header_dictionary(dictionary->AddIncludeDictionary(ksr_HEADER));
+ fill_page_heading_dictionary(dictionary->AddIncludeDictionary(ksr_PAGE_HEADING),
+ query);
+
+ ResultsList *results = query->GetResults();
+ int resCount = 0;
+
+ for (ResultsList::const_iterator iter = results->begin();
+ iter != results->end();
+ ++iter) {
+ QueryResult *qr = (*iter);
+
+ // Create a new sub-dictionary named "Result Dict <n>" for this entry
+
+ ++resCount;
+
+ TemplateDictionary *result_dictionary =
+ dictionary->AddSectionDictionary(ksr_ONE_RESULT);
+
+ result_dictionary->SetValue(ksr_JUMP_TO_URL, qr->GetUrl());
+
+ if (qr->IsSubItem()) {
+ result_dictionary->ShowSection(ksr_SUBITEM_SECTION);
+ }
+
+ result_dictionary->SetValue(ksr_LEAD_LINE, qr->GetLeadLine());
+
+ result_dictionary->SetValueAndShowSection(ksr_SNIPPET1, qr->GetSnippet1(),
+ ksr_SNIPPET1_SECTION);
+
+ result_dictionary->SetValueAndShowSection(ksr_SNIPPET2, qr->GetSnippet2(),
+ ksr_SNIPPET2_SECTION);
+
+ result_dictionary->SetValueAndShowSection(ksr_DESC, qr->GetDescription(),
+ ksr_DESCRIPTION_SECTION);
+
+ result_dictionary->SetValueAndShowSection(ksr_CAT_URL, qr->GetCategoryUrl(),
+ ksr_CATEGORY_SECTION);
+
+ result_dictionary->SetValueAndShowSection("CATEGORY", qr->GetCategoryName(),
+ "CATEGORY_SECTION");
+
+
+ if (IsEmpty(qr->GetDisplayUrl()) &&
+ IsEmpty(qr->GetPageSize()) &&
+ IsEmpty(qr->GetCachedUrl()) &&
+ IsEmpty(qr->GetSimilarPagesUrl()) &&
+ (IsEmpty(qr->GetStockUrl()) ||
+ IsEmpty(qr->GetStockSymbol())) ) {
+ // there is nothing on the last line, so hide it altogether
+ } else {
+ result_dictionary->ShowSection("LASTLINE_SECTION");
+
+ result_dictionary->SetValue(ksr_URL, qr->GetDisplayUrl());
+
+ result_dictionary->SetValueAndShowSection(ksr_KSIZE, qr->GetPageSize(),
+ ksr_KS_SECTION);
+
+ result_dictionary->SetValueAndShowSection(ksr_CACHE_URL, qr->GetCachedUrl(),
+ ksr_CACHE_SECTION);
+
+ result_dictionary->SetValueAndShowSection(ksr_SIM_PAGES_URL,
+ qr->GetSimilarPagesUrl(),
+ ksr_SIM_SECTION);
+
+ result_dictionary->SetValueAndShowSection(ksr_STOCK_URL, qr->GetStockUrl(),
+ ksr_STOCK_SECTION);
+
+ result_dictionary->SetValueAndShowSection(ksr_STOCK_SYMBOL,
+ qr->GetStockSymbol(),
+ ksr_STOCK_SECTION);
+ }
+
+ result_dictionary->SetValueAndShowSection(ksr_MORE_URL, qr->GetMoreUrl(),
+ ksr_MORE_SECTION);
+
+ result_dictionary->SetValueAndShowSection(ksr_MORE_LABEL, qr->GetMoreLabel(),
+ ksr_MORE_SECTION);
+
+ }
+
+ fill_page_footing_dictionary(dictionary->AddIncludeDictionary(ksr_PAGE_FOOTING),
+ query);
+}
+
+void output_page(const Query* query) {
+ TemplateDictionary dict("search-results dict");
+ string output;
+ fill_search_results_dictionary(&dict, query);
+ ctemplate::ExpandTemplate(SEARCH_RESULTS_FN, STRIP_WHITESPACE, &dict, &output);
+ // output now holds the expanded template
+}
+
+</pre>
+
+
+<hr>
+<ul>
+ <li> <A HREF="guide.html">User's Guide</A> </li>
+ <li> <A HREF="reference.html">Reference Manual</A> </li>
+ <li> <A HREF="auto_escape.html">Auto Escape</A> </li>
+ <li> <A HREF="tips.html">Tips</A> </li>
+<!--
+ <li> <A HREF="example.html">Example</A> </li>
+-->
+</ul>
+
+<hr>
+<address>
+Craig Silverstein<br>
+<script type=text/javascript>
+ var lm = new Date(document.lastModified);
+ document.write(lm.toDateString());
+</script>
+</address>
+
+</body>
+</html>
diff --git a/doc/guide.html b/doc/guide.html
new file mode 100644
index 0000000..f60f94a
--- /dev/null
+++ b/doc/guide.html
@@ -0,0 +1,1080 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+
+<html>
+<head>
+<title>How To Use the Ctemplate (formerly Google Template) System</title>
+
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<link href="designstyle.css" type="text/css" rel="stylesheet">
+<style type="text/css">
+ ol.bluelist li {
+ color: #3366ff;
+ font-family: sans-serif;
+ }
+ ol.bluelist li p {
+ color: #000;
+ font-family: "Times Roman", times, serif;
+ }
+ ul.blacklist li {
+ color: #000;
+ font-family: "Times Roman", times, serif;
+ }
+</style>
+</head>
+
+<body>
+
+<h1>How To Use the Ctemplate (formerly Google Template) System</h1>
+<small>(as of
+<script type=text/javascript>
+ var lm = new Date(document.lastModified);
+ document.write(lm.toDateString());
+</script>)
+</small>
+<br>
+
+
+<h2> Motivation </h2>
+
+<p>A template system can be used to separate output formatting
+specifications, which govern the appearance and location of output
+text and data elements, from the executable logic which prepares the
+data and makes decisions about what appears in the output.</p>
+
+<p>Template systems lie along a continuum of power versus separation.
+"Powerful" constructs like variable assignment or conditional
+statements make it easy to modify the look of an application within
+the template system exclusively, without having to modify any of the
+underlying "application logic". They do so, however, at the cost of
+separation, turning the templates themselves into part of the
+application logic.</p>
+
+<p>This template system leans strongly towards preserving the
+separation of logic and presentation. It is intentionally constrained
+in the features it supports and, as a result, applications tend to
+require quite a bit of code to instantiate a template. This may not
+be to everybody's tastes. However, while this design limits the power
+of the template <i>language</i>, it does not limit the power or
+flexibility of the template <i>system</i>. This system supports
+arbitrarily complex text formatting. Many Google applications,
+including the "main" Google web search, use this system
+for formatting output.</p>
+
+<p>Finally, this system is designed with an eye towards efficiency.
+Template instantiation is very quick, with an eye towards minimizing
+both memory use and memory fragmentation.</p>
+
+
+<h2> Overview </h2>
+
+<p>There are two main parts to the Ctemplate System:</p>
+
+<ul>
+ <li> Templates
+ <li> Data dictionaries
+</ul>
+
+<p>The templates are text files that contain the format specification
+for the formatted output, i.e, the template language. The data
+dictionaries contain the mappings from the template elements (markers)
+embedded in the templates to the data that they will format. Here's
+a simple template:</p>
+<pre>
+ <html><head><title>{{TITLE}}</title>{{META_TAGS}}</head>
+ <body>{{BODY}}</body></html>
+</pre>
+
+<p>Here's a dictionary that one could use to instantiate the template:</p>
+<pre>
+ {"TITLE": "Template example",
+ "BODY": "This is a simple template example.\nIt's boring",
+ "DATE": "11/20/2005"}
+</pre>
+
+<p>If we instantiated the template with this dictionary (a process we
+call "expanding"), here's the output we would get:</p>
+<pre>
+ <html><head><title>Template example</title></head>
+ <body>This is a simple template example.
+It's boring</body></html>
+</pre>
+
+<p><code>{{TITLE}}</code> and <code>{{BODY}}</code> are <b>template
+elements</b>, also called <b>markers</b>. In the dictionary,
+<code>TITLE</code>, <code>BODY</code>, and <code>DATE</code> are
+<b>dictionary names</b>, and the values associated with each one, such
+as <code>11/20/2005</code>, are <b>dictionary values</b>.</p>
+
+<p>A few points are clear even from this simple example:</p>
+<ol>
+ <li> Dictionary keys and values are strings; the Ctemplate
+ system is not typed. </li>
+ <li> Dictionary values come already formatted. It was up to the
+ application code to decide how to format the value for
+ <code>DATE</code>, and to insert the date into the dictionary
+ already formatted. </li>
+ <li> Not all dictionary values must be used by a template.
+ <code>DATE</code> is entirely ignored. </li>
+ <li> Not all template elements may exist in the dictionary. In this
+ example, <code>{{META_TAGS}}</code> is not found in the
+ dictionary. This is perfectly legal; missing dictionary names
+ evaluate to the empty string. </li>
+</ol>
+
+
+<h3> Templates </h3>
+
+<p> The template language has four major types of markers (the full
+list of marker types is described in the <A
+HREF="reference.html#template">reference guide</A>):</p>
+<ol>
+ <li> <b>Variable</b> markers, which are replaced by text based on
+ dictionary values. All markers in the above example are
+ variable markers. Variable markers look like this:
+ <code>{{FOO}}</code></li>
+
+ <li> <b>Start section</b> and <b>end section</b> markers, which delimit
+ sections which may appear zero, one, or N times in
+ the output. The number of times a section appears is
+ determined by the data dictionaries, as explained below.
+ Each time a section is expanded, it uses a different
+ dictionary, so that the output values may be different from one
+ iteration of a section expansion to another. Note that the
+ specification of how sections expand is entirely dependent on
+ the dictionary, as set up by the application; there is no way
+ to specify a repeat count in the template language itself.
+ Section markers look like this:
+ <code>{{#FOO}}...{{/FOO}}</code></li>
+
+ <li> <b>Template-include</b> markers, which designate other templates to be
+ expanded and inserted at the location where the marker appears.
+ These are treated much like sections -- one may think of them
+ as sections whose content is specified in a
+ different file instead of inline -- and just like sections, can
+ be expanded zero, one or N times in the output, each with a
+ different dictionary and even a different include-file.
+ Template-include markers look like this:
+ <code>{{>FOO}}</code></li>
+
+ <li> <b>Comment</b> markers, which may annotate the template
+ structure but drop completely out of the expanded
+ output. Comment markers look like this:
+ <code>{{! comment lives here -- cool, no?}}</code></li>
+</ol>
+
+<p>These marker types each have their own namespace. For readability,
+however, it is best to not overuse a single name.</p>
+
+<p>Anything found in a template of the form <code>{{...}}</code> is
+interpreted as a template marker. All other text is considered
+formatting text and is output verbatim at template expansion time.
+Formatting text may consist of HTML tags, XML tags, linefeeds and
+other spacing characters, constant text, etc.</p>
+
+
+<h3> Data Dictionaries </h3>
+
+<p>A data dictionary is a map from keys to values. The keys are
+always strings, each string representing either a variable, a section,
+or a template-include file. (Comments are not stored in the data
+dictionary!) These values correspond to the name of the associated
+template marker: a section <code>{{#FOO}}</code> in the template text
+is matched to the key <code>"FOO"</code> in the dictionary, if it
+exists. Note the case must match as well.</p>
+
+<p>The value associated with a key differs according to key type. The
+value associated with a <i>variable</i> is simple: it's the value for
+that variable. Both keys and values can be any 8-bit
+character-string, and may include internal NULs (\0).</p>
+
+<p>The value associated with a <i>section</i> is more complicated, and
+somewhat recursive: it's a list of data dictionaries. Come
+template-expansion time, the section is expanded once for each
+dictionary in the list, so if there are two dictionaries in the list,
+then the section text will occur in the output twice. The first time,
+all variables/etc. in the section will be evaluated taking into
+account the first dictionary. The second time, all
+variables/etc. will be evaluated taking into account the second
+dictionary. (See <A HREF="#inheritance">below</A> for a definition of
+"taking into account.")</p>
+
+<p>A <i>template-include</i> is a special type of section, so the
+associated value is the same: a list of dictionaries.
+Template-includes also have one other, mandatory associated piece of
+information: the filename of the template to include.</p>
+
+<p>The application program is responsible for building this data
+dictionary, including all nesting. It then applies this dictionary to
+a single template to produce formatted output.</p>
+
+
+<h3>Expanding a Template</h3>
+
+<p>A program using Ctemplate typically reads in templates at
+load time. During the course of program execution, the program will
+repeatedly perform the following two steps: first, instantiate a data
+dictionary, and second, apply the dictionary to the template to
+produce output.</p>
+
+<p>The template system applies a dictionary to a template by finding
+all template markers in the template, and replacing them with the
+appropriate dictionary values. It matches template markers to
+dictionary keys in the obvious way. For instance, a template marker
+<code>{{FOO}}</code> matches the dictionary key <code>FOO</code>. The
+marker <code>{{#BAR}}</code> matches the dictionary key
+<code>BAR</code>, as does the marker <code>{{/BAR}}</code>. The
+marker <code>{{>BAZ}}</code> matches the dictionary key
+<code>BAZ</code>. (And of course, the marker <code>{{!
+comment}}</code> doesn't match any dictionary key at all.)</p>
+
+<p>If no dictionary key is found for a given template marker, then the
+template marker is ignored: if a variable, it expands to the empty
+string; if a section or include-template, the section or
+include-template is expanded zero times.</p>
+
+<p>All names are case sensitive. Names -- that is, variable keys and,
+as a result, template markers -- must be made of (7-bit ascii)
+alphanumeric characters and the underscore. The comment marker,
+which does not map to dictionary keys, may contain any characters
+whatsoever except <code>}</code>, the close-curly brace. It's a
+syntax error for any template marker to violate this rule.</p>
+
+<p>Outside of the template markers, templates may contain any text
+whatsoever, including (single) curly braces and NUL characters.</p>
+
+
+<h3> <A NAME="auto_escape">Auto Escape Mode</A> </h3>
+
+<p>The Auto Escape mode helps protect against cross-site scripting
+(XSS) attacks in web-applications by automatically escaping variables
+in your template. The <a href="auto_escape.html">Guide to using Auto
+Escape</a> has an overview of Auto Escape as well as discussion of its
+limitations.</p>
+
+<p>Auto Escape is enabled on a template-by-template basis. Simply add
+the AUTOESCAPE pragma to the desired template. That template will then
+be automatically escaped, independently of the templates it may
+include or it may be included from. The AUTOESCAPE pragma must be
+placed at the top of the template. It takes a 'context' argument
+saying what context the template is used in: html, javascript, css,
+xml, etc. (There's also a <code>state=IN_TAG</code> argument that is
+used when the template is just a snippet of html intended for use in a
+tag.) See the <A HREF="reference.html#auto_escaping">reference
+guide</A> for a full description of autoescape arguments.</p>
+
+<p>The table below shows four small sample templates along with their
+corresponding AUTOESCAPE pragma. The two most common contexts are
+<code>HTML</code> and <code>JAVASCRIPT</code>. We also show a sample
+template for the <code>CSS</code> context as well as a sample template
+for the <code>IN_TAG</code> state of <code>HTML</code>
+(although it is expected to be rarely used).</p>
+
+<p>
+<table id="AutoescapePragmaEx" border=1 cellpadding=3>
+ <tr>
+ <th>HTML</th>
+ <th>JAVASCRIPT</th>
+ <th>CSS</th>
+ <th>HTML IN_TAG (uncommon)</th>
+ </tr>
+ <tr valign="top">
+ <td>
+ <pre>
+ {{%AUTOESCAPE context="HTML"}}
+
+ <body>
+ <p>Hello {{USER}}</p>
+ <p><a href="{{URL}}">Your Account</a></p>
+ </body>
+ </pre>
+ </td>
+ <td>
+ <pre>
+ {{%AUTOESCAPE context="JAVASCRIPT"}}
+
+ function showMessage(user, msg) {
+ alert("Hello: " + user + " Message: " + msg);
+ }
+
+ var user = '{{USER}}';
+ var msg = '{{MSG}}';
+ showMessage(user, msg);
+ </pre>
+ </td>
+ <td>
+ <pre>
+ {{%AUTOESCAPE context="CSS"}}
+
+ P.abstract {
+ text-align:{{EDGE}};
+ font-size:{{FONT_SIZE_PC}};
+ }
+ .italic {font-style:{{ITALIC}}}
+ </pre>
+ </td>
+ <td>
+ <pre>
+ {{%AUTOESCAPE context="HTML" state="IN_TAG"}}
+
+ class="{{CLASS}}" id="{{ID}}"
+ </pre>
+ </td>
+ </tr>
+</table>
+</p>
+
+<p>Auto-escaping works by automatically applying <i>modifiers</i> to
+every variable in the template. You can manually apply modifiers as
+well, and even define your own. See the <A
+HREF="reference.html#template_modifier">reference guide</A> for a full
+discussion of modifiers and how to use them.</p>
+
+
+<h3> <A NAME="inheritance">Details on Dictionary Lookup</A> </h3>
+
+<p>The dictionary structure is a tree: there's a 'main' dictionary,
+and then a list of sub-dictionaries for each section or
+include-template. Even with all this complexity, the lookup rules are
+mostly straightforward: when looking up a marker -- be it a variable,
+section, or include-template marker -- the system looks in the
+currently applicable dictionary. If it's found there, great. If not,
+and the parent dictionary is not an include-template, it continues the
+look in the parent dictionary, and possibly the grandparent, etc.
+That is, lookup has <i>static scoping</i>: you look in your dictionary
+and any parent dictionary that is associated with the same
+template-file. As soon as continuing the lookup would require you to
+jump to a new template-file (which is what include-template would do),
+we stop the lookup.</p>
+
+<p>For instance, for a template that says
+<code>{{#RESULTS}}{{RESULTNUM}}. {{>ONE_RESULT}}{{/RESULTS}}</code>,
+<code>"ONE_RESULT"</code> is looked for in the "RESULTS" dictionary,
+and if not found there, is looked for in the main, top-level
+dictionary. Likewise, the variable <code>"RESULTNUM"</code> is looked
+for first in the "RESULTS" dictionary, then in the main dictionary if
+necessary. However, "ONE_RESULT" will not do equivalent cascading
+lookups. In fact, it will have no parent dictionaries at all, because
+it's a different template file and thus in a different scope.</p>
+
+<p>Because of these scoping rules, it's perfectly reasonable to set
+all variables that are needed in a given template file, in the
+top-level dictionary for that template. In fact, the <code><A
+HREF="#sections">ShowSection()</A></code> function is provided to
+support just this idiom. To avoid confusion in such a usage mode,
+it's strongly encouraged that you give unique names to all sections
+and include-templates in a single template file. (It's no problem,
+given the template scoping rules, for a single section or
+include-template name to be repeated across different template
+files.)</p>
+
+<p>There's a single special case: the <b>global variable
+dictionary</b>. Every dictionary inherits its initial set of values
+from the global dictionary. Clients can <A HREF="#variables">set
+variables in the global dictionary</A> just like they can in normal
+template dictionaries they create.</p>
+
+<p>The system initializes the global dictionary with a few useful
+values for your convenience. All system variables are prefixed with
+<code>BI</code>, to emphasize they are "built in" variables.</p>
+<ul>
+ <li> <code>BI_SPACE</code>, which has the value
+ <code><space></code>. It is used to force a space
+ at the beginning or end of a line in the template,
+ where it would normally be suppressed. (See below.) </li>
+
+ <li><code>BI_NEWLINE</code>, which has the value
+ <code><newline></code> It is used to force a
+ newline at the end of a line, where it would normally
+ be suppressed. (See below.) </li>
+</ul>
+
+<p>As is usual for inheritance, if a user explicitly assigns a value
+to these variable-names in its own dictionary, this overrides the
+inherited value. So, <code>dict->SetValue("BI_SPACE",
+"&nbsp;")</code> causes <code>BI_SPACE</code> to have the value
+<code>&nbsp;</code>, rather than <code><space></code>, when
+expanding <code>dict</code>.</p>
+
+<p>Note that only variables can be inherited from the global
+dictionary, not section dictionaries or include-file dictionaries.</p>
+
+<p>A couple of small implementation notes: global inheritance is "last
+chance", so if a section's parent dictionary redefined
+<code>BI_SPACE</code>, say, the section dictionary inherits the
+parent-dict value, not the global-dict value. Second, variable
+inheritance happens at expand time, not at dictionary-create time. So
+if you create a section dictionary, and then afterwards set a variable
+in its parent dictionary (or in the global dictionary), the section
+<i>will</i> inherit that variable value, if it doesn't define the
+value itself.</p>
+
+
+<h2> Writing Application Code To Use Templates </h2>
+
+<p>Most application code concerns filling a template dictionary, but
+there is also code for expanding templates given a dictionary. A
+final category of code lets you inspect and control the template
+system.</p>
+
+
+<h3> Creating A Template Dictionary </h3>
+
+<p>The class <code>TemplateDictionary</code> is used for all template
+dictionary operations. <code>new ctemplate::TemplateDictionary(name)</code> is
+used to create a new top-level dictionary.
+<code>dict->AddSectionDictionary(name)</code> and
+<code>dict->AddIncludeDictionary(name)</code> are used to create
+sub-dictionaries for sections or include-files. After
+creating a dictionary, the application should call one or more
+functions for each marker in the template. As an example, consider
+the following template:
+<pre>
+<html><body> {{! This page has no head section.}}
+{{#CHANGE_USER}}
+<A HREF="/login">Click here</A> if you are not {{USERNAME}}<br>
+{{/CHANGE_USER}}
+
+Last five searches:<ol>
+{{#PREV_SEARCHES}
+<li> {{PREV_SEARCH}}
+{{/PREV_SEARCHES}}
+</ol>
+
+{{>RESULT_TEMPLATE}}
+
+{{FOOTER}}
+</body></html>
+</pre>
+
+<p>To instantiate the template, the user should call a function to set
+up <code>FOOTER</code>, and a function to say what to do for the
+sections <code>CHANGE_USER</code> and <code>PREV_SEARCHES</code>, and
+for the include-template <code>RESULT_TEMPLATE</code>. Quite likely,
+the application will also want to create a sub-dictionary for
+<code>CHANGE_USER</code>, and in that sub-dictionary call a function
+to set up <code>USERNAME</code>. There will also be sub-dictionaries
+for <code>PREV_SEARCHES</code>, each of which will need to set
+<code>PREV_SEARCH</code>. Only when this is all set up will the
+application be able to apply the dictionary to the template to get
+output.</p>
+
+<p>The appropriate function to call for a given template marker
+depends on its type.</p>
+
+<h4> <A NAME="variables">Variables</A> </h4>
+
+<p>For variables, the only interesting action is to set the variable's
+value. For most variables, the right method to call is
+<code>dict->SetValue(name, value)</code>. (The name and value
+can be specified as strings in a variety of ways: C++ strings, char
+*'s, or char *'s plus length.)</p>
+
+<p>There are two other ways to set a variable's value as well, each
+with a different scoping rule. You can call
+<code>ctemplate::TemplateDictionary::SetGlobalValue(name, value)</code>
+-- no <code>TemplateDictionary</code> instance needed here -- to set a
+variable that can be used by all templates in an application. This
+is quite rare.</p>
+
+<p>You can also call <code>dict->SetTemplateGlobalValue(name,
+value)</code>. This sets a variable that is seen by all child
+dictionaries of this dictionary: sub-sections you create via
+<code>AddSectionDictionary</code>, and included templates you create
+via <code>AddIncludeDictionary</code> (both described below). This
+differs from <code>SetValue()</code>, because <code>SetValue()</code>
+values are never inherited across template-includes. Almost always,
+<code>SetValue</code> is what you want;
+<code>SetTemplateGlobalValue</code> is intended for variables that are
+"global" to a particular template tree not all template trees, such as
+a color scheme to use, a language code, etc.</p>
+
+<p>To make it easier to use <code>SetValue()</code>, there are a few
+helper routines to help setting values of a few special forms.</p>
+
+<ul>
+ <li> <code>SetIntValue(name, int)</code>: takes an int as the value. </li>
+ <li> <code>SetFormattedValue(name, fmt, ...)</code>: the
+ <code>fmt</code> and <code>...</code> work just like in
+ <code>printf</code>: <code>SetFormattedValue("HOMEPAGE",
+ "http://%s/", hostname)</code>. </li>
+</ul>
+
+<p>Example:</p>
+<pre>
+ ctemplate::TemplateDictionary* dict = new ctemplate::TemplateDictionary("var example");
+ dict->SetValue("FOOTER", "Aren't these great results?");
+</pre>
+
+<h4> <A NAME="sections">Sections</A> </h4>
+
+<p>Sections are used in two ways in templates. One is to expand some
+text multiple times. This is how <code>PREV_SEARCHES</code> is used
+in the example above. In this case we'll have one small
+sub-dictionary for each of the five previous searches the user did.
+To do this, call <code>AddSectionDictionary(section_name)</code>
+to create the sub-dictionary. It returns a
+<code>TemplateDictionary*</code> that you can use to fill the
+sub-dictionary.
+
+<p>The other use of sections is to conditionally show or hide a block
+of text at template-expand time. This is how <code>CHANGE_USER</code>
+is used in the example template: if the user is logged in, we show the
+section with the user's username, otherwise we choose not to show the
+section.</p>
+
+<p>This second case is a special case of the first, and the "standard"
+way to show a section is to expand it exactly one time, by calling
+<code>AddSectionDictionary()</code> once, and then setting
+<code>USERNAME</code> in the sub-dictionary.</p>
+
+<p>However, the hide/show idiom is so common there are a few
+convenience methods to make it simpler. The first takes advantage of
+the fact sections inherit variables from their parent: you set
+<code>USERNAME</code> in the parent dictionary, rather than a section
+sub-dictionary, and then call <code>ShowSection()</code>, which adds a
+single, empty dictionary for that section. This causes the section to
+be shown once, and to inherit <i>all</i> its variable values from its
+parent.</p>
+
+<p>A second convenience method is written for the particular case we
+have with <code>USERNAME</code>: if the user's username is non-empty,
+we wish to
+show the section with <code>USERNAME</code> set to the username,
+otherwise we wish to hide the section and show neither
+<code>USERNAME</code> nor the text around it. The method
+<code>SetValueAndShowSection(name, value, section_name)</code> does
+exactly that: if value is non-empty, add a single dictionary to
+<code>section_name</code> and call <code>section_dict->AddValue(name,
+value)</code>.</p>
+
+<p>Example:</p>
+<pre>
+ ctemplate::TemplateDictionary* dict = new ctemplate::TemplateDictionary("section example");
+ const char* username = GetUsername(); // returns "" for no user
+ if (username[0] != '\0') {
+ ctemplate::TemplateDictionary* sub_dict = dict->AddSectionDictionary("CHANGE_USER");
+ sub_dict->SetValue("USERNAME", username);
+ } else {
+ // don't need to do anything; we want a hidden section, which is the default
+ }
+
+ // Instead of the above 'if' statement, we could have done this:
+ if (username[0] != '\0') {
+ dict->ShowSection("CHANGE_USER"); // adds a single, empty dictionary
+ dict->SetValue("USERNAME", username); // take advantage of inheritance
+ } else {
+ // don't need to do anything; we want a hidden section, which is the default
+ }
+
+ // Or we could have done this:
+ dict->SetValueAndShowSection("USERNAME", username, "CHANGE_USER");
+
+ // Moving on...
+ GetPrevSearches(prev_searches, &num_prev_searches);
+ if (num_prev_searches > 0) {
+ for (int i = 0; i < num_prev_searches; ++i) {
+ TemplateDictionary* sub_dict = dict->AddSectionDictionary("PREV_SEARCHES");
+ sub_dict->SetValue("PREV_SEARCH", prev_searches[i]);
+ }
+ }
+</pre>
+
+<h4> Template-includes </h4>
+
+<p>Template-include markers are much like section markers, so
+<code>AddIncludeDictionary(name)</code> acts, not surprisingly,
+exactly like <code>AddSectionDictionary(name)</code>. However, since
+variable inheritance doesn't work across include boundaries, there is
+no template-include equivalent to <code>ShowSection()</code> or
+<code>SetValueAndShowSection()</code>.</p>
+
+<p>One difference between template-includes and sections is that for a
+sub-dictionary that you create via
+<code>AddIncludeDictionary()</code>, you <i>must</i> call
+<code>subdict->SetFilename()</code> to indicate the name of the
+template to include. If you do not set this, the sub-dictionary will
+be ignored. The filename may be absolute, or relative, in which case
+it's relative to some entry in the <A
+HREF="reference.html#template_cache">template search path</A>.</p>
+
+<p>Example:</p>
+<pre>
+ using ctemplate::TemplateDictionary;
+ TemplateDictionary* dict = new TemplateDictionary("include example");
+ GetResults(results, &num_results);
+ for (int i = 0; i < num_results; ++i) {
+ TemplateDictionary* sub_dict = dict->AddIncludeDictionary("RESULT_TEMPLATE");
+ sub_dict->SetFilename("results.tpl");
+ FillResultsTemplate(sub_dict, results[i]);
+ }
+</pre>
+
+<p>In practice, it's much more likely that
+<code>FillResultsTemplate()</code> will be the one to call
+<code>SetFilename()</code>. Note that it's not an error to call
+<code>SetFilename()</code> on a dictionary even if the dictionary is
+not being used for a template-include; in that case, the function is a
+no-op, but is perhaps still useful as self-documenting code.</p>
+
+<p>Another property of template-includes is that they set the indentation level
+for the included template, that is, every line in the included template is
+indented by the same amount as the template-includes line itself. For
+instance, if you have a template <code>PRINT_STUFF</code> like this:</p>
+<pre>
+print "Hello!"
+print "You are the 10th caller!"
+print "Congratulations!"
+</pre>
+
+<p>and you include it in the template:</p>
+
+<pre>
+ if ShouldPrintStuff():
+ {{>PRINT_STUFF}}
+ else:
+ pass
+</pre>
+
+<p>then when it is expanded, all three print lines will be indented,
+not just the first one:</p>
+
+<pre>
+ if ShouldPrintStuff():
+ print "Hello!"
+ print "You are the 10th caller!"
+ print "Congratulations!"
+ else:
+ pass
+</pre>
+
+<p>Note that this behavior is immaterial when using <A
+HREF="#expand"><code>STRIP_WHITESPACE</code></A>, since in that case
+all leading whitespace is stripped.</p>
+
+
+<h3> <A name="expand">Expanding a Template</A> </h3>
+
+<p>Once you have a template dictionary, it's simplicity itself to
+expand the template with those dictionary values, putting the output
+in a string:</p>
+<pre>
+ ctemplate::TemplateDictionary dict("debug-name");
+ FillDictionary(&dict, ...);
+ string output;
+ bool error_free = <font color=red>ctemplate::ExpandTemplate(<filename>, ctemplate::STRIP_WHITESPACE, &dict, &output);</font>
+ // output now holds the expanded template.
+ // ExpandTemplate returns false if the system cannot load-and-parse
+ // <filename> or any of the template files referenced by the
+ // TemplateDictionary.
+</pre>
+
+<p>The first argument to <code>ExpandTemplate</code> is the filename
+holding the template to expand (though there are ways to use <A
+HREF="#string">non-file-based templates</A> as well). The second argument
+is the "strip" mode, which specifies how to treat whitespace in the
+template. It can take the following values:</p>
+<ul>
+ <li> <code>ctemplate::DO_NOT_STRIP</code>: do nothing. This expands
+ the template file verbatim.
+
+ <li> <code>ctemplate::STRIP_BLANK_LINES</code>: remove all blank
+ lines. This ignores any blank lines found in the template file
+ when parsing it. When the template is html, this reduces the
+ size of the output text without requiring a sacrifice of
+ readability for the input file.
+
+ <li> <code>ctemplate::STRIP_WHITESPACE</code>: remove not only blank
+ lines when parsing, but also whitespace at the beginning and
+ end of each line. It also removes any linefeed (possibly
+ following whitespace) that follows a closing <code>}}</code> of
+ any kind of template marker <i>except</i> a template variable.
+ (This means a linefeed may be removed anywhere by simply
+ placing a comment marker as the last element on the line.)
+ When the template is html, this reduces the size of the output
+ html without changing the way it renders (except in a few
+ special cases.) When using this flag, the built-in template
+ variables <code>BI_NEWLINE</code> and <code>BI_SPACE</code> can
+ be useful to force a space or newline in a particular
+ situation.
+</ul>
+
+<p>The expanded template is written to the string <code>output</code>.
+If <code>output</code> was not empty before calling
+<code>Expand()</code>, the expanded template is appended to the end of
+<code>output</code>.
+
+<p>There is also a "power user" version of
+<code>ExpandTemplate()</code>, called <code>ExpandWithData()</code>,
+that allows you to pass in per-expand data. Another "power user"
+version allows you to expand the template into a custom output
+container, rather than a string. See the <A
+HREF="reference.html#per_expand_data">reference guide</A> for more
+information about these advanced methods.</p>
+
+
+<h3> <A name="string">Getting a Template From a String Rather Than a File</A> </h3>
+
+<p>The first argument to <code>ExpandTemplate</code> is named
+"filename", suggesting that the template has to be read from an
+on-disk file. But in reality, the "filename" argument is just a key
+into an internal cache. (By default, the template system looks on
+disk to satisfy a cache miss, hence the "filename" to describe this
+variable.) If you have a template specified in a string rather than a
+file, you can manually insert it into the cache via
+<code>ctemplate::StringToTemplateCache()</code>.</p>
+
+<p><code>StringToTemplateCache()</code> parses the string you pass in
+as if it were a template file, and inserts it into the global cache
+with the key and strip-mode that you provide. You can then use this
+key and strip-mode as the first two arguments to
+<code>ExpandTemplate</code>. You can also use the key as the argument
+to <code>ctemplate::TemplateDictionary::SetFilename()</code>.</p>
+
+<p>Prefer file-based to string-based templates where possible.
+Updating a file-based template requires merely a data push, rather
+than pushing the new executable, and it also makes it easier for
+non-programmers to modify the template. One reason to use
+string-based templates is if you are in an environment where having
+data files could be dangerous—for instance, you work on a disk
+that is usually full, or need the template to work even in the face of
+disk I/O errors.</p>
+
+<p>This package comes with a script, <A
+HREF="reference.html#template_converter">template-converter</A>, that
+takes a template file as input and emits a C++ code snippet (an .h
+file) that defines a string with those template contents. This makes
+it easy to start by using a normal, file-based template, and then
+switch to <code>StringToTemplateCache()</code> later if you so
+desire.</p>
+
+
+<h3> Copying a Template Dictionary </h3>
+
+<p>You can use the <code>MakeCopy()</code> method on a template
+dictionary to make a "deep" copy of the template. This can be useful
+for situations like the following: you want to fill a template several
+times, each time with 90% of the values the same, but the last 10%
+different. Computing the values is slow. Here's how you can use
+<code>MakeCopy()</code> to do it:</p>
+<ol>
+ <li> fill dict with 90%
+ <li> <code>newdict1 = dict->MakeCopy();</code>
+ <li> fill newdict1 with last 10%
+ <li> <code>newdict2 = dict->MakeCopy();</code>
+ <li> fill newdict2 with last 10%
+ <li> etc.
+</ol>
+
+
+<h3> The Template Cache </h3>
+
+<p>When templates are loaded from disk, they are stored in an internal
+template cache, which is used by <code>ExpandTemplate()</code> and
+(most obviously) <code>StringToTemplateCache()</code>. You can define
+your own template cache with the <code>TemplateCache</code> class.</p>
+
+<p>This is an advanced technique used when you want to support having
+several versions of a template file in memory at the same time (for
+instance, a webserver might want to keep an old version of a template
+file around until all old requests using that template are done being
+serviced). It also supports advanced operations like removing a
+template from the cache, and reloading templates from disk if they
+have changed.</p>
+
+<p>See the <A HREF="reference.html#template_cache">reference
+manual</A> for more details about the template cache.</p>
+
+
+<h3> Template and Threads </h3>
+
+<p>All expansion functions and static <code>TemplateDictionary</code>
+methods are threadsafe: you can safely call
+<code>ctemplate::TemplateDictionary::SetGlobalValue()</code>
+without needing to worry about locking.</p>
+
+<p>Non-static <code>TemplateDictionary</code> methods are not
+thread-safe. It is not safe for two threads to assign values to the
+same template-dictionary without doing their own locking. Note that
+this is expected to be quite rare: usually only one thread will care
+about a given template-dictionary.</p>
+
+
+<h2> <a name="testing_templates">Testing Templates</a> </h2>
+
+<p>Templates have the advantage that they separate the presentation of
+your data from the application logic that generates the data.
+Naturally, you want to do the same for testing: you would like to test
+the application's <i>logic</i> in a way that is robust to changes in
+the <i>presentation</i>.</p>
+
+<p>The easiest way to test this logic is with unit tests that exercise
+the functions in your code that fill template dictionaries. The class
+<code>ctemplate::TemplateDictionaryPeer</code> in
+<code>template_test_util.h</code> is designed to help you do exactly
+that.</p>
+
+<p>Here's a sample test using <code>TemplateDictionaryPeer</code>:</p>
+<pre>
+ void MyTestMethod() {
+ // Create and populate the dictionary as your app normally would.
+ // In this case, we create a dict with data like this:
+ // { color:blue,
+ // shape_section: [
+ // { size:big, num_sides:7 },
+ // { size:big, num_sides:7 },
+ // { size:big, num_sides:7 }
+ // ]
+ // }
+ MyObject obj;
+ ctemplate::TemplateDictionary dict;
+ obj.FillDictionary(&dict);
+ // Create a TemplateDictionaryPeer to gain access to the dict contents.
+ ctemplate::TemplateDictionaryPeer peer(&dict);
+ // Expect color:blue at the top level of this dictionary.
+ EXPECT_STREQ("blue", peer.GetSectionValue("color"));
+ // Fetch sub-dictionaries from the dict.
+ vector<const ctemplate::TemplateDictionary*> shape_dicts;
+ peer.GetSectionDictionaries("shape_section", &shape_dicts);
+ EXPECT_EQ(3, shape_dicts.size());
+ for (int i = 0; i < 3; ++i) {
+ // Create another peer for each sub-dict, and assert that each sub-dict
+ // contains the expected data.
+ ctemplate::TemplateDictionaryPeer shape_peer(dicts[i]);
+ EXPECT_STREQ("big", shape_peer.GetSectionValue("size"));
+ EXPECT_STREQ("7", shape_peer.GetSectionValue("num_sides"));
+ }
+ }
+</pre>
+
+<p>Note that by using <code>TemplateDictionaryPeer</code>, you can
+unit test the code for filling a <code>TemplateDictionary</code>
+independent of the consuming <code>Template</code>.</p>
+
+<p>The above tests your dictionary filling functions, but doesn't
+touch the template expansion. Naturally, you may also want to test
+the template itself. In this case, you will want to avoid using your
+program's dictionary filling functions, and will instead provide a
+custom dictionary in your test. There are a variety of properties you
+might want to test about the template, but here are a few sample
+tests:</p>
+
+<pre>
+ void TestTemplateHTMLEscapesColor() {
+ // Populate a dictionary that lets us exercise the condition we're testing.
+ // In this case, that the 'color' tag will be HTML escaped.
+ ctemplate::TemplateDictionary dict("t1");
+ dict.SetValue("color", "<blue>");
+ // Expand the template with this dictionary.
+ string result;
+ ctemplate::ExpandTemplate(FLAGS_test_srcdir + "templates/my_template.html",
+ ctemplate::STRIP_WHITESPACE, &dict, &result);
+ // Assert that the expansion has the appropriate text in it.
+ EXPECT_THAT(result, HasSubstr("&lt;blue&gt;"));
+ }
+
+ void TestColorAppearsBeforeShape() {
+ // This time, the condition under test is that the "color" element of
+ // the dictionary appears before the "shape" element.
+ // Create an appropriate dictionary.
+ ctemplate::TemplateDictionary dict("t2"); // Note: use sufficiently unique
+ dict.SetValue("color", "white_asdf"); // strings that they won't occur
+ dict.SetValue("shape", "square_asdf"); // "bare" in the template.
+
+ string result;
+ ctemplate::ExpandTemplate(FLAGS_test_srcdir + "templates/my_template.html",
+ ctemplate::STRIP_WHITESPACE, &dict, &result);
+ // Assert that color comes before shape.
+ EXPECT_THAT(result, ContainsRegex("white_asdf.*square_asdf"));
+ }
+</pre>
+
+
+<h2> <A NAME="security">Security Considerations</A> </h2>
+
+<p>Like all web applications, programs that use the Ctemplate
+System to create HTML documents can be vulnerable to
+Cross-Site-Scripting (XSS) attacks unless data inserted into a
+template is appropriately sanitized and/or escaped. Which specific
+form of escaping or sanitization is required depends on the context in
+which the template variable appears within a HTML document (such as,
+regular "inner text", within a <code><script></code> tag, or
+within an <code>onClick</code> handler).
+
+<p>If you are concerned with XSS, your are strongly encouraged to
+leverage the <a href="auto_escape.html">Auto Escape</a> mode developed
+specifically to better defend your application against XSS. The Auto
+Escape mode follows the guidelines outlined below. Do note however
+that regardless of whether you use Auto Escape or not, escaping alone
+while generally required, is often not enough! You also may need to
+sanitize or validate the input, as for instance with URL attributes.
+For further information, refer to additional <a
+href="xss_resources.html">resources</a> on Cross-Site-Scripting
+issues.</p>
+
+The remainder of this section provides a brief summary of techniques
+to prevent XSS vulnerabilities due to template variables in various
+HTML contexts.
+
+<ol class=bluelist>
+<li> Regular text (outside of tags and other special situations).
+
+ <p>Use the auto-escape pragma to html-escape the variable.</p>
+</li>
+
+<li> HTML tag attributes.
+
+ <p>In addition to the auto-escape pragma, ensure that the
+ attribute is enclosed in double quotes in the template.</p>
+</li>
+
+<li> URL attributes (eg., href/src).
+
+ <p>In addition to the auto-escape pragma, ensure that the
+ attribute is enclosed in double quotes in the template.</p>
+</li>
+
+<li> Beware of inserting variables containing data from untrusted
+ sources into the context of a <code>style</code> tag or
+ attribute.
+
+ <p>Certain CSS style-sheet constructs can result in the
+ invocation of javascript. To prevent XSS, the variable must be
+ carefully validated and sanitized.</p>
+</li>
+
+<li> Populating javascript variables.
+
+ <p>In addition to the auto-escape pragma, ensure that the
+ literal is enclosed in quotes in the template:</p>
+ <pre>
+ <script>
+ var msg_text = '{{MESSAGE}}';
+ </script>
+ </pre>
+
+ <p>Literals of non-string types cannot be quoted and escaped.
+ Instead, ensure that the variable's value is set such that it is
+ guaranteed that the resulting string corresponds to a javascript
+ literal of the expected type. For example, use</p>
+ <pre>
+ dict->SetValueInt("NUM_ITEMS", num_items);
+ </pre>
+ <p>to populate an integer javascript variable in the template
+ fragment</p>
+ <pre>
+ <script>
+ var num_items = {{NUM_ITEMS}};
+ </script>
+ </pre>
+
+</li>
+
+<li> Populating javascript variables within event handlers such as
+ <code>onClick</code>.
+
+ <p>Tag attributes whose values are evaluated as a javascript
+ expression (such as <code>on{Click,Load,etc}</code> handlers)
+ generally require HTML-Escape in addition to Javascript-Escape,
+ since the attribute's value is HTML-unescaped by the browser
+ before it is passed to the javascript interpreter.</p>
+
+ <p>However, the javascript-escaping provided by auto-escape
+ makes a subsequent HTML-Escape unnecessary. As such you can
+ apply the same rules for variables within event handlers
+ as you would for javascript variables in string literals:</p>
+ <pre>
+ <button ...
+ onclick='GotoUrl("{{TARGET_URL}}");'>
+ </pre>
+</li>
+
+<li> Consider potential non-template sources of XSS.
+
+ <p>There are a number of scenarios in which XSS can arise that
+ are unrelated to the insertion of values into HTML templates,
+ including,</p>
+
+ <ul class=blacklist>
+ <li> injection into HTTP headers such as <code>Location</code>,</li>
+ <li> incorrect browser-side guess of the content-encoding of a HTML
+ document without explicitly specified <code>charset</code>,</li>
+ <li> incorrect browser-side guess of a non-HTML document's
+ content-type that overrides the document's specified
+ <code>Content-Type</code>,</li>
+ <li> browser-side handling of documents served for download-to-disk
+ (<code>Content-Disposition: attachment</code>).</li>
+ </ul>
+
+ <p>Please consult additional <a
+ href="xss_resources.html">documentation</a> on
+ Cross-Site-Scripting for more detailed discussion of such
+ issues.</p>
+</li>
+
+</ol>
+
+
+<h2> Working Effectively with Templates </h2>
+
+<h3> <A name="register">Registering Template Strings</A> </h3>
+
+<p>Both dictionary keys and template filenames are strings. Instead
+of using raw strings, we encourage you to use a bit of machinery to
+help protect against various types of errors.</p>
+
+<p>For dictionary keys, you can use the <A
+HREF="reference.html#make_tpl_varnames_h">make_tpl_varnames_h</A> tool
+to create static string variables to use instead of a string constant.
+This will protect against typos, as the <A
+HREF="reference.html#make_tpl_varnames_h">make_tpl_varnames_h</A>
+documentation describes. It also yields slightly more efficient
+code.</p>
+
+<p>For template filenames that a program uses -- including
+sub-templates -- we suggest the following idiom:</p>
+
+<pre>
+ #include "example.tpl.varnames.h" // defines 1 string per dictionary key
+ RegisterTemplateFilename(EXAMPLE_FN, "example.tpl"); // defines template
+ ...
+ include_dict->SetFilename(EXAMPLE_FN);
+ ...
+ ctemplate::ExpandTemplate(EXAMPLE_FN, ctemplate::DO_NOT_STRIP, ...);
+ ...
+</pre>
+
+<p>By registering the filename, you can <A
+HREF="reference.html#template_namelist">query</A> the template system
+to detect syntax errors, reload-status, and so forth.</p>
+
+
+<h3> <A NAME="managing">Managing Templates</A> </h3>
+
+<p>There are methods to change the global state of the template
+system, to examine templates, and to examine template dictionaries.
+See the <A HREF="reference.html">reference guide</A> for more
+information.</p>
+
+
+<hr>
+<ul>
+<!--
+ <li> <A HREF="guide.html">User's Guide</A> </li>
+-->
+ <li> <A HREF="reference.html">Reference Manual</A> </li>
+ <li> <A HREF="auto_escape.html">Auto Escape</A> </li>
+ <li> <A HREF="tips.html">Tips</A> </li>
+ <li> <A HREF="example.html">Example</A> </li>
+</ul>
+
+<hr>
+<address>
+Craig Silverstein<br>
+<script type=text/javascript>
+ var lm = new Date(document.lastModified);
+ document.write(lm.toDateString());
+</script>
+</address>
+
+</body>
+</html>
diff --git a/doc/howto.html b/doc/howto.html
new file mode 100644
index 0000000..2a55381
--- /dev/null
+++ b/doc/howto.html
@@ -0,0 +1,31 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+
+<html>
+<head>
+<title>How To Use the Ctemplate (formerly Google Template) System</title>
+
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<link href="designstyle.css" type="text/css" rel="stylesheet">
+</head>
+
+<body>
+
+<p>This document has split into two parts: a user's guide and a
+reference guide. Use the links below to see these, and other
+documents about the template system.<p>
+
+<ul>
+ <li> <A HREF="guide.html">User's Guide</A> </li>
+ <li> <A HREF="reference.html">Reference Manual</A> </li>
+ <li> <A HREF="auto_escape.html">Auto Escape</A> </li>
+ <li> <A HREF="tips.html">Tips</A> </li>
+ <li> <A HREF="example.html">Example</A> </li>
+</ul>
+
+<hr>
+<address>
+Craig Silverstein<br>
+</address>
+
+</body>
+</html>
diff --git a/doc/index.html b/doc/index.html
new file mode 100644
index 0000000..13da75e
--- /dev/null
+++ b/doc/index.html
@@ -0,0 +1,111 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+ <title>Ctemplate (formerly Google Template) System</title>
+
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <link href="designstyle.css" type="text/css" rel="stylesheet">
+ <style type="text/css">
+ ol.bluelist li {
+ color: #3366ff;
+ font-family: sans-serif;
+ }
+ ol.bluelist li p {
+ color: #000;
+ font-family: "Times Roman", times, serif;
+ }
+ ul.blacklist li {
+ color: #000;
+ font-family: "Times Roman", times, serif;
+ }
+ </style>
+</head>
+<body>
+
+<h1> <a name="Ctemplate_System"></a>Ctemplate System </h1>
+<center><strong>Status: Current</strong>
+<small>(as of 25 April 2008)</small></center>
+<br>
+
+<p>Welcome to the C++ CTemplate system! (This project was originally
+called Google Templates, due to its origin as the template system used
+for Google search result pages, but now has a more general name
+matching its community-owned nature.)</p>
+
+<p>As a quick start, here's a small but complete program that uses this
+template library. For more details see, the links below.</p>
+
+<h3>Template file <code>example.tpl</code></h3>
+<pre>
+ Hello {{NAME}},
+ You have just won ${{VALUE}}!
+ {{#IN_CA}}Well, ${{TAXED_VALUE}}, after taxes.{{/IN_CA}}
+</pre>
+
+<h3>C++ program <code>example.cc</code></h3>
+<pre>
+ #include <stdlib.h>
+ #include <string>
+ #include <iostream>
+ #include <ctemplate/template.h>
+ int main(int argc, char** argv) {
+ ctemplate::TemplateDictionary dict("example");
+ dict.SetValue("NAME", "John Smith");
+ int winnings = rand() % 100000;
+ dict.SetIntValue("VALUE", winnings);
+ dict.SetFormattedValue("TAXED_VALUE", "%.2f", winnings * 0.83);
+ // For now, assume everyone lives in CA.
+ // (Try running the program with a 0 here instead!)
+ if (1) {
+ dict.ShowSection("IN_CA");
+ }
+ std::string output;
+ ctemplate::ExpandTemplate("example.tpl", ctemplate::DO_NOT_STRIP, &dict, &output);
+ std::cout << output;
+ return 0;
+ }
+</pre>
+
+<h3>Compiling and linking (using gcc)</h3>
+<pre>
+ gcc -o example example.cc -lctemplate_nothreads
+</pre>
+
+<p>I can use the "nothreads" library because <code>example.cc</code>
+doesn't use threads. If <code>example.cc</code> were threaded, I
+would do something like this instead:</p>
+<pre>
+ gcc -o example example.cc -lctemplate -pthread
+</pre>
+
+<p>See the README for more details about the two different ctemplate
+libraries.</p>
+
+
+<h2>In-depth Documentation</h2>
+
+<ol>
+ <li> <A HREF="howto.html">Howto</A>: Introduction to the
+ Ctemplate system, and a tutorial for using it. </li>
+
+ <li> <A HREF="auto_escape.html">Auto Escape</A>: Guide to using
+ the optional Auto Escape mode to protect your web application
+ better against XSS.</li>
+
+ <li> <A HREF="tips.html">Tips</A>: Advice, tips, and recommendations
+ for best practices with templates, to make them easier to write
+ and maintain, and to avoid common template mistakes. </li>
+
+ <li> <A HREF="example.html">Examples</A>: Some example templates and
+ application code that uses them. These are taken from actual
+ Google applications. </li>
+</ol>
+
+<hr>
+<address>
+Craig Silverstein<br>
+Last modified: Mon Feb 22 10:59:03 PST 2010
+</address>
+
+</body>
+</html>
diff --git a/doc/reference.html b/doc/reference.html
new file mode 100644
index 0000000..09eab1a
--- /dev/null
+++ b/doc/reference.html
@@ -0,0 +1,1707 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+
+<html>
+<head>
+<title>Ctemplate System Reference Guide</title>
+
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<link href="designstyle.css" type="text/css" rel="stylesheet">
+<style type="text/css">
+ ol.bluelist li {
+ color: #3366ff;
+ font-family: sans-serif;
+ }
+ ol.bluelist li p {
+ color: #000;
+ font-family: "Times Roman", times, serif;
+ }
+ ul.blacklist li {
+ color: #000;
+ font-family: "Times Roman", times, serif;
+ }
+</style>
+</head>
+
+<body>
+
+<h1>Ctemplate System Reference Guide</h1>
+<small>(as of
+<script type=text/javascript>
+ var lm = new Date(document.lastModified);
+ document.write(lm.toDateString());
+</script>)
+</small>
+<br>
+
+
+<h2> Overview </h2>
+
+<p>The main class used by the template system is
+<code>TemplateDictionary</code>, which is used to expand a template
+file. It is used by the main functions for expanding a template,
+found in <code>template.h</code>.</p>
+
+<p><code>TemplateCache</code> is used to hold a collection of
+<code>Template</code> objects. <code>TemplateNamelist</code> provides
+various introspection routines on collections of <code>Template</code>
+objects.</p>
+
+<p><code>TemplateModifier</code> and <code>PerExpandData</code> are
+used to modify the values of a <code>TemplateDictionary</code> at
+expand time. <code>TemplateAnnotator</code> does too, but is intended
+for debugging purposes. <code>TemplateDictionaryPeer</code> is used
+for testing template code.</p>
+
+<p><code>ExpandEmitter</code> provides the ability to emit an expanded
+template to an arbitrary output store.</p>
+
+<p><code>TemplateString</code> is a string-like class that is built to
+be very efficient when used with the template system. For instance,
+tools are available to hash constant <code>TemplateString</code>
+objects at compile-time, speeding up their use at run-time.</p>
+
+<p>The rest of this document describes these classes and functions in
+more detail, as well as build tools and other mechanisms for handling
+templates.</p>
+
+<p>(Note: the code snippets below all assume the default configuration
+option is set, which puts template code in namespace
+<code>ctemplate</code>.)</p>
+
+<h2> <A NAME="template">Expanding Templates</A> </h2>
+
+
+<h3> The Template Language </h3>
+
+<p>Templates are strings that contain special formatting code called
+<em>template markers</em>. In the Ctemplate System, template
+strings are usually read from a file.</p>
+
+<p>Anything found in a template of the form {{...}} is
+interpreted as a template marker. All other text is considered
+formatting text and is output verbatim at template expansion time.
+Outside of the template markers, templates may contain any text
+whatsoever, including (single) curly braces and NUL characters.</p>
+
+<p>The template language has six types of markers:</p>
+<ol>
+ <li> <b>Variable</b> markers, which are replaced by text based on
+ dictionary values. Variable markers look like this:
+ {{FOO}}</li>
+
+ <li> <b>Start section</b> and <b>end section</b> markers, which
+ delimit sections which may appear zero, one, or N times in
+ the output. Section markers look like this:
+ <code>{{#FOO}}...{{/FOO}}</code></li>
+
+ <li> <b>Template-include</b> markers, which designate other
+ templates to be expanded and inserted at the location where the
+ marker appears. These are treated much like sections -- one
+ may think of them as sections whose content is specified in a
+ different file instead of inline -- and just like sections, can
+ be expanded zero, one or N times in the output, each with a
+ different dictionary. Template-include markers look like this:
+ <code>{{>FOO}}</code></li>
+
+ <li> <b>Comment</b> markers, which may annotate the template
+ structure but drop completely out of the expanded
+ output. Comment markers look like this:
+ <code>{{! comment lives here -- cool, no?}}</code></li>
+
+ <li> <b>Set-delimiter</b> markers, which change the marker
+ delimiters from <code>{{</code> and <code>}}</code> to custom
+ strings. (The only requirement is that these strings not
+ contain whitespace or the equals sign.) This is useful for
+ languages like TeX, where double-braces may occur in the text
+ and are awkward to use for markup. Set-delimiter markers look
+ like this: <code>{{=< >=}} <! Now markers are
+ delimited by braces > <=| |=> |! And now markers are
+ delimited by bars! | </code></li>
+
+ <li> <b>Pragma</b> markers, which invoke additional built-in template
+ features when processing the template. Pragma markers look like
+ this: <code>{{%PRAGMA [name="value"...]}}</code>. Currently,
+ AUTOESCAPE is the only pragma defined.</li>
+</ol>
+
+<p>These marker types each have their own namespace. For readability,
+however, it is best to not overuse a single name.</p>
+
+
+<h3> Modifiers </h3>
+
+<p>A variable and include-template can have one or more <A
+HREF="#template_modifier">modifiers</A> attached to them, like so:</p>
+<pre>
+ {{MYVAR:mod1:mod2:mod3=value:mod4=value with spaces:mod5}}
+</pre>
+
+<p>A modifier is a filter that's
+applied at template-expand time, that munges the value of the variable
+before it's output. See the <A
+HREF="#template_modifier"><code>TemplateModifier</code></A> class for
+more details.</p>
+
+<p>When expanding a variable (or template-include) with a modifier,
+the modifiers are applied in order, left to right. For a
+template-include, first the entire sub-template is expanded, as a
+single string, and then the modifiers are applied to that string.</p>
+
+<p>In general, using explicit modifiers does not turn off <A
+HREF="#auto_escape">auto-escaping</A> on a variable. The explicit
+modifier <code>:none</code> does suppress auto-escaping.</p>
+
+
+<h3> <A NAME="special_markers">Special Markers</A> </h3>
+
+<p>Some marker names may have a special meaning in the template
+system. Right now, there's one such name.</p>
+
+<h4><A NAME="separator">Separator Sections</A></h4>
+
+<p>If you have a section named FOO, you can define inside
+of it a section named FOO_separator, and the template
+system will automatically expand that section every time
+<code>FOO</code> is expanded, <i>except for the last</i>. Thus, the
+contents of <code>FOO_separator</code> can be used to separate
+repeated values of a section.</p>
+
+<p>Here's an example:</p>
+<pre>
+ Here are the meeting attendees:
+ {{#ATTENDEES}}
+ {{NAME}}
+ {{#ATTENDEES_separator}}, {{/ATTENDEES_separator}}
+ {{/ATTENDEES}}
+ .
+</pre>
+
+<p>Here is a more convoluted example, to show the date:</p>
+<pre>
+ {{#DATE}}{{DATE_COMPONENT}}{{#DATE_separator}}{{DATE_SEP}}{{/DATE_separator}}{{/DATE}}
+</pre>
+
+<p>You'd set up a template dictionary to repeat <code>DATE</code>
+three times, with <code>DATE_COMPONENT</code> set to the month, day,
+and year (or day, month, and year, depending on your locale...), and
+<code>DATE_SEP</code> set to <code>/</code> or <code>-</code> or
+whatever date-separator is called for.</p>
+
+<p><code>SEP_separator</code> is always evaluated with the current
+dictionary. Thus, in the date example, if you wanted a different
+separator each time, you could do so by setting <code>DATE_SEP</code>
+to a different value for each repetition of <code>DATE</code>.</p>
+
+<p>While <code>SEP_separator</code> is automatically expanded by the
+template system, it is otherwise a perfectly normal section. You can
+even instantiate it yourself by calling
+<code>AddSectionDictionary("SEP_separator")</code>. In that case, the
+section will be expanded both via the automatic expansion as a
+separator, and as a normal section via the section dictionary you
+added. This is more confusing than helpful, and you should probably
+never do it.</p>
+
+<p>There can be at most one "separator" sub-section per section. If
+there are more, only the last is automatically expanded.</p>
+
+
+<h3> <A NAME="strip">Specifying a template</A> </h3>
+
+<p>In the template system -- in functions like
+<code>ExpandTemplate()</code> -- a template is specified by a pair:
+filename + strip-mode. The filename specifies the name of the
+template file on disk (but see below for string templates). The strip
+mode specifies how this file should be parsed as it's read from disk,
+in particular, how whitespace should be handled. It can take the
+following values:</p>
+
+<ul>
+ <li> <code>ctemplate::DO_NOT_STRIP</code>: do nothing. This expands
+ the template file verbatim.
+
+ <li> <code>ctemplate::STRIP_BLANK_LINES</code>: remove all blank
+ lines. This ignores any blank lines found in the template file
+ when parsing it. When the template is html, this reduces the
+ size of the output text without requiring a sacrifice of
+ readability for the input file.
+
+ <li> <code>ctemplate::STRIP_WHITESPACE</code>: remove not only blank
+ lines when parsing, but also whitespace at the beginning and
+ end of each line. It also removes any linefeed (possibly
+ following whitespace) that follows a closing <code>}}</code> of
+ any kind of template marker <i>except</i> a template variable.
+ (This means a linefeed may be removed anywhere by simply
+ placing a comment marker as the last element on the line.)
+ When the template is html, this reduces the size of the output
+ html without changing the way it renders (except in a few
+ special cases.) When using this flag, the built-in template
+ variables <code>BI_NEWLINE</code> and <code>BI_SPACE</code> can
+ be useful to force a space or newline in a particular
+ situation.
+</ul>
+
+<p>The filename is where the template file lives on disk. It can be
+either an absolute filename, or relative to a directory in the
+<A HREF="#search_path">template search path</A>.</p>
+
+<p>In addition to reading a template from disk, it is possible to read
+a template from a string, using <code>StringToTemplateCache()</code>.
+The first argument of <code>StringToTemplateCache()</code> is a "key"
+to use to refer to this string-based template. This key takes the
+place of the filename, for any routine that asks for a
+filename + strip.</p>
+
+
+<h3> <A NAME="expand_template">ExpandTemplate()</A> </h3>
+
+<p>This is the main workhorse function of the template system. It
+takes the filename of a template, a <A
+HREF="#template_dictionary">template dictionary</A>, and a string to
+emit to, and emits an "expanded" version of the template using the
+given template dictionary to fill in the template markers.</p>
+
+<p>If the template specified by the given filename is already found in
+an internal cache, the cached version of the template is used,
+otherwise the template is loaded from disk, parsed, and stored in the
+cache before expansion is performed. As always, the "filename" can
+also be a <A HREF="#strip">key</A> to a string-based template,
+inserted directly into the cache via
+<code>StringToTemplateCache()</code>.</p>
+
+<p>There is an overloaded version of <code>Expand()</code> that takes
+an <A HREF="#expand_emitter"><code>ExpandEmitter</code></A> rather
+than a string, as the source to expand the template into.</p>
+
+<p>This function returns true if the template was successfully
+expanded into the output parameter. It returns false if expansion
+failed or was only partially successful. It might fail because the
+template file cannot be found on disk, or because the template has
+syntax errors and cannot be parsed, or because the template
+sub-includes another template, and that sub-template has errors. To
+minimize the risk of errors at expand-time, you can call
+<code>LoadTemplate()</code> (below) first to load and parse the
+template into the cache. This will catch all errors except for errors
+involving sub-templates.</p>
+
+<p>In the case of partial failures -- typically, failures resulting in
+an error in a sub-inclued template -- there may be partial data
+emitted to the output before the error was detected. If
+<code>ExpandTemplate()</code> returns false, you should be careful to
+check for and remove this partial data, if desired.</p>
+
+
+<h3> <A NAME="expand_with_data">ExpandWithData()</A> </h3>
+
+<p><code>ExpandWithData()</code> is like
+<code>ExpandTemplate()</code>, with the addition that it allows you to
+pass in <A HREF="#per_expand_data">per-expand data</A>. It's called
+like this:</p>
+<pre>
+ ctemplate::TemplateDictionary dict(...);
+ ctemplate::PerExpandData per_expand_data;
+ string output;
+ ctemplate::ExpandWithData(filename, strip_mode, &output, &dict,
+ &per_expand_data);
+</pre>
+
+<p>Per-expand data is applied to all templates that are seen while
+expanding: not only the template you called <code>Expand()</code> on,
+but also sub-templates that are brought in via template-includes
+(<code>{{>INCLUDE}}</code>). See the description of the <A
+HREF="#per_expand_data"><code>PerExpandData</code></A> class for more
+details about how expansion can be modified by per-expand data.</p>
+
+<p>The return value has the same meaning as for
+<code>ExpandTemplate()</code> In fact, if you pass in
+<code>NULL</code> as the <code>per_expand_data</code> argument, this
+function is exactly equivalent to <code>ExpandTemplate()</code>.</p>
+
+
+<h3> <A NAME="load_template">LoadTemplate()</A> </h3>
+
+<p>This function takes a filename and a strip-mode, and loads the file
+into the default template cache. Future calls to
+<code>ExpandTemplate()</code> or <code>ExpandWithData()</code> will
+get the parsed template from the cache, without needing to go to
+disk.</p>
+
+<p>This function returns true if the template was successfully read
+from disk, parsed, and inserted into the cache. It will also return
+true if the template is already in the cache (even if the file has
+changed on disk since the template was inserted into the cache). It
+will return false if the file cannot be found on disk, or cannot be
+successfully parsed. (Note that <code>LoadTemplate()</code> cannot
+detect errors in sub-included templates, since the identity of
+sub-included templates is specified in a
+<code>TemplateDictionary</code>, not in the template itself.)</p>
+
+
+<h3> <A NAME="string_to_template_cache">StringToTemplateCache()</A> </h3>
+
+<p>In addition to reading a template file from disk, it is also
+possible to read a template file from a string, using
+<code>StringToTemplateCache()</code>. It takes the content
+as a string. It also takes in a key and a <A HREF="#strip">strip</A>
+mode. The given key and strip mode can be used as the filename/strip
+pair in calls to <code>ExpandTemplate()</code> and similar
+functions. The key can also be used as the "filename" in calls to
+<code>ctemplate::TemplateDictionary::SetFilename()</code>, allowing
+this template to be included inside other templates.</p>
+
+<p><code>StringToTemplateCache()</code> returns true if the string is
+successfully inserted into the cache. It returns false otherwise,
+probably because there is already a string or filename in the cache
+with the same key.</p>
+
+
+<h3> default_template_cache() and mutable_default_template_cache() </h3>
+
+<p>All the above routines -- <code>ExpandTemplate()</code>,
+<code>LoadTemplate()</code>, and the like -- read and write parsed
+templates to the default template cache. This is just a static
+instance of the <A
+HREF="#template_cache"><code>TemplateCache</code></A> class. It can
+be accessed via these two functions:
+<code>default_template_cache()</code> and, if you need a non-const
+version of the cache, <code>mutable_default_template_cache()</code>.
+These can be useful if you need the advanced features of template
+caches, such as <code>ReloadAllIfChanged()</code> or
+<code>ClearCache()</code>.</p>
+
+
+<h2> <A NAME="template_dictionary">The <code>TemplateDictionary</code>
+ Class</A> </h2>
+
+<p>The class <code>TemplateDictionary</code> is used for all template
+dictionary operations. In general, an application will need to call a
+<code>TemplateDictionary</code> method for every marker in the
+associated template (the major exception: markers that evaluate to the
+empty string can be ignored).</p>
+
+<p>The appropriate function to call for a given template marker
+depends on its type.</p>
+
+
+<h3> Data Dictionaries </h3>
+
+<p>A data dictionary is a map from keys to values. The keys are
+always strings, corresponding to the name of the associated template
+marker, so a section <code>{{#FOO}}</code> in the template text is
+matched to the key <code>FOO</code> in the dictionary, if it exists.
+Note the case must match as well.</p>
+
+<p>The value associated with a key differs according to key type. The
+value associated with a <i>variable</i> is simple: it's the value for
+that variable. Both keys and values can be any 8-bit
+character-string, and may include internal NULs (<code>\0</code>).</p>
+
+<p>The value associated with a <i>section</i> is a list of data
+dictionaries. At template-expansion time, the section is expanded
+once for each dictionary in the list. The first time, all
+variables/etc. in the section will be evaluated taking into account
+the first dictionary. The second time, all variables/etc. will be
+evaluated taking into account the second dictionary. (See <A
+HREF="#inheritance">below</A> for a definition of "taking into
+account.")</p>
+
+<p>The value associated with a <i>template-include</i> is also a list
+of data dictionaries. Each data dictionary in this list must also
+have one other, mandatory associated piece of associated information:
+the filename of the template to include. At expand-time, that
+filename is passed as-is to <code>ctemplate::ExpandTemplate()</code>
+(or, more exactly, the equivalent of <code>ExpandTemplate()</code> in
+the same <code>TemplateCache</code> that the parent template comes
+from).</p>
+
+
+<h3> <A NAME="inheritance">Details on Dictionary Lookup</A> </h3>
+
+<p>The dictionary structure is a tree: there's a 'main' dictionary,
+and then a list of sub-dictionaries for each section or
+include-template. When looking up a marker -- be it a variable,
+section, or include-template marker -- the system looks in the
+currently applicable dictionary. If it's found there, that value is
+used. If not, and the parent dictionary is not an include-template,
+it continues the look in the parent dictionary, and possibly the
+grandparent, etc. That is, lookup has <i>static scoping</i>: you look
+in your dictionary and any parent dictionary that is associated with
+the same template-file. As soon as continuing the lookup would
+require you to jump to a new template-file (which is what
+include-template would do), we stop the lookup.</p>
+
+<p>If lookup fails in all dictionaries, the template system does a
+final lookup in the <b>global variable dictionary</b>.</p>
+
+<p>The system initializes the global dictionary with a few useful
+values for your convenience (the user can add more). All system
+variables are prefixed with <code>BI</code>, to emphasize they are
+"built in" variables.</p>
+<ul>
+ <li> <code>BI_SPACE</code>, which has the value
+ <code><space></code>. It is used to force a space
+ at the beginning or end of a line in the template,
+ where it would normally be suppressed. (See below.) </li>
+
+ <li><code>BI_NEWLINE</code>, which has the value
+ <code><newline></code> It is used to force a
+ newline at the end of a line, where it would normally
+ be suppressed. (See below.) </li>
+</ul>
+
+<p>Variable inheritance happens at expand time, not at
+dictionary-create time. So if you create a section dictionary, and
+then afterwards set a variable in its parent dictionary (or in the
+global dictionary), the section <i>will</i> inherit that variable
+value, if it doesn't define the value itself.</p>
+
+
+<h3> SetValue() and variants </h3>
+
+<p>SetValue() is used to set the value for a variable
+marker in a dictionary. It takes a string as input -- nominally a <A
+HREF="#template_string"><code>TemplateString</code></A>, though a C++
+string or C char* will be auto-converted -- for the variable name and
+its value. The name is the same string as is used for the variable's
+template-marker inside the template this dictionary will be expanded
+with: if the template reads <code>Hello {{NAME}}</code> then the
+first argument to <code>SetValue()</code> must be <code>NAME</code>.
+Case matters.</p>
+
+<p><code>SetIntValue()</code> takes an integer as the value, rather
+than a string. On all platforms, the integer may be up to 64
+bits.</p>
+
+<p><code>SetFormattedValue()</code> is a convenience routine.
+<code>SetFormattedValue(key, arg1, arg2, ...)</code> is logically
+equivalent to</p>
+<pre>
+ char buffer[A_BIG_ENOUGH_NUMBER];
+ sprintf(buffer, arg1, arg2, ...);
+ SetValue(key, buffer);
+</pre>
+<p>without having to worry about the size of <code>buffer</code>, or
+about stack overflow.</p>
+
+<p><code>SetValueWithoutCopy()</code> is provided to give an extra bit
+of efficiency when needed. <code>SetValue()</code> will copy the key
+and value into an internal data structure used by the
+<code>TemplateDictionary</code>; this avoids dangling pointers if the
+arguments to <code>SetValue()</code> are temporaries, or otherwise
+have shorter lifetime than the <code>TemplateDictionary</code>. But
+if you know that both the key and value strings have lifetime longer
+than the <code>TemplateDictionary</code> -- perhaps because they are
+global (static duration) <code>char*</code>'s -- you can call
+<code>SetValueWIthoutCopy()</code> to avoid the copy. This yields a
+small time savings at the cost of significant code fragility, so
+should only be used when absolutely necessary.</p>
+
+
+<h3> SetGlobalValue() and SetTemplateGlobalValue() </h3>
+
+<p><code>SetGlobalValue()</code> is like <code>SetValue()</code> but
+works on the global dictionary. Since the global dictionary is shared
+across all template dictionaries, this is a static method on
+<code>TemplateDictionary</code>. It is thread-safe. It is also
+relatively slow.</p>
+
+<p><code>SetTemplateGlobalValue()</code> is like
+<code>SetValue()</code>, but the values are preserved across
+template-includes.</p>
+
+<p>This example shows all three forms:</p>
+<pre>
+A.tpl:
+ {{NAME}} has won {{>PRIZE}}. It is worth {{AMOUNT}}.
+B.tpl:
+ {{AMOUNT}} dollars! And it's all yours, {{NAME}}
+C.tpl:
+ To: {{NAME}}. Amount: {{AMOUNT}}.
+code:
+ ctemplate::TemplateDictionary dict("set_value_demo");
+ ctemplate::TemplateDictionary* subdict = dict.AddIncludeDictionary("PRIZE");
+ subdict->SetFilename("B.tpl");
+ dict->SetValue("NAME", "Jane McJane");
+ dict->SetTemplateGlobalValue("AMOUNT", "One Million");
+ ctemplate::TemplateDictionary::SetGlobalValue("NAME", "John Doe");
+ ctemplate::TemplateDictionary dict_c("set_value_demo, part 2");
+
+ ctemplate::ExpandTemplate("A.tpl", ..., &dict);
+ ctemplate::ExpandTemplate("C.tpl", ..., &dict_c);
+</pre>
+
+<p>The first expand yields this:</p>
+<pre>
+ Jane McJane has won One Million dollars! And it's all yours, John Doe. It is worth One Million.
+</pre>
+
+<p>The second expand yields this:</p>
+<pre>
+ To: John Doe. Amount: .
+</pre>
+
+<p><code>NAME</code> was set via <code>SetValue()</code>, so its
+value was not propagated across the include-dict boundary; instead,
+the subdict (B.tpl) got its value for <code>NAME</code> from the
+global dictionary. <code>AMOUNT</code>, on the other hand, was set
+via <code>SetTemplateGlobalValue()</code>, so its value was propagated
+across the boundary, and the subdict saw it. However, the totally
+unrelated template, C.tpl, did not see either value, and only sees the
+values in the global dictionary. (Of course, had we filled
+<code>dict_c</code> with some values, C.tpl would have had access to
+those.)</p>
+
+
+<h3> AddSectionDictionary(), ShowSection(),
+ and SetValueAndShowSection() </h3>
+
+<p><code>AddSectionDictionary(section_name)</code> returns a
+sub-dictionary associated with the given section_name (for instance,
+<code>dict.AddSectionDictionary("MYSECT")</code> for a template like
+<code>{{#MYSECT}}...{{/MYSECT}}</code>). If called multiple times, it
+will return a new dictionary each time. During <code>Expand()</code>,
+the section will be expanded once for each time
+<code>AddSectionDictionary()</code> was called; that is, the text
+inside the section delimiters will be repeated once for each
+<code>AddSectionDictionary()</code> call, and within a single
+repetition, the dictionary returned by
+<code>AddSectionDictionary()</code> will be used to populate the text
+inside the section delimiters. (With the current dictionary as that
+dictionary's parent, for inheritance purposes.)</p>
+
+<p>This suggests that if <code>AddSectionDictionary()</code> is never
+called on a section, the text inside the section will be omitted
+entirely by <code>Expand()</code>.</p>
+
+<p><code>ShowSection()</code> is a convenience method used to show the
+text inside the section exactly once. It is equivalent to calling
+<code>AddSectionDictionary()</code> once, and ignoring the returned
+sub-dictionary. All variables in the section will depend on
+dictionary inheritence to get their values.</p>
+
+<p><code>SetValueAndShowSection()</code> is another convenience
+method,, used to show a section if and only if a related variable is
+set to a non-empty value. <code>SetValueAndShowSection(name, value,
+section_name)</code> is equivalent to this: if value is empty do
+nothing, otherwise add a single dictionary to
+<code>section_name</code> and call <code>section_dict->AddValue(name,
+value)</code>.</p>
+
+<p>Example:</p>
+<pre>
+ ctemplate::TemplateDictionary* dict = new ctemplate::TemplateDictionary("section example");
+ const char* username = GetUsername(); // returns "" for no user
+ if (username[0] != '\0') {
+ ctemplate::TemplateDictionary* sub_dict = dict->AddSectionDictionary("CHANGE_USER");
+ sub_dict->SetValue("USERNAME", username);
+ } else {
+ // don't need to do anything; we want a hidden section, which is the default
+ }
+
+ // Instead of the above 'if' statement, we could have done this:
+ if (username[0] != '\0') {
+ dict->ShowSection("CHANGE_USER"); // adds a single, empty dictionary
+ dict->SetValue("USERNAME", username); // take advantage of inheritance
+ } else {
+ // don't need to do anything; we want a hidden section, which is the default
+ }
+
+ // Or we could have done this:
+ dict->SetValueAndShowSection("USERNAME", username, "CHANGE_USER");
+
+ // Moving on...
+ GetPrevSearches(prev_searches, &num_prev_searches);
+ if (num_prev_searches > 0) {
+ for (int i = 0; i < num_prev_searches; ++i) {
+ TemplateDictionary* sub_dict = dict->AddSectionDictionary("PREV_SEARCHES");
+ sub_dict->SetValue("PREV_SEARCH", prev_searches[i]);
+ }
+ }
+</pre>
+
+
+<h3> AddIncludeDictionary() and SetFilename() </h3>
+
+<p><code>AddIncludeDictionary(section_name)</code> returns a
+sub-dictionary associated with the given include_name (for instance,
+<code>dict.AddIncludeDictionary("MYTPL")</code> for a template like
+<code>{{>MYTPL}}</code>). If called multiple times, it
+will return a new dictionary each time. It is the responsibility of
+the caller to then call <code>SetFilename()</code> on the
+sub-dictionary returned.</p>
+
+<p>During <code>Expand()</code>,
+each dictionary returned by <code>AddIncludeDictionary</code> will be
+examined in turn. For each dictionary for which
+<code>SetFilename()</code> is called, that filename will be read as a
+template (via <code>LoadTemplate()</code>, with the same
+"strip" value as the current template), and expanded using the
+dictionary. (Note that the dictionary will not inherit
+<code>SetValue()</code> values from the parent dictionary, though it
+will inherit <code>SetTemplateGlobalValue()</code> values.) This
+expanded template will then be emitted to the output.</p>
+
+<p>Note that if <code>AddIncludeDictionary()</code> is never called,
+the template-include will be a no-op during <code>Expand()</code>.
+Likewise, if it is called but <code>SetFilename()</code> is never
+called on the resulting sub-dictionary, the template-include will be a
+no-op. On the other hand, if it is called multiple times, multiple
+templates -- possibly all from the same file, possibly not -- will be
+inserted at the point of the template-include.</p>
+
+<p>If a user has called <code>StringToTemplateCache(key, ...)</code>,
+then the user can call <code>SetFilename(key)</code> to include the
+contents of the string as the sub-template.</p>
+
+
+<h3> Dump() and DumpToString() </h3>
+
+<p>These routines dump the contents of a dictionary and its
+sub-dictionaries. <code>Dump()</code> dumps to stdout,
+<code>DumpToString()</code> to a string. They are intended for
+debugging.</p>
+
+
+<h2> <A NAME="template_cache">The <code>TemplateCache</code> Class</A> </h2>
+
+<p>This class holds a collection of templates. It can be used to give
+you a coherent view of the template system: you load all the templates
+you are going to use into the cache, and then reload them from disk in
+one atomic operation. You can have multiple
+<code>TemplateCache</code> objects in your executable, perhaps one for
+each service you provide, or perhaps one per thread (so as to avoid
+thread contention when loading templates).</p>
+
+<p>One intended use of the template cache is to make it safe to reload
+template files while serving user requests from a webserver. The idea
+is that every user request, as it's created, is associated with the
+current template cache. When you wish to reload, you
+<code>Clone()</code> the current cache, and then reload inside the
+cloned copy. New requests will get the cloned cache, while old
+requests will continue to render using the old cache.
+<code>TemplateCache</code> is written to make this use-case efficient:
+templates are shared between caches when appropriate, with
+reference-counting to keep memory management easy.</p>
+
+
+<h3> The default template cache </h3>
+
+<p>The template system creates a default template cache, which is
+available via the functions <code>default_template_cache()</code> and
+<code>mutable_default_template_cache()</code>.</p>
+
+<p>For simple uses of the template system, using the default cache,
+via <code>ExpandTemplate()</code> and the like, may be perfectly
+adequate. If you want more sophisticated features, such as the
+ability to have different versions of the same template file active at
+one time, or to change the template root-directory, you will have to
+use an explicit <code>TemplateCache</code>.</p>
+
+
+<h3> LoadTemplate() and StringToTemplateCache() </h3>
+
+<p>These two routines are how you explicitly insert data into the
+cache. <code>LoadTemplate()</code> reads a template from disk, while
+<code>StringToTemplateCache()</code> takes the data from a
+user-specified string. These work exactly the same as the global <A
+HREF="#load_template"><code>LoadTemplate()</code></A> and <A
+HREF="#string_to_template_cache"><code>StringToTemplateCache()</code></A>,
+except they insert into the given <code>TemplateCache</code>, rather
+than the global cache.</p>
+
+<p><code>LoadTemplate()</code> is not strictly necessary: if the cache
+cannot find a template it needs at <code>Expand*()</code> time, it will
+automatically try to fetch it from disk. It is intended mostly for
+use with <A HREF="#freeze"><code>Freeze()</code></A>, which disables
+this auto-fetch behavior.</p>
+
+<p>Both of these routines take a <A HREF="#strip">strip</A> mode
+specifying how the template system should treat whitespace while
+parsing.</p>
+
+<p>If the template-cache is <A HREF="#freeze">frozen</A>,
+<code>LoadTemplate()</code> will only return true if the template is
+already stored in the cache, and will return false in every other
+case. For a frozen cache, <code>StringToTemplateCache()</code> will
+always return false.</p>
+
+
+<h3> ExpandWithData() and ExpandFrozen() </h3>
+
+<p>These routines takes a string that represents either a template
+filename (for disk-based templates), or a key used in
+<code>StringToTemplateCache()</code> (for string-based templates), a <A
+HREF="#strip">strip</A> mode saying how to parse the template's
+whitespace, and <A HREF="#per_expand_data">per-expand data</A> (which
+can be NULL). Overloads are provided to output the expanded template
+to either a string or to an arbitrary <A
+HREF="#expand_emitter"><code>ExpandEmitter</code></A>.</p>
+
+<p>Expand uses the filename + strip pair to fetch the template from
+the cache, if it's there. If not, <code>ExpandWithData()</code> will
+fetch the template from disk and insert it into the cache.
+<code>ExpandFrozen()</code>, on the other hand, will just fail to
+expand, and return false. This is the only difference in behavior
+between the two routines. To reinforce this behavior,
+<code>ExpandFrozen()</code> will return false immediately if <A
+HREF="#freeze"><code>Freeze()</code></A> has not been called on the
+cache.
+
+<p>While expanding, the template system may come across template
+sub-includes (<code>{{>SUB_TEMPLATE}}</code>). It will attempt to
+fetch these templates from the cache as well; failing that, it will
+try to load the template from disk (for <code>ExpandWithData()</code>)
+or else fail the expand and return false (for
+<code>ExpandFrozen()</code>).</p>
+
+<p>Because <code>ExpandFrozen()</code> never updates the cache, it is
+a const method, unlike <code>ExpandWithData()</code>.</p>
+
+<p>Note that <code>TemplateCache</code> does not provide the
+convenience <code>ExpandTemplate()</code> routine, as the analogue of
+the global <A
+HREF="#expand_template"><code>ExpandTemplate()</code></A>. If you are
+not interested in the per-expand data, just call
+<code>ExpandWithData()</code> with the per-expand data set to NULL.</p>
+
+
+<h3> ReloadAllIfChanged() </h3>
+
+<p>For every file-based template in the cache (this method ignores
+string-based templates), <code>ReloadAllIfChanged()</code> checks the
+filesystem to see if the file has changed since it was loaded into the
+cache. If so, the cache loads a new version of the file into the
+cache. Note that at this point both the old and new versions of the
+file exist in the cache! Only the new version is accessible via new
+calls to <code>Expand()</code>, but any expansions currently in flight
+during the <code>ReloadAllIfChanged()</code> call will continue to use
+the old version.</p>
+
+<p>NOTE: <code>ReloadAllIfChanged()</code> never modifies existing
+items in the cache in any way. It only loads new entries into the
+cache.</p>
+
+<p><code>ReloadAllIfChanged()</code> comes in two flavors, controlled
+by the passed-in enum. In "immediate" mode, it synchronously iterates
+through the cache and reloads all files that need it. In "lazy" mode,
+it waits to reload a given template file until the next time it's
+actually used (in a call to <code>Expand*()</code>). "Immediate" mode
+is safer in the case where templates depend on each other and the
+files change a lot, since all files are reloaded at about the same
+time. "Lazy" mode avoids the latency spike of "immediate" mode, and
+is preferable in the (common) case that files on disk change only
+rarely.</p>
+
+
+<h3> <A NAME="search_path"> SetTemplateRootDirectory(),
+ AddAlternateTemplateRootDirectory(), and
+ template_root_directory() </A> </h3>
+
+<p>By default, filenames passed in to <code>Expand*()</code> are taken
+to be relative to the current working directory. These functions
+change that behavior. <code>SetTemplateRootDirectory()</code> resets
+the search path to be the single path passed in to this function.
+Every time <code>AddAlternateTemplateRootDirectory()</code> is called,
+it adds another directory to the end of the search path. The template
+system will follow the search path, in order, when looking for a
+filename.</p>
+
+<p>Note that the template search path is only meaningful when the
+filename passed to <code>Expand*()</code> (or specified for a
+sub-include) is a relative filename. If the filename is an absolute
+filename, starting with <code>/</code>, the search path is
+ignored.</p>
+
+<p><code>template_root_directory()</code> returns the first entry in
+the search path. There is currently no way to access other entries in
+the search path.</p>
+
+
+<h3> FindTemplateFilename() </h3>
+
+<p><code>FindTemplateFilename()</code> does the work of finding a
+template file in the filesystem, using the current template search
+path. It takes a relative pathname as input, and returns an absolute
+pathname as output, indicating where the template file lives on the
+filesystem. If the template file is not found, this method returns
+the empty string.</p>
+
+
+<h3> <A NAME="freeze">Freeze()</A> </h3>
+
+<p><code>Freeze()</code> marks the template cache as immutable. After
+this method is called, the cache can no longer be modified by loading
+new templates or reloading existing templates. During expansion only
+cached included templates will be used; they won't be loaded
+on-demand.</p>
+
+<p>Before calling <code>Freeze()</code>, you should make sure your
+cache has all the templates it might need, using
+<code>LoadTemplate()</code> and <code>StringToTemplateCache()</code>.
+Otherwise, <code>ExpandWithData()</code> and
+<code>ExpandFrozen()</code> may fail.</p>
+
+<p>Once the cache is frozen, calls to
+<code>SetTemplateRootDirectory()</code>,
+<code>AddAlternateTemplateRootDirectory()</code>,
+<code>Delete()</code>, and <code>ReloadAllIfChanged()</code> will
+fail.</p>
+
+<p>After the cache is frozen, the <code>TemplateCache</code> object is
+effectively const.</p>
+
+
+<h3> Delete() </h3>
+
+<p>This method deletes an entry from the cache. If the entry is in
+the cache multiple times (each with a different "strip" mode), this
+method deletes all of them.</p>
+
+
+<h3> ClearCache() </h3>
+
+<p>This method deletes all entries from the cache. It can be called
+even on a frozen cache.</p>
+
+<p>Note: this method is not typically necessary unless you are testing
+for memory leaks. It is intended to be called just before exiting the
+program, and after all template expansions are completed. Using it in
+that way may prevent unnecessary reporting by the leak checker.</p>
+
+
+<h3> Clone() </h3>
+
+<p><code>Clone()</code> makes a shallow copy of the given
+<code>TemplateCache</code> object, and returns the copy. The new copy
+and the old share the same template objects; since it's a shallow
+copy, they actually share pointers to the exact same object. (Since
+the template cache never changes a template object once it's loaded
+into the cache, sharing the pointer isn't a risk.)</p>
+
+<p>The intended use of <code>Clone()</code>, as described above, is to
+allow fine control over "epochal" changes in templates. One
+<code>TemplateCache</code> can hold all versions of the template files
+before the big update; after the update is done, you can clone the old
+cache and then call <code>ReloadAllIfChanged()</code> on the clone.
+This is a low-cost operation, since the two copies share most
+resources. Smart pointers take care of most memory management
+issues.</p>
+
+<p>The caller is responsible for calling <code>delete</code> on the
+returned <code>TemplateCache</code> object.</p>
+
+
+
+<h2> <A NAME="template_namelist">The <code>TemplateNamelist</code> Class</A> </h2>
+
+<p>This class provides information about <A
+HREF="guide.html#register">registered</A> templates. Or more
+precisely, all templates corresponding to registered filenames.</p>
+
+<p>All methods in this class are static.</p>
+
+
+<h3> RegisterTemplate() and
+ RegisterTemplateFilename() </h3>
+
+<p><code>TemplateNamelist::RegisterTemplate()</code> takes a filename
+and adds it to the static namelist used by
+<code>TemplateNamelist</code>. All other methods of
+<code>TemplateNamelist</code> work only on registered filenames.</p>
+
+<p>It's fairly rare to call this method directly. Instead, the more
+common use is to use the macro <code>RegisterTemplateFilename</code>
+somewhere in the global scope, like so:</p>
+<pre>
+RegisterTemplateFilename(EXAMPLE_FN, "example.tpl");
+</pre>
+
+<p>The reason to prefer the macro is it defines a global variable that
+you can use instead of the hard-coded template name. This helps catch
+typos. The <code>RegisterTemplateFilename()</code> example is
+functionally equivalent to:</p>
+<pre>
+#define EXAMPLE_FN "example.tpl"
+</pre>
+
+<p>It can be used like this:</p>
+<pre>
+ ctemplate::ExpandTemplate(EXAMPLE_FN, ctemplate::DO_NOT_STRIP, ...);
+</pre>
+
+
+<h3> GetMissingList() </h3>
+
+<p><code>TemplateNamelist::GetMissingList()</code> returns a list of
+all registered templates (or rather, all filenames) where the file
+could not be found on disk.</p>
+
+
+<h3> AllDoExist() </h3>
+
+<p>Returns true if and only if the missing-list is empty.</p>
+
+
+<h3> GetBadSyntax() </h3>
+
+<p>Returns a list of all registered templates where the template
+contains a syntax error, and thus cannot be used.</p>
+
+
+<h3> IsAllSyntaxOkay() </h3>
+
+<p>True if and only if the bad-syntax list is empty.</p>
+
+
+<h3> GetLastmodTime() </h3>
+
+<p>Returns the latest last-modified time for any registered
+template-file.</p>
+
+
+<h2> <A NAME="template_modifier">The TemplateModifier Class</A>
+ and Associated Functions</h2>
+
+<p>A modifier is a filter that's applied at template-expand time, that
+munges the value of the variable before it's output. For instance,
+<code><html><body>{{NAME:html_escape}}</body></html></code>
+asks the template system to apply the built-in
+<code>html_escape</code> modifier when expanding
+<code>{{NAME}}</code>. If you set <code>NAME</code> in your
+dictionary to be <code>Jim & Bob</code>, what will actually be
+emitted in the template is <code>Jim &amp; Bob</code>.</p>
+
+<p>You can chain modifiers together. This template first html-escapes
+<code>NAME</code>, and then javascript-escapes that result:</p>
+<pre>
+ <html><body>{{NAME:html_escape:javascript_escape}}</body></html>
+</pre>
+
+<p>Modifiers typically have a long, descriptive name and also a
+one-letter abbreviation. So this example is equivalent to the
+previous one:</p>
+<pre>
+ <html><body>{{NAME:h:j}}</body></html>
+</pre>
+
+<p>Some modifiers take an argument, specified after an equals
+sign:</p>
+<pre>
+ <html><body>{{NAME:html_escape_with_arg=pre}}</body></html>
+</pre>
+
+
+<h3> Built-in Modifiers </h3>
+
+<p>Here are the modifiers that are built in to the template system.
+They are all defined in template_modifiers.cc:</p>
+
+<table border="1" cellpadding="3" summary="List of built-in modifiers">
+<tr><th>long name</th><th>short name</th><th>description</th></tr>
+
+<tr><td><code>:cleanse_css</code></td><td><code>:c</code></td>
+ <td>Removes characters not safe for a CSS value. Safe characters
+ are alphanumeric, space, underscore, period, coma, exclamation
+ mark, pound, percent, and dash.</td>
+</tr>
+
+<tr><td><code>:html_escape</code></td><td><code>:h</code></td>
+ <td>html-escapes the variable before output
+ (eg <code>&</code> -> <code>&amp;</code>)</td>
+</tr>
+
+<tr><td><code>:html_escape_with_arg</code></td><td><code>:H</code></td>
+ <td>special purpose html escaping. See
+ <a href="#html_escape_args">:H Arguments</a>
+ below for details.</td>
+</tr>
+
+<tr><td><code>:img_src_url_escape_with_arg</code></td><td><code>:I</code></td>
+ <td>special purpose image url escaping. See
+ <a href="#url_escape_args">:I and :U Arguments</a>
+ below for details.</td>
+</tr>
+
+<tr><td><code>:javascript_escape</code></td><td><code>:j</code></td>
+ <td>javascript-escapes the variable before output (eg
+ <code>"</code> -> <code>\x27</code> and
+ <code>&</code> -> <code>\x26</code>)</td>
+</tr>
+
+<tr><td><code>:javascript_escape_with_arg</code></td><td><code>:J</code>
+ </td>
+ <td>special purpose javascript escaping. See
+ <a href="#javascript_escape_args">:J Arguments</a>
+ below for details.</td>
+</tr>
+
+<tr><td><code>:json_escape</code></td><td><code>:o</code></td>
+ <td>json-escapes a variable before output as a string in json;
+ HTML characters are escaped using Unicode escape sequences
+ (e.g <code>&</code> -> <code>\u0026</code>) to comply with
+ <a href="http://www.ietf.org/rfc/rfc4627.txt">RFC 4627</a>.
+ </td>
+</tr>
+
+<tr><td><code>:none</code></td><td></td>
+ <td>leaves the variable as is (used to disable <A
+ HREF="#auto_escape">auto-escaping</A>)</td>
+</tr>
+
+<tr><td><code>:pre_escape</code></td><td><code>:p</code></td>
+ <td>pre-escapes the variable before output (same as html_escape but
+ whitespace is preserved; useful for <pre>...</pre>)</td>
+</tr>
+
+<tr><td><code>:url_escape_with_arg</code></td><td><code>:U</code></td>
+ <td>special purpose url escaping. See
+ <a href="#url_escape_args">:I and :U Arguments</a>
+ below for details.</td>
+</tr>
+
+<tr><td><code>:url_query_escape</code></td><td><code>:u</code></td>
+ <td>performs URL escaping on the variable before output.
+ space is turned into +, and everything other than [0-9a-zA-Z.,_:*/~!()-], is
+ transformed into %-style escapes. Use this when you are building
+ URLs with variables as parameters:
+ <pre><a href="http://google.com/search?q={{QUERY:u}}">{{QUERY:h}}</a></pre>
+ </td>
+</tr>
+
+<tr><td><code>:xml_escape</code></td><td></td>
+ <td>xml-escapes the variable before output
+ (the five characters <code><>&"'</code> become
+ <code>&lt&gt;&amp;&quot;&#39;</code>)
+ suitable for content returned in raw XML. It is not intended
+ for escaping content within CDATA blocks.</td>
+</tr>
+
+</table>
+
+<p>The <code>*_with_arg</code> modifiers require an argument to
+specify the type of escaping to use. The following sections list
+the supported arguments for each of these modifiers.
+
+<h4 id="html_escape_args">:H Arguments</h4>
+<p>Here are the values that are supported by
+the <code>html_escape_with_arg</code> modifier:</p>
+<table border="1" cellpadding="3" summary="Arguments for :H modifier">
+<tr><th>value</th><th>description</th></tr>
+
+<tr><td><code>=snippet</code></td>
+ <td>like <code>html_escape</code>, but allows HTML entities and
+ some tags to pass through unchanged. The allowed tags
+ are <code><br></code>, <code><wbr></code>, <code><b></code>,
+ and <code></b></code>.</td>
+</tr>
+
+<tr><td><code>=pre</code></td>
+ <td>same as <code>pre_escape</code></td>
+</tr>
+
+<tr><td><code>=url</code></td>
+ <td>same as <code>:U=html</code> below. For backwards compatibility.</td>
+</tr>
+
+<tr><td><code>=attribute</code></td>
+ <td>replaces characters not safe for an use in an unquoted
+ attribute with underscore. Safe characters are alphanumeric,
+ underscore, dash, period, and colon.</td>
+</tr>
+
+</table>
+
+<h4 id="url_escape_args">:I and :U Arguments</h4>
+<p>Here are the values that are supported by
+the <code>img_src_url_escape_with_arg</code> and
+<code>url_escape_with_arg</code> modifiers:</p>
+<table border="1" cellpadding="3" summary="Arguments for :I and :U modifiers">
+<tr><th>value</th><th>description</th></tr>
+
+<tr><td><code>=html</code></td>
+ <td>Ensures that a variable contains a safe URL. Safe means that
+ it is either a http or https URL, or else it has no protocol
+ specified.
+ <ul>
+ <li>If the URL is safe, the modifier HTML-escapes the URL.
+ <li>Otherwise, the modifier replaces the unsafe URL with one of the
+ following values:
+ <ul>
+ <li><code>/images/cleardot.gif</code> (the <code>:I</code>
+ modifier)
+ <li><code>#</code> (the <code>:U</code> modifier)
+ </ul>
+ </li>
+ </ul>
+ <b>Do not use <code>:U</code> for image URLs.</b> Use <code>:I</code>
+ instead. <code>#</code> is not a safe replacement for an image URL.
+ <code><img src=#></code> can cause each browser to request the
+ entire page again.
+ </td>
+</tr>
+
+<tr><td><code>=javascript</code></td>
+ <td>Same as <code>=html</code>, but using javascript escaping
+ instead of html escaping.</td>
+</tr>
+
+<tr><td><code>=css</code></td>
+ <td>Same as <code>=html</code> but using CSS escaping instead
+ of html escaping so that the variable can be safely inserted
+ within a CSS <code>@import</code> statement or a CSS property.
+ The characters in [\r\n()'"<>*\] are transformed
+ into %-style escapes.</td>
+</tr>
+
+<tr><td><code>=query</code></td>
+ <td>(Supported for <code>:U</code> only) Same as
+ <code>url_query_escape</code>.</td>
+</tr>
+
+</table>
+
+<h4 id="javascript_escape_args">:J Arguments</h4>
+<p>Here are the values that are supported by
+the <code>javascript_escape_with_arg</code> modifier:</p>
+<table border="1" cellpadding="3" summary="Arguments for :J modifier">
+<tr><th>value</th><th>description</th></tr>
+
+<tr><td><code>=number</code></td>
+ <td>Ensures that the variable is a valid number or boolean
+ javascript literal. This includes booleans
+ <code>true</code> and <code>false</code>, decimal
+ numbers (e.g. <code>4.10</code> or <code>-5.01e+10</code>)
+ as well as hex numbers (e.g. <code>0x5FF</code>). This modifier
+ is intended to ensure the variable not enclosed in
+ quotes cannot contain javascript code that may execute. It does
+ not guarantee that the variable is syntactically well-formed.
+ If the variable is safe, it is returned
+ as-is, otherwise it is replaced with <code>null</code>.
+ In the future we may add more logic to support objects and
+ arrays.</td>
+</tr>
+</table>
+
+<h3> Custom Modifiers </h3>
+
+<p>In addition to the built-in modifiers, you can write your own
+modifier. Custom modifiers must have a name starting with "x-", and
+the name can contain alphanumeric characters plus dashes and
+underscores. Custom modifiers can also accept values with any
+character except for : and <code>}</code>. For example
+this template could be a valid use of a custom modifier:</p>
+
+<pre>
+{{VAR:x-my_modifier:value1,value2,value3 has spaces,etc}}
+</pre>
+
+<p>See <code><template_modifiers.h></code> for details on how to
+write a modifier and how to register it. In short, you write a
+modifier by subclassing <code>ctemplate::TemplateModifier</code> and
+overriding the <code>Modify</code> method, and you register it by
+calling <code>ctemplate::AddModifier()</code> Here is an example of
+the code for a custom modifier:</p>
+<pre>
+ class StarEscape : public ctemplate::TemplateModifier {
+ void Modify(const char* in, size_t inlen,
+ const ctemplate::PerExpandData* per_expand_data,
+ ctemplate::ExpandEmitter* outbuf, const string& arg) const {
+ outbuf->Emit(string("*") + string(in, inlen) + string("*"));
+ }
+ };
+</pre>
+
+
+<h3> Subclassing TemplateModifier </h3>
+
+<p>The minimum work to create a custom modifier is to subclass
+<code>TemplateModifier</code> and override the <code>Modify()</code>
+method. <code>Modify()</code> takes as input the value of the text to
+be modified, as well as the <A HREF="#per_expand_data">per expand
+data</A> associated with this <code>Expand()</code> call. The method
+may use this input, plus any other data it may have, to generate
+output, which it should write into the given
+<code>ExpandEmitter</code>.</p>
+
+<p>The subclass can also override <code>MightModify()</code>. This is
+useful for modifiers that are typically a no-op (in which case the
+modifier is just doing busy-work, copying its input to the output
+<code>ExpandEmitter</code>). If <code>MightModify()</code> returns
+false, the template system will avoid calling <code>Modify()</code> at
+all on that variable, avoiding the busy-work copy.</p>
+
+
+<h3> AddModifier() </h3>
+
+<p> AddModifier() is used to register a custom modifier,
+so the modifier can be used in templates. The name of the modifier
+must start with <code>x-</code>. </p>
+
+
+<h3> AddXssSafeModifier() </h3>
+
+<p> <code>AddXssSafeModifier()</code> is used to register a custom
+modifier that can work well with the <A
+HREF="auto_escape.html">auto-escape system</A>. It is used when the
+modifier produces output that is "safe" from cross-site scripting
+attacks in all contexts in which it might be used. For instance, a
+modifier that only emits numbers is xss-safe if it's only used in html
+or javascript contexts.</p>
+
+
+<h3> <A NAME="auto_escape">Auto-escaping and Manual Escaping</A> </h3>
+
+<p>If the <A HREF="auto_escape.html">auto-escape pragma</A> is used
+in a document, then all variables will be auto-escaped, even if
+explicit modifiers are used on the variable. The rules are a little
+complicated:</p>
+
+<ul>
+ <li> If the explicit modifier is a built-in modifier, and that
+ modifier is "compatible" with the modifier that auto-escape
+ would perform ("compatible" means it safely escapes in at least
+ as many contexts as the auto-escape modifier), then only the
+ explicit modifier is applied, and no further auto-escaping is
+ done. </li>
+
+ <li> If the explicit modifier is a custom modifier registered using
+ AddXssSafeModifier(), no further auto-escaping is
+ done. </li>
+
+ <li> If the explicit modifier is the :none modifier, no
+ further auto-escaping is done. This is the mechanism for
+ manually turning off auto-escaping. </li>
+
+ <li> In all other situations, auto-escaping will be performed after
+ the explicit modifiers have all run. </li>
+</ul>
+
+
+<h2> <A NAME="per_expand_data">The <code>PerExpandData</code> Class</A> </h2>
+
+<p><code>ExpandWithData()</code> and
+<code>TemplateModifier::Modify()</code> both take a
+<code>PerExpandData</code> object. Per-expand data is applied to all
+templates that are seen while expanding: not only the template you
+called <code>ExpandWithData()</code> on, but also sub-templates that
+are brought in via template-includes (<code>{{>INCLUDE}}</code>).
+
+<p>There are several types of per-expand data you can set, by calling
+the appropriate method on a <code>PerExpandData</code> object.</p>
+
+
+<h3> SetAnnotateOutput() </h3>
+
+<p>This is a debugging function. When expanding this template, it adds
+marker-strings to the output to indicate what template-substitutions
+the system made. This takes a string argument which can be used to
+shorten the filenames printed in the annotations: if the filename
+contains the string you give, everything before that string is elided
+from the filename before printing. (It's safe to just always pass in
+the empty string.)</p>
+
+
+<h3> SetAnnotator() </h3>
+
+<p>This overrides the default text-based annotation used by
+<code>SetAnnotateOutput()</code>. If this is set and
+<code>SetAnnotateOutput()</code> is called, the per-expand data will
+use this <A
+HREF="#template_annotator"><code>TemplateAnnotator</code></A> instance
+to do the annotation, rather than the default instance.</p>
+
+
+<h3> InsertForModifiers() and LookupForModifiers() </h3>
+
+<p><code>InsertForModifiers()</code> stores an arbitrary key/value
+pair in the <code>PerExpandData</code> structure. This is used with
+<A HREF="#template_modifier">template modifiers</A>: the
+<code>PerExpandData</code> object passed to
+<code>ExpandWithData()</code> is made available to every template
+modifier that is called during expand time (including any custom
+modifiers). The intended use of this functionality is to allow a
+modifier to work one way when expanding a template with dictionary A,
+and another way when expanding a template with dictionary B. For
+instance, a modifier might encrypt part of a webpage using a user's
+secret-key, which is of course different for every expansion of the
+webpage.</p>
+
+<p><code>LookupForModifiers()</code> can be used by a
+template-modifier to read the key/value pair inserted by
+<code>InsertForModifiers()</code>.
+<code>LookupForModifiersAsString()</code> is the same, but returns the
+value as a char* rather than a void*, for convenience.</p>
+
+
+<h3> SetTemplateExpansionModifier() </h3>
+
+<p>This is an advanced feature for those who need a custom hook into
+template expansion. It will not be used by most programmers. It
+takes a template-modifier as its argument, but this template modifier
+is treated specially: instead of applying when an appropriate magic
+string appears in the text of a template, it applies every time a
+template is expanded during a call to <code>ExpandWithData()</code>.
+Note this means that it's called not only after the top-level
+template, that <code>ExpandWithData()</code> is called on, is
+expanded, but also on every sub-template that is expanded due to a
+template-include.</p>
+
+<p>This unusual functionality has a few unusual properties. Since the
+template expansion modifier is not called in normal fashion, the
+normal <code>arg</code> argument to the template modifier does not
+make sense. Instead, the <code>arg</code> is set to the path of the
+template which is being expanded. Also, template expansion modifiers
+can be expensive, since they are applied pretty indiscriminately, so
+it can be worth implementing the <code>MightModifiy()</code> predicate
+for the passed-in <code>TemplateModifier</code> to avoid unnecessary
+work.</p>
+
+
+<h2> <A NAME="template_annotator">The <code>TemplateAnnotator</code>
+ Class</A> </h2>
+
+<p>The <code>TemplateAnnotator</code> class is used to pass in to <A
+HREF="#per_expand_data"><code>PerExpandData::SetAnnotator()</code></A>,
+to control how expand-time annotation is done. This is meant to be
+used as a debugging routine.</p>
+
+<p>This class is an abstract base class; <code>SetAnnotator()</code>
+takes a subclass that implements the various methods of the base
+class. These methods control the action taken when various template
+markers are seen during template expansion.</p>
+
+<p><code>template_annotator.h</code> defines the abstract base class,
+and also a concrete subclass that is used by default for annotation if
+<code>SetAnnotator()</code> is not called.</p>
+
+
+<h2> <A NAME="template_dictionary_peer">The
+ <code>TemplateDictionaryPeer</code> Class</A> </h2>
+
+<p>By design, it is not possible to view the contents of a
+<code>TemplateDictionary</code>; we want to make sure the interface
+between the logic layer of the application and the presentation layer
+of the template goes in only one direction. While generally this
+keeps programs as clean as possible, it presents problems in testing
+code, which may want to verify that a given
+<code>TemplateDictionary</code> has been filled properly. The
+<code>TemplateDictionaryPeer</code> addresses this need. It lives in
+<code>template_test_util.h</code>.</p>
+
+<p>Some of the methods of <code>TemplateDictionaryPeer</code> are
+useful for internal tests only. Below are some of the methods that
+are most useful for user-level tests.</p>
+
+
+<h3> STS_INIT_FOR_TEST </h3>
+
+<p>This macro allows use of <code>STS_INIT</code> for testing, even
+when the input pointer is not guaranteed to be allocated for the
+entire length of the test (it must, of course, be allocated for the
+entire lifetime of the template being tested). Since normally
+<code>STS_INIT</code> requires inputs to have static duration, this
+allows for more flexibility in tests, at the cost of worse memory
+management and decreased code safety (in that it's possible to
+accidentally violate the lifetime requirements).</p>
+
+
+<h3> GetSectionValue() </h3>
+
+<p>This returns the value for the named variable. It uses normal
+template scoping rules to resolve the name.</p>
+
+
+<h3> IsHiddenSection() and IsHiddenTemplate() </h3>
+
+<p>Checks if a section or sub-template is "hidden" (that is, won't be
+displayed at all).</p>
+
+
+<h3> GetSectionDictionaries() and GetIncludeDictionaries() </h3>
+
+<p>Returns all the sub-dictionaries for a given section or
+template-include, in a vector.</>
+
+
+<h3> Other Testing Functions </h3>
+
+<p>template_test_util.h has other useful routines for
+testing, such as ExpandIs(), which tests whether a
+template + dictionary pair expands into an expected string. See the
+header file for details.</p>
+
+
+<h2> <A NAME="expand_emitter">The <code>ExpandEmitter</code> Class</A> </h2>
+
+<p>There are two overloads of <A
+HREF="#expand_template"><code>ExpandTemplate()</code></A>: the first
+emits the expanded template to a C++ string, and the second emits to
+an <code>ExpandEmitter</code>: an abstract base class that serves as a
+data source. It supports just one overloaded method,
+<code>Emit()</code>, that can take a char, a char*, or a C++ string as
+input.</p>
+
+<p>Using this class requires subclassing <code>ExpandEmitter</code>
+and providing the various definitions for <code>Emit()</code>. For
+instance, a subclass might provide definitions of <code>Emit()</code>
+that send the input bytes out to a network socket.</p>
+
+<p>In addition to defining the abstract base class,
+<code>template_emitter.h</code> provides a sample concrete subclass
+implementation, for emitting to a string.</p>
+
+
+<h2> <A NAME="template_string">The <code>TemplateString</code> and
+ <code>StaticTemplateString</code> Classes</A> </h2>
+
+<p><code>TemplateString</code> is a string-like implementation.
+Ctemplate uses <code>TemplateString</code> almost exclusively,
+internally. Many of the public API methods, such as
+<code>TemplateDictionary::SetValue()</code>, also take
+<code>TemplateString</code> as input. <code>TemplateString</code>
+has implicit constructors for both C++ strings and char*'s, so every
+method that takes a <code>TemplateString</code> will also work if
+given a C++ string or a char*. If you have a char* and know its
+length, you can save a bit of work by explicitly constructing a
+<code>TemplateString</code> with a char* + length, for instance:</p>
+<pre>
+ dict->SetValue(ctemplate::TemplateString("MYVAR", 5), value);
+</pre>
+
+<p>Some compile-time tools work with <code>TemplateString</code> to
+offload computation from runtime to compile-time. This is possible
+because the Ctemplate code often stores a hash of a string
+rather than a string directly. For static, immutable strings,
+<code>TemplateString</code> can store a pre-computed hash value. This
+functionality is used by <A
+HREF="#make_tpl_varnames_h"><code>make_tpl_varnames_h</code></A>. Thus,
+using this tool to create constants to use for <code>SetValue()</code>
+keys provides not only protection against typos, but a speed
+improvement as well.</p>
+
+<p>For immutable strings in your code, you can create efficient
+compile-time template-string objects of your own -- in this case of
+type <code>StaticTemplateString</code> -- by using the
+<code>STS_INIT</code> macro, like so:</p>
+<pre>
+static const StaticTemplateString kSectName =
+ STS_INIT(kSectName, "test_SetAddSectionDictionary");
+</pre>
+
+<p>The string variable's name, <code>kSectName</code> is repeated
+twice. The variable's value is specified inside the macro. Note that
+this macro should be used at the top level of a file, not inside
+functions (even when the variables are made static), and you should
+define the <code>StaticTemplateString</code> exactly as above:
+<code>static const StaticTemplateString</code>. Otherwise, the
+undefined constructor/destructor order of C++ may result in surprising
+behavior, wherein the <code>StaticTemplateString</code> is not
+initialized when it ought to be.</p>
+
+
+<h2> The <code>Template</code> Class </h2>
+
+<p>In older version of ctemplate, the <code>Template</code> class,
+which holds parsed templates, was a major part of the template
+workflow: the common template use-case would be:</p>
+<pre>
+ Template* tpl = Template::GetTemplate(filename, strip_mode);
+ TemplateDictionary dict(name);
+ tpl->Expand(&dict, &outstring);
+</pre>
+
+<p>In current use, this model is deprecated in favor of the single
+<code>ExpandTemplate()</code> call; support for <code>Template</code>
+methods may be removed entirely in future versions of ctemplate.
+However, you may still find older code using this old formulation.</p>
+
+
+<h2> <A NAME="auto_escaping">Auto-Escaping</A> </h2>
+
+<p>The <a href="auto_escape.html">Guide to using Auto Escape</a> has
+an overview of Auto Escape as well as discussion of its limitations.
+<!-- TODO(csilvers): move that information here? -->
+To use it, put the following text at the top of the template:</p>
+<pre>
+ {{%AUTOESCAPE context="CONTEXT" [state="STATE"]}}
+</pre>
+
+<p>Description of the arguments:</p>
+<ul>
+ <li> The context attribute is one of <code>HTML</code>,
+ <code>JAVASCRIPT</code>, <code>CSS</code>,
+ <code>JSON</code> or <code>XML</code>. It must correspond
+ to the context in which the browser will interpret this
+ template. <b>Warning:</b> Setting the wrong context will
+ result in wrong escaping applied to all variables in
+ the given template. In particular, if the template starts with
+ a <code><script></code> tag, its context is
+ <code>HTML</code> and not <code>JAVASCRIPT</code>. Auto-Escape
+ will recognize the <code><script></code> tag and hence
+ properly Javascript-escape the variables within it. Similarly,
+ if the template starts with a <code><style></code> tag,
+ its context is <code>HTML</code> and not <code>CSS</code>.
+</li>
+ <li> The state attribute is commonly omitted. It accepts the
+ value <code>IN_TAG</code> in the <code>HTML</code> context
+ to indicate that the template only contains (one or more)
+ HTML attribute name and value pairs that are part of an
+ HTML tag formed in a parent template.
+</ul>
+
+<p>This will auto-escape every variable in the template. To turn off
+auto-escaping for a particular variable, you can apply the
+<code>none</code> modifier, like so: <code>{{MYVAR:none}}</code>.
+Here is an example of an autoescaped document:</p>
+
+<pre>
+ {{%AUTOESCAPE context="HTML"}}
+
+ <body>
+ <p>Hello {{USER}}</p>
+ <p><a href="{{URL}}">Your Account</a></p>
+ <p>Your identifier: {{ID:none}}{{! This is dangerous! }}</p>
+ </body>
+</pre>
+
+
+<h2> Development Tools </h2>
+
+<p>This package includes several tools to make it easier to use write
+and use templates.</p>
+
+
+<h3> <A name="make_tpl_varnames_h">make_tpl_varnames_h:
+ Template Syntax Checker and Header File Generator</A> </h3>
+
+<p><code>make_tpl_varnames_h</code> is a "lint" style syntax checker
+and header file generator. It takes the names of template files as
+command line arguments and loads each file into a Template object by
+retrieving the file via the Template factory method. The loading of
+the file does pure syntax checking and reports such errors as
+mis-matched section start/end markers, mis-matched open/close
+double-curly braces, such as <code>"{{VAR}"</code>, or invalid
+characters in template variables/names/comments.</p>
+
+<p>If the template passes the syntax check, by default the utility
+then creates a header file for use in the executable code that fills
+the dictionary for the template. If the developer includes this
+header file, then constants in the header file may be referenced in
+the dictionary building function, rather than hard-coding strings as
+variable and section names. By using these constants, the compiler
+can notify the developer of spelling errors and mismatched names.
+Here's an example of how this is used, and how it helps prevent
+errors:</p>
+
+<pre>
+ const char * const kosr_RESULT_NUMBER = "RESULT_NUMBER"; // script output
+ dict.SetValue("RESSULT_NUMBER", "4"); // typo is silently missed
+ dict.SetValue(kosr_RESSULT_NUMBER, "4"); // compiler catches typo
+</pre>
+
+<p>Each constant is named as follows:</p>
+
+<ul>
+ <li> The initial letter 'k', indicating a defined constant. </li>
+
+ <li> One or more prefix letters which are derived from the
+ template file name. These prefix letters consist of the first
+ letter of the file name, followed by the first letter following
+ each underscore in the name, with the exception of the letter
+ 'p' when it is followed by the letters "ost", as is a <A
+ HREF="tips.html#versioning">recommended convention</A> for
+ template versioning. For example, the prefix letters for the
+ file <code>one_search_result_post20020815.tpl</code> are
+ <code>osr</code>. </li>
+
+ <li> An underscore. </li>
+
+ <li> The variable or section name itself, same casing. </li>
+</ul>
+
+<p>As an example, the section name "RESULT_NUMBER" in the file
+one_search_result_post20020815.tpl would be given the constant name
+<code>kosr_RESULT_NUMBER</code> and would appear in the header file as
+<code>const char * const kosr_RESULT_NUMBER = "RESULT_NUMBER";</code>
+-- as in the example above. (The variable is actually a
+<code>StaticTemplateString</code>, not a char*, but the basic idea
+holds.)</p>
+
+<p>
+An alternate output directory may be specified by the command line
+flag <code>--header_dir</code>.
+</p>
+
+<p>The name of the generated header file is the same as the name of
+the template file with an extension added to the name. By default,
+that extension is <code>.varnames.h</code>. In the above example, the
+header file containing the constant declarations would be named
+<code>one_search_result_post20020815.tpl.varnames.h</code>. An
+alternate extension may be provided via the command line flag
+<code>--outputfile_suffix</code>.</p>
+
+<p>Important command line flags:</p>
+
+<ul>
+ <li> <code>--noheader</code> -- Indicates that a header file
+ should not be generated; only syntax checking should be done. </li>
+
+ <li> <code>--header_dir</code> -- sets the directory where the header
+ is written. Default: "./" </li>
+
+ <li> <code>--template_dir</code> -- sets the template root
+ directory. Default: <code>./</code> which is the correct
+ specification when it is run from the directory where the templates
+ are located. This is only used if the input template filenames
+ are specified as relative paths rather than absolute
+ paths. </li>
+
+ <li> <code>--outputfile_suffix</code> -- the extension added to the
+ name of the template file to create the name of the generated
+ header file. Default: <code>.varnames.h</code>.
+</ul>
+
+<p>For a full list of command line flags, run
+<code>make_tpl_varnames_h --help</code>.</p>
+
+
+<h3> <A name="template_converter">template-converter: convert a
+ template to a C++ string</A> </h3>
+
+<p><code>StringToTemplateCache()</code> lets you load a template
+from a string instead of a file. Applications may prefer this option
+to reduce the dependencies of the executable, or use it in
+environments where data files are not practical. In such cases,
+<code>template-converter</code> can be used as a template "compiler",
+letting the developer write a template file as a data file in the
+normal way, and then "compiling" it to a C++ string to be included in
+the executable.</p>
+
+<p>Usage is <code>template-converter <template filename></code>.
+C++ code is output is to stdout; it can be stored in a .h file or
+included directly into a C++ file. Perl must be installed to use this
+script.</p>
+
+
+<hr>
+<ul>
+ <li> <A HREF="guide.html">User's Guide</A> </li>
+<!--
+ <li> <A HREF="reference.html">Reference Manual</A> </li>
+-->
+ <li> <A HREF="auto_escape.html">Auto Escape</A> </li>
+ <li> <A HREF="tips.html">Tips</A> </li>
+ <li> <A HREF="example.html">Example</A> </li>
+</ul>
+
+<hr>
+<address>
+Craig Silverstein<br>
+<script type=text/javascript>
+ var lm = new Date(document.lastModified);
+ document.write(lm.toDateString());
+</script>
+</address>
+
+</body>
+</html>
+
diff --git a/doc/tips.html b/doc/tips.html
new file mode 100644
index 0000000..723065b
--- /dev/null
+++ b/doc/tips.html
@@ -0,0 +1,474 @@
+
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<title>Tips and Guidelines for Using the Ctemplate System</title>
+
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<link href="designstyle.css" type="text/css" rel="stylesheet">
+<style type="text/css">
+ ol.bluelist li {
+ color: #3366ff;
+ font-family: sans-serif;
+ }
+ ol.bluelist li p {
+ color: #000;
+ font-family: "Times Roman", times, serif;
+ }
+ ul.blacklist li {
+ color: #000;
+ font-family: "Times Roman", times, serif;
+ }
+</style>
+</head>
+
+<body>
+
+<h1>Tips and Guidelines for Using the Ctemplate System</h1>
+<small>(as of 10 March 2010)</small>
+
+<br>
+
+<p>The <A HREF="guide.html">basic rules</A> of the template system are
+enough to use it, but over time, we at Google have developed some
+tips, guidelines, and best practices that make it easier to use
+templates effectively, and to avoid common template errors.</p>
+
+
+<h2> Program Design Considerations </h2>
+
+<h3> <a name=versioning>Template naming and versioning</a> </h3>
+
+<p> Early in Google's use of templates, we noticed a problem: if a
+binary that uses a template and its corresponding template were both
+modified, particularly if the change were such that the old binary
+could not work with the new template or the new binary could not work
+with the old template, then somehow they both had to be deployed at
+the same instant to not present errors to our users. This was hard to
+do. The solution was to adopt a template naming and versioning
+convention. The procedure to use it follows:</p>
+
+<ul>
+ <li> Each template name ends with <code>_postYYYYMMDD.tpl</code>,
+ where YYYMMDD is the date of this version's initial
+ creation. </li>
+
+ <li> Before making (non-backward-compatible) modifications to a
+ template, copy the template to a new name, incorporating a
+ later date than the original one being copied. </li>
+
+ <li> Edit the new file, and push it to the production server. </li>
+
+ <li> Finally, update the code to refer to the new template-name
+ (ideally, using the <A
+ HREF="guide.html#register"><code>RegisterTemplateFilename</code>
+ idiom</A>), and push the new executable to the production
+ server. </li>
+</ul>
+
+<p>When this convention is followed, the new template file does not
+overwrite the old one when it is deployed, because it is a new file
+with a new name. The old template file is still there to be used as
+long as the old binary is still in production and the new template
+file just sits there being ignored. Then when the new binary finally
+gets deployed, it immediately starts using the new template file,
+because it is coded (in <code>RegisterTemplateFilename</code>) to do
+so. After that, it is the old template file that continues to sit
+there ignored.</p>
+
+<p>The <A
+HREF="reference.html#make_tpl_varnames_h"><code>make_tpl_varnames_h</code>
+utility</A> knows about the "_postYYYYMMDD" naming convention, so it
+is important that you use that convention exactly if you use the
+<code>make_tpl_varnames_h</code>.</p>
+
+
+<h3> Processing Phases </h3>
+
+<p>Typically a program using the Ctemplate System will
+perform the following phases, usually in this order:</p>
+
+<ol>
+ <li> Retrieve and prepare the data used to fill a dictionary. </li>
+
+ <li> Build the data dictionary, including all its
+ sub-dictionaries, that will supply the values to the
+ designated template object, its sections, and its
+ included templates. </li>
+
+ <li> Retrieve the top-level template object required to
+ format the data. (This may or may
+ not involve reading and parsing a template file,
+ depending on whether the requested file has already
+ been read and parsed by the running program or
+ whether that file has been marked "reload if changed"
+ and was in fact changed.) </li>
+
+ <li> Expand the template object into an output buffer
+ using the completed data dictionary. </li>
+
+ <li> Output the buffer. </li>
+
+ <li> Clean up: Destroy the top-level data dictionary
+ whenever it is no longer needed. </li>
+
+ <li> Optionally, clear the cache at the end of program
+ execution. </li>
+</ol>
+
+
+<h3> <A NAME="oneone">One template / One procedure call</A> </h3>
+
+<p> Most of the code of the program will be in Phases 1 and
+2. Clearly, Phase 1 is outside the scope of the template system. But
+in designing the code for Phase 2 (building the data dictionary), it
+is wise to have the structure of the program reflect the structure of
+the templates being used. Specifically, there should be a single
+procedure call to build the dictionary for a single template. That
+procedure call should take parameters that include all the data
+required to populate the data dictionary for that template and all the
+templates it includes. Following this "one template/one procedure
+call" guideline further, for each included template, another procedure
+should be called to populate the (or <i>each</i>) data dictionary for
+that included template. This maintains the "one template/one procedure
+call" principle in a nested fashion that reflects the nesting of the
+templates.</p>
+
+<p> This is not to imply that the "one procedure call" for a template
+should not be modularized into sub-procedures for readability and
+maintainability, or that it should not call other auxilliary
+procedures for such things as formatting the data and converting it to
+the appropriate strings, etc. But it does mean that there should be
+one entry point for building the dictionary tree for one template and
+that entry point should show the data dependencies of that template
+through its parameter list. This code for populating the data
+dictionary should <i>NOT</i> be intermingled with data gathering code
+that should have been done in Phase 1.</p>
+
+<p>(Inside Google, the convention has been used to name the dictionary
+building procedure using the pattern <code>fill_..._dictionary</code>
+where the dots are related to the name of the template the data is
+being prepared for. For instance, the data for the template named
+one_search_result.tpl might be placed in a dictionary via a function
+named <code>fill_one_search_result_dictionary</code>.)
+
+
+<h2> <A name=tips>Tips, Idioms, and Conventions</a> </h2>
+
+<ol class=bluelist>
+
+<li> Choose template names to create unique constant prefixes.
+
+ <p>Template names should contain <em>at least two words</em>
+ to avoid constant prefix clashes (e.g. <code>kxy_</code>
+ instead of <code>kx_</code> ) The name of a new template
+ should be checked against the existing names before
+ proceeding. If your new template name produces a prefix that
+ conflicts with an already existing template, you should change
+ the name of your new template, even though it may be the only
+ perfect name you can come up with. You'll have to use a less
+ than perfect name in that case. (See "Template Syntax Checker
+ and Header File Generator" below for more explanation about
+ constant prefixes.)</p> </li>
+
+<li> <a name="tip_setformattedvalue"></a>Use SetFormattedValue
+ discriminately.
+
+ <p> This method should never be used to sneak HTML into the
+ executable as in</p>
+
+ <pre>
+ dictionary->SetFormattedValue(kxy_VAR,
+ "<b>%s</b>",
+ some_const_char_string);
+ </pre>
+
+ <p>In that case, the <code><b></code> and
+ <code></b></code> should be moved into the template.</p>
+
+<li> Never have a section encompass an entire template.
+
+ <p>If the first line of a template is a start section marker
+ and the last line is its matching end section marker, then
+ those markers are unnecessary in almost all cases. They are
+ usually put there to allow the entire template to be hidden or
+ iterated, but since it encompasses the entire file, the
+ section may be hidden by not expanding the file (or by hiding
+ the template-include section that includes the file) and it
+ may be iterated by iterating the template-include marker of
+ the including template. (The only exception might be if the
+ entire page is to be iterated, but this seems a bit of a
+ stretch.)</p> </li>
+
+<li> An included template is just a section whose contents are
+ located in a separate file. You may iterate over it just
+ like you do sections.
+
+ <p>For example, if your template has the following
+ template-include marker:</p>
+ <pre>
+ {{>MY_INCLUDED_TEMPLATE}}
+ </pre>
+ <p>you may call</p>
+ <pre>
+ ctemplate::TemplateDictionary *child_dict =
+ dictionary->AddIncludeDictionary(kxy_MY_INCLUDED_TEMPLATE);
+ </pre>
+ <p>to iterate that section. (Note: Make sure you call
+ <code>child_dict->SetFilename()</code>! If your included
+ template is not showing in the output, this is the first thing
+ you should check.)</p> </li>
+
+<li> The recommended idiom to fill an include-template dictionary is
+ like this:
+ <pre>
+ fill_include_template_dictionary(dict->AddIncludeDictionary(name), ...);
+ </pre>
+
+ <p>But what do you do if you decide, in
+ <code>fill_include_template_dictionary</code>, that you don't
+ want to display anything for this include-template after all? It
+ seems like it's too late: you've already created the
+ sub-dictionary. The solution is simple: just be sure that
+ <code>fill_include_template_dictionary()</code> doesn't call
+ <code>SetFilename()</code> in that case.</p>
+
+<li> Never have a section which only contains another section.
+ <p>For example, don't do this:</p>
+ <pre>
+ {{#OUTER_SECTION}}
+ {{#INNER_SECTION}}
+ section contents here
+ {{/INNER_SECTION}}
+ {{/OUTER_SECTION}}
+ </pre>
+ <p>or this equivalent template code (see the previous item):</p>
+ <pre>
+ {{#OUTER_SECTION}}
+ {{>INCLUDED_SECTION}}
+ {{/OUTER_SECTION}}
+ </pre>
+
+ <p>This is usually done because the developer thinks the outer
+ section must be used to hide the section when the inner
+ section, intended for iteration, has no iterations. In both
+ cases, you should only have one section (either
+ <code>INNER_SECTION</code> or <code>INCLUDED_SECTION</code> in
+ the examples) and iterate that section either 0 times or more
+ than 0 times. It's the wonder of the dual use of sections,
+ i.e. that they may be conditional or iterative or, in this case,
+ both.</p>
+
+ <p>A related suggestion: Do not have a section whose entire
+ contents is one variable marker with nothing else, unless you
+ need to iterate over that section with multiple values of that
+ variable. You don't need the surrounding section just to hide
+ the marker. A variable marker that is not set, does not
+ produce output. By convention, we set such variables to the
+ empty string. But in neither case do you need to hide it by
+ hiding a surrounding section that contains nothing else.</p>
+
+<li> Use this hide/show idiom for <code>if-else</code> blocks.
+
+ <p>Since sections are hidden by default, you can use represent
+ if-else logic in your code via <code>ShowSection</code>. For
+ example:</p>
+
+ <pre>
+ if ( my_test ) {
+ dict->ShowSection(kxyz_TRUE_BLOCK);
+ [ more code to fill the values for that section]
+ } else {
+ dict->ShowSection(kxyz_FALSE_BLOCK);
+ [ more code to fill the values for that section]
+ }
+ </pre>
+
+<li> <code>Write...</code> vs. <code>Fill...Dictionary</code> methods
+ - Observe the proper division of labor, don't mix them.
+
+ <p>The output (or write) function should create the top level
+ template dictionary, call one or more fill-dictionary routines
+ with it, then get the template and expand it. It should not call
+ dictionary modifying methods, like <code>ShowSection</code>
+ and <code>SetValue</code>. By keeping these separated into
+ their own fill-dictionary routine, the code is more modular and
+ lends itself to template re-use. If you maintain the proper
+ division of labor, the template you are filling and outputting
+ may be filled and included in a larger template by someone
+ else.</p> </li>
+
+<li> Use <code>AddSectionDictionary</code> only when you want to
+ iterate over a section or, secondarily, if you need to avoid name
+ conflicts.
+
+ <p>Sometimes developers get the idea that every section requires
+ its own child dictionary created by an
+ <code>AddSectionDictionary</code> call. Because of variable
+ inheritence, this isn't usually so. The intended purpose of
+ <code>AddSectionDictionary</code> is to enable iteration over a
+ section. Secondarily, if the section contains generic names that
+ may conflict with the same name in other parts of the template,
+ it may be safer to call <code>AddSectionDictionary</code> to
+ create a separate namespace. In any case, do not assume you must
+ call <code>AddSectionDictionary</code> just because you are
+ working within a section. The main dictionary can be used for all
+ levels of conditional sections as long as you avoid name
+ conflicts by keeping the marker names unique.</p> </li>
+
+<li> Do not place <code>RegisterTemplateFilename</code>
+ statements in header (<code>.h</code>) files.
+
+ <p><code>RegisterTemplateFilename</code> is a macro that
+ instantiates a <code>TemplateNamelist</code> object. If you place
+ it in a header file, a different object will get created each time
+ it is included in another <code>.cc</code> file.
+
+ <p>The <code>RegisterTemplateFilename</code> statement and its
+ associated <code>#include</code> of the <code>varnames.h</code>
+ file should occur only in the <code>.cc</code> file that
+ implements the fill-dictionary routine for that template. You
+ should never have more than one
+ <code>RegisterTemplateFilename</code> for a single template and
+ you should try hard not to copy the <code>#include</code> file to
+ other files as well. The template versioning makes this more
+ important because a developer may not know that the template name
+ with included version number needs to be updated in more than one
+ file when versioning occurs. [Also see above for more information
+ about what routine uses the filename declared by the
+ <code>RegisterTemplateFilename</code> statement.]</p> </li>
+
+<li> Never reference more than one template in a
+ fill...dictionary method.
+
+ <p>Each template should have its own fill-dictionary
+ routine. That routine should only reference marker names defined
+ in that template. If this convention is followed, then all the
+ prefixes in a fill-dictionary routine will be the same. [Note
+ that an implication of this convention is that if the template
+ includes another template, via a template-include marker, then
+ containing template's fill-dictionary routine should call the
+ included template's fill-dictionary routine (being careful to
+ observe the convention described above). But
+ then, this is merely a restatement of <A HREF="#oneone">"One
+ template / One procedure call"</A>.]</p> </li>
+
+<li> Have fill...dictionary call <code>SetFilename</code> even if the
+ dictionary is never used for a template-include.
+
+ <p>SetFilename() is required when a dictionary is created via
+ <code>AddIncludeDictionary()</code>. However, it's safe to set
+ all the time. By setting it always, you make the code work
+ properly if this dictionary ever changes to be template-included
+ after all. Even if not, by saying what template file the
+ dictionary is intended to go with, you are self-documenting your
+ code.</p> </li>
+
+<li> Do not call <code>c_str()</code> on strings to pass them to
+ <code>TemplateDictionary</code> methods.
+
+ <p>Note that all the TemplateDictionary methods are defined to
+ take <code>TemplateString</code> objects. These are created
+ automatically from both strings and char*'s (and can be created
+ manually if you have a char* and a length). So if you have a
+ string, it's safe and efficient to just pass it in directly; you
+ do not need to extract the const char * from your string object
+ to pass it to these methods. For some reason, this is a common
+ error of novice template coders.</p>
+
+ <p>The one exception to this rule is when using the method
+ <code>SetFormattedValue</code>. When calling that
+ method, you must call <code>c_str()</code> on strings that are to
+ be inserted
+ into the format string, just as you would when providing data for
+ any other printf format string.</p> </li>
+
+<li> Do not use <code>SetGlobalValue</code> when you could use
+ <code>SetValue</code> or <code>SetTemplateGlobalValue</code>.
+
+ <p><code>SetGlobalValue</code> should be used quite rarely, for
+ constants that really are consistent across all your templates.
+ It's slower to look up a value in the global dictionary than it
+ is in the template-specific dictionary.</p> </li>
+
+<li> Do not use <code>StringToTemplateCache</code> unless you have
+ a specific need for its non-file-based attributes.
+
+ <p><code>ctemplate::StringToTemplateCache</code> was created for
+ use in highly constrained cases where file I/O may be impaired or
+ undesirable, for instance to produce a server error message
+ where there may be disk problems or to produce formatted
+ output where there are processes that do not have a facility
+ for updating data files dynamically. It is not recommended for
+ ordinary use since it cannot be updated dynamically via a
+ data-push; changes always require a binary push.</p>
+ </ul>
+ </li>
+
+<li> Use <A HREF="auto_escape.html">auto-escaping</A> to prevent
+ Cross-Site-Scripting security vulnerabilities.
+
+ <p>Use <code>{{%AUTOESCAPE}}</code> consistently. Use the
+ <code>:none</code> modifier to override autoesacping only in
+ those (usually rare) cases where there is a specific reason the
+ template variable should not be escaped, for example:
+ <ul class=blacklist>
+ <li>The template variable contains HTML markup that should be
+ interpreted by the browser. In this case you must be very careful to
+ ensure that the variable can in no case contain "harmful" HTML. Also,
+ keep in mind the <a href="#tip_setformattedvalue">above
+ recommendation</a> on the use of <code>SetFormattedValue</code> and
+ consider moving the HTML markup into the template.</li>
+
+ <li>The variable is known to be already escaped at the point it
+ is inserted into the template (for example, the value might be
+ kept in escaped form in a storage backend). Here, escaping again
+ via a variable-modifier would result in "double escaping". You
+ must ensure that the variable comes escaped in the appropriate
+ context (that is, if you're inserting the variable into an html
+ document, it's html-escaped and not java-escaped).</li>
+ </ul>
+ </li>
+
+<li> Do not leave an extra space when using <code>{{BI_SPACE}}</code>
+
+ <p>The built-in template variable <code>BI_SPACE</code> is itself
+ replaced by a single space. It is used where you need to make
+ sure a space is preserved at the end of a line. It is a common
+ mistake to leave an extra space before this marker, which results
+ in not one, but two, spaces created in the document.</p>
+
+ <p>Incorrect:</p><pre>
+<table border=0 {{BI_SPACE}}
+ align=center></pre>
+
+ <p>Correct:</p><pre>
+<table border=0{{BI_SPACE}}
+ align=center></pre>
+
+ </li>
+
+</ol>
+
+<hr>
+<ul>
+ <li> <A HREF="guide.html">User's Guide</A> </li>
+ <li> <A HREF="reference.html">Reference Manual</A> </li>
+ <li> <A HREF="auto_escape.html">Auto Escape</A> </li>
+<!--
+ <li> <A HREF="tips.html">Tips</A> </li>
+-->
+ <li> <A HREF="example.html">Example</A> </li>
+</ul>
+
+<hr>
+<address>
+Craig Silverstein<br>
+<script type=text/javascript>
+ var lm = new Date(document.lastModified);
+ document.write(lm.toDateString());
+</script>
+</address>
+
+</body>
+</html>
diff --git a/doc/xss_resources.html b/doc/xss_resources.html
new file mode 100644
index 0000000..96038e1
--- /dev/null
+++ b/doc/xss_resources.html
@@ -0,0 +1,71 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+ <title>Cross-Site Scripting Resources</title>
+
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <link href="designstyle.css" type="text/css" rel="stylesheet">
+ <style type="text/css">
+ <!--
+ ol.bluelist li {
+ color: #3366ff;
+ font-family: sans-serif;
+ }
+ ol.bluelist li p {
+ color: #000;
+ font-family: "Times Roman", times, serif;
+ }
+ ul.blacklist li {
+ color: #000;
+ font-family: "Times Roman", times, serif;
+ }
+ //-->
+ </style>
+</head>
+<body>
+
+<h1> <a name="XSS_Resources"></a>Cross-Site Scripting Resources</h1>
+<center><strong>Status: Current</strong>
+<small>(as of 17 August 2006)</small></center>
+<br>
+
+<p>Cross-Site Scripting (commonly abbreviated as XSS) is a security
+issue that arises when an attacker can cause client-side script (such as
+JavaScript) of his or her choosing to execute within another user's
+browser in the context of a given web-site or web-application. This may
+allow the attacker to steal that user's session cookies for the
+web-application in question, or otherwise manipulate that user's session
+context.
+
+<p>XSS vulnerabilities most often arise if a web-application renders
+data that originated from an untrusted source (such as a query
+parameter) in a HTML document without carefully validating or escaping
+that data.
+
+<p>The following online resources provide further information on XSS
+vulnerabilities and how to avoid them:
+
+<ul>
+ <li>The Open Web Application Security Project (OWASP) has an
+ <a
+ href="http://www.owasp.org/index.php/Cross_Site_Scripting">introductory
+ article</a> on XSS.
+ </li>
+
+ <li>In addition, the OWASP's <a
+ href="http://www.owasp.org/index.php/Category:OWASP_Guide_Project">Guide to Building Secure Web
+ Applications and Web Services</a> and the <a
+ href="http://www.owasp.org/index.php/Category:OWASP_Top_Ten_Project">"Top
+ Ten" Vulnerabilities</a> include sections on XSS.
+ </li>
+
+ <li>The CERT Coordination Center published <a
+ href="http://www.cert.org/tech_tips/malicious_code_mitigation.html">Understanding
+ Malicious Content Mitigation for Web Developers</a> and <a
+ href="http://www.cert.org/advisories/CA-2000-02.html">Advisory
+ CA-2000-02 Malicious HTML Tags Embedded in Client Web Requests</a>.
+
+ </li>
+</ul>
+</body>
+</html>