Blame - doc/reference.html - RealtimeRoboticsGroup/test

blob: 09eab1a9fb2e2793f72b158c6236c4707029c408 [file] [log] [blame]

Brian Silverman	70325d6	2015-09-20 17:00:43 -0400	[diff] [blame^]	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
				2
				3	<html>
				4	<head>
				5	<title>Ctemplate System Reference Guide</title>
				6
				7	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
				8	<link href="designstyle.css" type="text/css" rel="stylesheet">
				9	<style type="text/css">
				10	ol.bluelist li {
				11	color: #3366ff;
				12	font-family: sans-serif;
				13	}
				14	ol.bluelist li p {
				15	color: #000;
				16	font-family: "Times Roman", times, serif;
				17	}
				18	ul.blacklist li {
				19	color: #000;
				20	font-family: "Times Roman", times, serif;
				21	}
				22	</style>
				23	</head>
				24
				25	<body>
				26
				27	<h1>Ctemplate System Reference Guide</h1>
				28	<small>(as of
				29	<script type=text/javascript>
				30	var lm = new Date(document.lastModified);
				31	document.write(lm.toDateString());
				32	</script>)
				33	</small>
				34	<br>
				35
				36
				37	<h2> Overview </h2>
				38
				39	<p>The main class used by the template system is
				40	<code>TemplateDictionary</code>, which is used to expand a template
				41	file. It is used by the main functions for expanding a template,
				42	found in <code>template.h</code>.</p>
				43
				44	<p><code>TemplateCache</code> is used to hold a collection of
				45	<code>Template</code> objects. <code>TemplateNamelist</code> provides
				46	various introspection routines on collections of <code>Template</code>
				47	objects.</p>
				48
				49	<p><code>TemplateModifier</code> and <code>PerExpandData</code> are
				50	used to modify the values of a <code>TemplateDictionary</code> at
				51	expand time. <code>TemplateAnnotator</code> does too, but is intended
				52	for debugging purposes. <code>TemplateDictionaryPeer</code> is used
				53	for testing template code.</p>
				54
				55	<p><code>ExpandEmitter</code> provides the ability to emit an expanded
				56	template to an arbitrary output store.</p>
				57
				58	<p><code>TemplateString</code> is a string-like class that is built to
				59	be very efficient when used with the template system. For instance,
				60	tools are available to hash constant <code>TemplateString</code>
				61	objects at compile-time, speeding up their use at run-time.</p>
				62
				63	<p>The rest of this document describes these classes and functions in
				64	more detail, as well as build tools and other mechanisms for handling
				65	templates.</p>
				66
				67	<p>(Note: the code snippets below all assume the default configuration
				68	option is set, which puts template code in namespace
				69	<code>ctemplate</code>.)</p>
				70
				71	<h2> <A NAME="template">Expanding Templates</A> </h2>
				72
				73
				74	<h3> The Template Language </h3>
				75
				76	<p>Templates are strings that contain special formatting code called
				77	<em>template markers</em>. In the Ctemplate System, template
				78	strings are usually read from a file.</p>
				79
				80	<p>Anything found in a template of the form {{...}} is
				81	interpreted as a template marker. All other text is considered
				82	formatting text and is output verbatim at template expansion time.
				83	Outside of the template markers, templates may contain any text
				84	whatsoever, including (single) curly braces and NUL characters.</p>
				85
				86	<p>The template language has six types of markers:</p>
				87	<ol>
				88	<li> <b>Variable</b> markers, which are replaced by text based on
				89	dictionary values. Variable markers look like this:
				90	{{FOO}}</li>
				91
				92	<li> <b>Start section</b> and <b>end section</b> markers, which
				93	delimit sections which may appear zero, one, or N times in
				94	the output. Section markers look like this:
				95	<code>{{#FOO}}...{{/FOO}}</code></li>
				96
				97	<li> <b>Template-include</b> markers, which designate other
				98	templates to be expanded and inserted at the location where the
				99	marker appears. These are treated much like sections -- one
				100	may think of them as sections whose content is specified in a
				101	different file instead of inline -- and just like sections, can
				102	be expanded zero, one or N times in the output, each with a
				103	different dictionary. Template-include markers look like this:
				104	<code>{{>FOO}}</code></li>
				105
				106	<li> <b>Comment</b> markers, which may annotate the template
				107	structure but drop completely out of the expanded
				108	output. Comment markers look like this:
				109	<code>{{! comment lives here -- cool, no?}}</code></li>
				110
				111	<li> <b>Set-delimiter</b> markers, which change the marker
				112	delimiters from <code>{{</code> and <code>}}</code> to custom
				113	strings. (The only requirement is that these strings not
				114	contain whitespace or the equals sign.) This is useful for
				115	languages like TeX, where double-braces may occur in the text
				116	and are awkward to use for markup. Set-delimiter markers look
				117	like this: <code>{{=< >=}} <! Now markers are
				118	delimited by braces > <=\| \|=> \|! And now markers are
				119	delimited by bars! \| </code></li>
				120
				121	<li> <b>Pragma</b> markers, which invoke additional built-in template
				122	features when processing the template. Pragma markers look like
				123	this: <code>{{%PRAGMA [name="value"...]}}</code>. Currently,
				124	AUTOESCAPE is the only pragma defined.</li>
				125	</ol>
				126
				127	<p>These marker types each have their own namespace. For readability,
				128	however, it is best to not overuse a single name.</p>
				129
				130
				131	<h3> Modifiers </h3>
				132
				133	<p>A variable and include-template can have one or more <A
				134	HREF="#template_modifier">modifiers</A> attached to them, like so:</p>
				135	<pre>
				136	{{MYVAR:mod1:mod2:mod3=value:mod4=value with spaces:mod5}}
				137	</pre>
				138
				139	<p>A modifier is a filter that's
				140	applied at template-expand time, that munges the value of the variable
				141	before it's output. See the <A
				142	HREF="#template_modifier"><code>TemplateModifier</code></A> class for
				143	more details.</p>
				144
				145	<p>When expanding a variable (or template-include) with a modifier,
				146	the modifiers are applied in order, left to right. For a
				147	template-include, first the entire sub-template is expanded, as a
				148	single string, and then the modifiers are applied to that string.</p>
				149
				150	<p>In general, using explicit modifiers does not turn off <A
				151	HREF="#auto_escape">auto-escaping</A> on a variable. The explicit
				152	modifier <code>:none</code> does suppress auto-escaping.</p>
				153
				154
				155	<h3> <A NAME="special_markers">Special Markers</A> </h3>
				156
				157	<p>Some marker names may have a special meaning in the template
				158	system. Right now, there's one such name.</p>
				159
				160	<h4><A NAME="separator">Separator Sections</A></h4>
				161
				162	<p>If you have a section named FOO, you can define inside
				163	of it a section named FOO_separator, and the template
				164	system will automatically expand that section every time
				165	<code>FOO</code> is expanded, <i>except for the last</i>. Thus, the
				166	contents of <code>FOO_separator</code> can be used to separate
				167	repeated values of a section.</p>
				168
				169	<p>Here's an example:</p>
				170	<pre>
				171	Here are the meeting attendees:
				172	{{#ATTENDEES}}
				173	{{NAME}}
				174	{{#ATTENDEES_separator}}, {{/ATTENDEES_separator}}
				175	{{/ATTENDEES}}
				176	.
				177	</pre>
				178
				179	<p>Here is a more convoluted example, to show the date:</p>
				180	<pre>
				181	{{#DATE}}{{DATE_COMPONENT}}{{#DATE_separator}}{{DATE_SEP}}{{/DATE_separator}}{{/DATE}}
				182	</pre>
				183
				184	<p>You'd set up a template dictionary to repeat <code>DATE</code>
				185	three times, with <code>DATE_COMPONENT</code> set to the month, day,
				186	and year (or day, month, and year, depending on your locale...), and
				187	<code>DATE_SEP</code> set to <code>/</code> or <code>-</code> or
				188	whatever date-separator is called for.</p>
				189
				190	<p><code>SEP_separator</code> is always evaluated with the current
				191	dictionary. Thus, in the date example, if you wanted a different
				192	separator each time, you could do so by setting <code>DATE_SEP</code>
				193	to a different value for each repetition of <code>DATE</code>.</p>
				194
				195	<p>While <code>SEP_separator</code> is automatically expanded by the
				196	template system, it is otherwise a perfectly normal section. You can
				197	even instantiate it yourself by calling
				198	<code>AddSectionDictionary("SEP_separator")</code>. In that case, the
				199	section will be expanded both via the automatic expansion as a
				200	separator, and as a normal section via the section dictionary you
				201	added. This is more confusing than helpful, and you should probably
				202	never do it.</p>
				203
				204	<p>There can be at most one "separator" sub-section per section. If
				205	there are more, only the last is automatically expanded.</p>
				206
				207
				208	<h3> <A NAME="strip">Specifying a template</A> </h3>
				209
				210	<p>In the template system -- in functions like
				211	<code>ExpandTemplate()</code> -- a template is specified by a pair:
				212	filename + strip-mode. The filename specifies the name of the
				213	template file on disk (but see below for string templates). The strip
				214	mode specifies how this file should be parsed as it's read from disk,
				215	in particular, how whitespace should be handled. It can take the
				216	following values:</p>
				217
				218	<ul>
				219	<li> <code>ctemplate::DO_NOT_STRIP</code>: do nothing. This expands
				220	the template file verbatim.
				221
				222	<li> <code>ctemplate::STRIP_BLANK_LINES</code>: remove all blank
				223	lines. This ignores any blank lines found in the template file
				224	when parsing it. When the template is html, this reduces the
				225	size of the output text without requiring a sacrifice of
				226	readability for the input file.
				227
				228	<li> <code>ctemplate::STRIP_WHITESPACE</code>: remove not only blank
				229	lines when parsing, but also whitespace at the beginning and
				230	end of each line. It also removes any linefeed (possibly
				231	following whitespace) that follows a closing <code>}}</code> of
				232	any kind of template marker <i>except</i> a template variable.
				233	(This means a linefeed may be removed anywhere by simply
				234	placing a comment marker as the last element on the line.)
				235	When the template is html, this reduces the size of the output
				236	html without changing the way it renders (except in a few
				237	special cases.) When using this flag, the built-in template
				238	variables <code>BI_NEWLINE</code> and <code>BI_SPACE</code> can
				239	be useful to force a space or newline in a particular
				240	situation.
				241	</ul>
				242
				243	<p>The filename is where the template file lives on disk. It can be
				244	either an absolute filename, or relative to a directory in the
				245	<A HREF="#search_path">template search path</A>.</p>
				246
				247	<p>In addition to reading a template from disk, it is possible to read
				248	a template from a string, using <code>StringToTemplateCache()</code>.
				249	The first argument of <code>StringToTemplateCache()</code> is a "key"
				250	to use to refer to this string-based template. This key takes the
				251	place of the filename, for any routine that asks for a
				252	filename + strip.</p>
				253
				254
				255	<h3> <A NAME="expand_template">ExpandTemplate()</A> </h3>
				256
				257	<p>This is the main workhorse function of the template system. It
				258	takes the filename of a template, a <A
				259	HREF="#template_dictionary">template dictionary</A>, and a string to
				260	emit to, and emits an "expanded" version of the template using the
				261	given template dictionary to fill in the template markers.</p>
				262
				263	<p>If the template specified by the given filename is already found in
				264	an internal cache, the cached version of the template is used,
				265	otherwise the template is loaded from disk, parsed, and stored in the
				266	cache before expansion is performed. As always, the "filename" can
				267	also be a <A HREF="#strip">key</A> to a string-based template,
				268	inserted directly into the cache via
				269	<code>StringToTemplateCache()</code>.</p>
				270
				271	<p>There is an overloaded version of <code>Expand()</code> that takes
				272	an <A HREF="#expand_emitter"><code>ExpandEmitter</code></A> rather
				273	than a string, as the source to expand the template into.</p>
				274
				275	<p>This function returns true if the template was successfully
				276	expanded into the output parameter. It returns false if expansion
				277	failed or was only partially successful. It might fail because the
				278	template file cannot be found on disk, or because the template has
				279	syntax errors and cannot be parsed, or because the template
				280	sub-includes another template, and that sub-template has errors. To
				281	minimize the risk of errors at expand-time, you can call
				282	<code>LoadTemplate()</code> (below) first to load and parse the
				283	template into the cache. This will catch all errors except for errors
				284	involving sub-templates.</p>
				285
				286	<p>In the case of partial failures -- typically, failures resulting in
				287	an error in a sub-inclued template -- there may be partial data
				288	emitted to the output before the error was detected. If
				289	<code>ExpandTemplate()</code> returns false, you should be careful to
				290	check for and remove this partial data, if desired.</p>
				291
				292
				293	<h3> <A NAME="expand_with_data">ExpandWithData()</A> </h3>
				294
				295	<p><code>ExpandWithData()</code> is like
				296	<code>ExpandTemplate()</code>, with the addition that it allows you to
				297	pass in <A HREF="#per_expand_data">per-expand data</A>. It's called
				298	like this:</p>
				299	<pre>
				300	ctemplate::TemplateDictionary dict(...);
				301	ctemplate::PerExpandData per_expand_data;
				302	string output;
				303	ctemplate::ExpandWithData(filename, strip_mode, &output, &dict,
				304	&per_expand_data);
				305	</pre>
				306
				307	<p>Per-expand data is applied to all templates that are seen while
				308	expanding: not only the template you called <code>Expand()</code> on,
				309	but also sub-templates that are brought in via template-includes
				310	(<code>{{>INCLUDE}}</code>). See the description of the <A
				311	HREF="#per_expand_data"><code>PerExpandData</code></A> class for more
				312	details about how expansion can be modified by per-expand data.</p>
				313
				314	<p>The return value has the same meaning as for
				315	<code>ExpandTemplate()</code> In fact, if you pass in
				316	<code>NULL</code> as the <code>per_expand_data</code> argument, this
				317	function is exactly equivalent to <code>ExpandTemplate()</code>.</p>
				318
				319
				320	<h3> <A NAME="load_template">LoadTemplate()</A> </h3>
				321
				322	<p>This function takes a filename and a strip-mode, and loads the file
				323	into the default template cache. Future calls to
				324	<code>ExpandTemplate()</code> or <code>ExpandWithData()</code> will
				325	get the parsed template from the cache, without needing to go to
				326	disk.</p>
				327
				328	<p>This function returns true if the template was successfully read
				329	from disk, parsed, and inserted into the cache. It will also return
				330	true if the template is already in the cache (even if the file has
				331	changed on disk since the template was inserted into the cache). It
				332	will return false if the file cannot be found on disk, or cannot be
				333	successfully parsed. (Note that <code>LoadTemplate()</code> cannot
				334	detect errors in sub-included templates, since the identity of
				335	sub-included templates is specified in a
				336	<code>TemplateDictionary</code>, not in the template itself.)</p>
				337
				338
				339	<h3> <A NAME="string_to_template_cache">StringToTemplateCache()</A> </h3>
				340
				341	<p>In addition to reading a template file from disk, it is also
				342	possible to read a template file from a string, using
				343	<code>StringToTemplateCache()</code>. It takes the content
				344	as a string. It also takes in a key and a <A HREF="#strip">strip</A>
				345	mode. The given key and strip mode can be used as the filename/strip
				346	pair in calls to <code>ExpandTemplate()</code> and similar
				347	functions. The key can also be used as the "filename" in calls to
				348	<code>ctemplate::TemplateDictionary::SetFilename()</code>, allowing
				349	this template to be included inside other templates.</p>
				350
				351	<p><code>StringToTemplateCache()</code> returns true if the string is
				352	successfully inserted into the cache. It returns false otherwise,
				353	probably because there is already a string or filename in the cache
				354	with the same key.</p>
				355
				356
				357	<h3> default_template_cache() and mutable_default_template_cache() </h3>
				358
				359	<p>All the above routines -- <code>ExpandTemplate()</code>,
				360	<code>LoadTemplate()</code>, and the like -- read and write parsed
				361	templates to the default template cache. This is just a static
				362	instance of the <A
				363	HREF="#template_cache"><code>TemplateCache</code></A> class. It can
				364	be accessed via these two functions:
				365	<code>default_template_cache()</code> and, if you need a non-const
				366	version of the cache, <code>mutable_default_template_cache()</code>.
				367	These can be useful if you need the advanced features of template
				368	caches, such as <code>ReloadAllIfChanged()</code> or
				369	<code>ClearCache()</code>.</p>
				370
				371
				372	<h2> <A NAME="template_dictionary">The <code>TemplateDictionary</code>
				373	Class</A> </h2>
				374
				375	<p>The class <code>TemplateDictionary</code> is used for all template
				376	dictionary operations. In general, an application will need to call a
				377	<code>TemplateDictionary</code> method for every marker in the
				378	associated template (the major exception: markers that evaluate to the
				379	empty string can be ignored).</p>
				380
				381	<p>The appropriate function to call for a given template marker
				382	depends on its type.</p>
				383
				384
				385	<h3> Data Dictionaries </h3>
				386
				387	<p>A data dictionary is a map from keys to values. The keys are
				388	always strings, corresponding to the name of the associated template
				389	marker, so a section <code>{{#FOO}}</code> in the template text is
				390	matched to the key <code>FOO</code> in the dictionary, if it exists.
				391	Note the case must match as well.</p>
				392
				393	<p>The value associated with a key differs according to key type. The
				394	value associated with a <i>variable</i> is simple: it's the value for
				395	that variable. Both keys and values can be any 8-bit
				396	character-string, and may include internal NULs (<code>\0</code>).</p>
				397
				398	<p>The value associated with a <i>section</i> is a list of data
				399	dictionaries. At template-expansion time, the section is expanded
				400	once for each dictionary in the list. The first time, all
				401	variables/etc. in the section will be evaluated taking into account
				402	the first dictionary. The second time, all variables/etc. will be
				403	evaluated taking into account the second dictionary. (See <A
				404	HREF="#inheritance">below</A> for a definition of "taking into
				405	account.")</p>
				406
				407	<p>The value associated with a <i>template-include</i> is also a list
				408	of data dictionaries. Each data dictionary in this list must also
				409	have one other, mandatory associated piece of associated information:
				410	the filename of the template to include. At expand-time, that
				411	filename is passed as-is to <code>ctemplate::ExpandTemplate()</code>
				412	(or, more exactly, the equivalent of <code>ExpandTemplate()</code> in
				413	the same <code>TemplateCache</code> that the parent template comes
				414	from).</p>
				415
				416
				417	<h3> <A NAME="inheritance">Details on Dictionary Lookup</A> </h3>
				418
				419	<p>The dictionary structure is a tree: there's a 'main' dictionary,
				420	and then a list of sub-dictionaries for each section or
				421	include-template. When looking up a marker -- be it a variable,
				422	section, or include-template marker -- the system looks in the
				423	currently applicable dictionary. If it's found there, that value is
				424	used. If not, and the parent dictionary is not an include-template,
				425	it continues the look in the parent dictionary, and possibly the
				426	grandparent, etc. That is, lookup has <i>static scoping</i>: you look
				427	in your dictionary and any parent dictionary that is associated with
				428	the same template-file. As soon as continuing the lookup would
				429	require you to jump to a new template-file (which is what
				430	include-template would do), we stop the lookup.</p>
				431
				432	<p>If lookup fails in all dictionaries, the template system does a
				433	final lookup in the <b>global variable dictionary</b>.</p>
				434
				435	<p>The system initializes the global dictionary with a few useful
				436	values for your convenience (the user can add more). All system
				437	variables are prefixed with <code>BI</code>, to emphasize they are
				438	"built in" variables.</p>
				439	<ul>
				440	<li> <code>BI_SPACE</code>, which has the value
				441	<code><space></code>. It is used to force a space
				442	at the beginning or end of a line in the template,
				443	where it would normally be suppressed. (See below.) </li>
				444
				445	<li><code>BI_NEWLINE</code>, which has the value
				446	<code><newline></code> It is used to force a
				447	newline at the end of a line, where it would normally
				448	be suppressed. (See below.) </li>
				449	</ul>
				450
				451	<p>Variable inheritance happens at expand time, not at
				452	dictionary-create time. So if you create a section dictionary, and
				453	then afterwards set a variable in its parent dictionary (or in the
				454	global dictionary), the section <i>will</i> inherit that variable
				455	value, if it doesn't define the value itself.</p>
				456
				457
				458	<h3> SetValue() and variants </h3>
				459
				460	<p>SetValue() is used to set the value for a variable
				461	marker in a dictionary. It takes a string as input -- nominally a <A
				462	HREF="#template_string"><code>TemplateString</code></A>, though a C++
				463	string or C char* will be auto-converted -- for the variable name and
				464	its value. The name is the same string as is used for the variable's
				465	template-marker inside the template this dictionary will be expanded
				466	with: if the template reads <code>Hello {{NAME}}</code> then the
				467	first argument to <code>SetValue()</code> must be <code>NAME</code>.
				468	Case matters.</p>
				469
				470	<p><code>SetIntValue()</code> takes an integer as the value, rather
				471	than a string. On all platforms, the integer may be up to 64
				472	bits.</p>
				473
				474	<p><code>SetFormattedValue()</code> is a convenience routine.
				475	<code>SetFormattedValue(key, arg1, arg2, ...)</code> is logically
				476	equivalent to</p>
				477	<pre>
				478	char buffer[A_BIG_ENOUGH_NUMBER];
				479	sprintf(buffer, arg1, arg2, ...);
				480	SetValue(key, buffer);
				481	</pre>
				482	<p>without having to worry about the size of <code>buffer</code>, or
				483	about stack overflow.</p>
				484
				485	<p><code>SetValueWithoutCopy()</code> is provided to give an extra bit
				486	of efficiency when needed. <code>SetValue()</code> will copy the key
				487	and value into an internal data structure used by the
				488	<code>TemplateDictionary</code>; this avoids dangling pointers if the
				489	arguments to <code>SetValue()</code> are temporaries, or otherwise
				490	have shorter lifetime than the <code>TemplateDictionary</code>. But
				491	if you know that both the key and value strings have lifetime longer
				492	than the <code>TemplateDictionary</code> -- perhaps because they are
				493	global (static duration) <code>char*</code>'s -- you can call
				494	<code>SetValueWIthoutCopy()</code> to avoid the copy. This yields a
				495	small time savings at the cost of significant code fragility, so
				496	should only be used when absolutely necessary.</p>
				497
				498
				499	<h3> SetGlobalValue() and SetTemplateGlobalValue() </h3>
				500
				501	<p><code>SetGlobalValue()</code> is like <code>SetValue()</code> but
				502	works on the global dictionary. Since the global dictionary is shared
				503	across all template dictionaries, this is a static method on
				504	<code>TemplateDictionary</code>. It is thread-safe. It is also
				505	relatively slow.</p>
				506
				507	<p><code>SetTemplateGlobalValue()</code> is like
				508	<code>SetValue()</code>, but the values are preserved across
				509	template-includes.</p>
				510
				511	<p>This example shows all three forms:</p>
				512	<pre>
				513	A.tpl:
				514	{{NAME}} has won {{>PRIZE}}. It is worth {{AMOUNT}}.
				515	B.tpl:
				516	{{AMOUNT}} dollars! And it's all yours, {{NAME}}
				517	C.tpl:
				518	To: {{NAME}}. Amount: {{AMOUNT}}.
				519	code:
				520	ctemplate::TemplateDictionary dict("set_value_demo");
				521	ctemplate::TemplateDictionary* subdict = dict.AddIncludeDictionary("PRIZE");
				522	subdict->SetFilename("B.tpl");
				523	dict->SetValue("NAME", "Jane McJane");
				524	dict->SetTemplateGlobalValue("AMOUNT", "One Million");
				525	ctemplate::TemplateDictionary::SetGlobalValue("NAME", "John Doe");
				526	ctemplate::TemplateDictionary dict_c("set_value_demo, part 2");
				527
				528	ctemplate::ExpandTemplate("A.tpl", ..., &dict);
				529	ctemplate::ExpandTemplate("C.tpl", ..., &dict_c);
				530	</pre>
				531
				532	<p>The first expand yields this:</p>
				533	<pre>
				534	Jane McJane has won One Million dollars! And it's all yours, John Doe. It is worth One Million.
				535	</pre>
				536
				537	<p>The second expand yields this:</p>
				538	<pre>
				539	To: John Doe. Amount: .
				540	</pre>
				541
				542	<p><code>NAME</code> was set via <code>SetValue()</code>, so its
				543	value was not propagated across the include-dict boundary; instead,
				544	the subdict (B.tpl) got its value for <code>NAME</code> from the
				545	global dictionary. <code>AMOUNT</code>, on the other hand, was set
				546	via <code>SetTemplateGlobalValue()</code>, so its value was propagated
				547	across the boundary, and the subdict saw it. However, the totally
				548	unrelated template, C.tpl, did not see either value, and only sees the
				549	values in the global dictionary. (Of course, had we filled
				550	<code>dict_c</code> with some values, C.tpl would have had access to
				551	those.)</p>
				552
				553
				554	<h3> AddSectionDictionary(), ShowSection(),
				555	and SetValueAndShowSection() </h3>
				556
				557	<p><code>AddSectionDictionary(section_name)</code> returns a
				558	sub-dictionary associated with the given section_name (for instance,
				559	<code>dict.AddSectionDictionary("MYSECT")</code> for a template like
				560	<code>{{#MYSECT}}...{{/MYSECT}}</code>). If called multiple times, it
				561	will return a new dictionary each time. During <code>Expand()</code>,
				562	the section will be expanded once for each time
				563	<code>AddSectionDictionary()</code> was called; that is, the text
				564	inside the section delimiters will be repeated once for each
				565	<code>AddSectionDictionary()</code> call, and within a single
				566	repetition, the dictionary returned by
				567	<code>AddSectionDictionary()</code> will be used to populate the text
				568	inside the section delimiters. (With the current dictionary as that
				569	dictionary's parent, for inheritance purposes.)</p>
				570
				571	<p>This suggests that if <code>AddSectionDictionary()</code> is never
				572	called on a section, the text inside the section will be omitted
				573	entirely by <code>Expand()</code>.</p>
				574
				575	<p><code>ShowSection()</code> is a convenience method used to show the
				576	text inside the section exactly once. It is equivalent to calling
				577	<code>AddSectionDictionary()</code> once, and ignoring the returned
				578	sub-dictionary. All variables in the section will depend on
				579	dictionary inheritence to get their values.</p>
				580
				581	<p><code>SetValueAndShowSection()</code> is another convenience
				582	method,, used to show a section if and only if a related variable is
				583	set to a non-empty value. <code>SetValueAndShowSection(name, value,
				584	section_name)</code> is equivalent to this: if value is empty do
				585	nothing, otherwise add a single dictionary to
				586	<code>section_name</code> and call <code>section_dict->AddValue(name,
				587	value)</code>.</p>
				588
				589	<p>Example:</p>
				590	<pre>
				591	ctemplate::TemplateDictionary* dict = new ctemplate::TemplateDictionary("section example");
				592	const char* username = GetUsername(); // returns "" for no user
				593	if (username[0] != '\0') {
				594	ctemplate::TemplateDictionary* sub_dict = dict->AddSectionDictionary("CHANGE_USER");
				595	sub_dict->SetValue("USERNAME", username);
				596	} else {
				597	// don't need to do anything; we want a hidden section, which is the default
				598	}
				599
				600	// Instead of the above 'if' statement, we could have done this:
				601	if (username[0] != '\0') {
				602	dict->ShowSection("CHANGE_USER"); // adds a single, empty dictionary
				603	dict->SetValue("USERNAME", username); // take advantage of inheritance
				604	} else {
				605	// don't need to do anything; we want a hidden section, which is the default
				606	}
				607
				608	// Or we could have done this:
				609	dict->SetValueAndShowSection("USERNAME", username, "CHANGE_USER");
				610
				611	// Moving on...
				612	GetPrevSearches(prev_searches, &num_prev_searches);
				613	if (num_prev_searches > 0) {
				614	for (int i = 0; i < num_prev_searches; ++i) {
				615	TemplateDictionary* sub_dict = dict->AddSectionDictionary("PREV_SEARCHES");
				616	sub_dict->SetValue("PREV_SEARCH", prev_searches[i]);
				617	}
				618	}
				619	</pre>
				620
				621
				622	<h3> AddIncludeDictionary() and SetFilename() </h3>
				623
				624	<p><code>AddIncludeDictionary(section_name)</code> returns a
				625	sub-dictionary associated with the given include_name (for instance,
				626	<code>dict.AddIncludeDictionary("MYTPL")</code> for a template like
				627	<code>{{>MYTPL}}</code>). If called multiple times, it
				628	will return a new dictionary each time. It is the responsibility of
				629	the caller to then call <code>SetFilename()</code> on the
				630	sub-dictionary returned.</p>
				631
				632	<p>During <code>Expand()</code>,
				633	each dictionary returned by <code>AddIncludeDictionary</code> will be
				634	examined in turn. For each dictionary for which
				635	<code>SetFilename()</code> is called, that filename will be read as a
				636	template (via <code>LoadTemplate()</code>, with the same
				637	"strip" value as the current template), and expanded using the
				638	dictionary. (Note that the dictionary will not inherit
				639	<code>SetValue()</code> values from the parent dictionary, though it
				640	will inherit <code>SetTemplateGlobalValue()</code> values.) This
				641	expanded template will then be emitted to the output.</p>
				642
				643	<p>Note that if <code>AddIncludeDictionary()</code> is never called,
				644	the template-include will be a no-op during <code>Expand()</code>.
				645	Likewise, if it is called but <code>SetFilename()</code> is never
				646	called on the resulting sub-dictionary, the template-include will be a
				647	no-op. On the other hand, if it is called multiple times, multiple
				648	templates -- possibly all from the same file, possibly not -- will be
				649	inserted at the point of the template-include.</p>
				650
				651	<p>If a user has called <code>StringToTemplateCache(key, ...)</code>,
				652	then the user can call <code>SetFilename(key)</code> to include the
				653	contents of the string as the sub-template.</p>
				654
				655
				656	<h3> Dump() and DumpToString() </h3>
				657
				658	<p>These routines dump the contents of a dictionary and its
				659	sub-dictionaries. <code>Dump()</code> dumps to stdout,
				660	<code>DumpToString()</code> to a string. They are intended for
				661	debugging.</p>
				662
				663
				664	<h2> <A NAME="template_cache">The <code>TemplateCache</code> Class</A> </h2>
				665
				666	<p>This class holds a collection of templates. It can be used to give
				667	you a coherent view of the template system: you load all the templates
				668	you are going to use into the cache, and then reload them from disk in
				669	one atomic operation. You can have multiple
				670	<code>TemplateCache</code> objects in your executable, perhaps one for
				671	each service you provide, or perhaps one per thread (so as to avoid
				672	thread contention when loading templates).</p>
				673
				674	<p>One intended use of the template cache is to make it safe to reload
				675	template files while serving user requests from a webserver. The idea
				676	is that every user request, as it's created, is associated with the
				677	current template cache. When you wish to reload, you
				678	<code>Clone()</code> the current cache, and then reload inside the
				679	cloned copy. New requests will get the cloned cache, while old
				680	requests will continue to render using the old cache.
				681	<code>TemplateCache</code> is written to make this use-case efficient:
				682	templates are shared between caches when appropriate, with
				683	reference-counting to keep memory management easy.</p>
				684
				685
				686	<h3> The default template cache </h3>
				687
				688	<p>The template system creates a default template cache, which is
				689	available via the functions <code>default_template_cache()</code> and
				690	<code>mutable_default_template_cache()</code>.</p>
				691
				692	<p>For simple uses of the template system, using the default cache,
				693	via <code>ExpandTemplate()</code> and the like, may be perfectly
				694	adequate. If you want more sophisticated features, such as the
				695	ability to have different versions of the same template file active at
				696	one time, or to change the template root-directory, you will have to
				697	use an explicit <code>TemplateCache</code>.</p>
				698
				699
				700	<h3> LoadTemplate() and StringToTemplateCache() </h3>
				701
				702	<p>These two routines are how you explicitly insert data into the
				703	cache. <code>LoadTemplate()</code> reads a template from disk, while
				704	<code>StringToTemplateCache()</code> takes the data from a
				705	user-specified string. These work exactly the same as the global <A
				706	HREF="#load_template"><code>LoadTemplate()</code></A> and <A
				707	HREF="#string_to_template_cache"><code>StringToTemplateCache()</code></A>,
				708	except they insert into the given <code>TemplateCache</code>, rather
				709	than the global cache.</p>
				710
				711	<p><code>LoadTemplate()</code> is not strictly necessary: if the cache
				712	cannot find a template it needs at <code>Expand*()</code> time, it will
				713	automatically try to fetch it from disk. It is intended mostly for
				714	use with <A HREF="#freeze"><code>Freeze()</code></A>, which disables
				715	this auto-fetch behavior.</p>
				716
				717	<p>Both of these routines take a <A HREF="#strip">strip</A> mode
				718	specifying how the template system should treat whitespace while
				719	parsing.</p>
				720
				721	<p>If the template-cache is <A HREF="#freeze">frozen</A>,
				722	<code>LoadTemplate()</code> will only return true if the template is
				723	already stored in the cache, and will return false in every other
				724	case. For a frozen cache, <code>StringToTemplateCache()</code> will
				725	always return false.</p>
				726
				727
				728	<h3> ExpandWithData() and ExpandFrozen() </h3>
				729
				730	<p>These routines takes a string that represents either a template
				731	filename (for disk-based templates), or a key used in
				732	<code>StringToTemplateCache()</code> (for string-based templates), a <A
				733	HREF="#strip">strip</A> mode saying how to parse the template's
				734	whitespace, and <A HREF="#per_expand_data">per-expand data</A> (which
				735	can be NULL). Overloads are provided to output the expanded template
				736	to either a string or to an arbitrary <A
				737	HREF="#expand_emitter"><code>ExpandEmitter</code></A>.</p>
				738
				739	<p>Expand uses the filename + strip pair to fetch the template from
				740	the cache, if it's there. If not, <code>ExpandWithData()</code> will
				741	fetch the template from disk and insert it into the cache.
				742	<code>ExpandFrozen()</code>, on the other hand, will just fail to
				743	expand, and return false. This is the only difference in behavior
				744	between the two routines. To reinforce this behavior,
				745	<code>ExpandFrozen()</code> will return false immediately if <A
				746	HREF="#freeze"><code>Freeze()</code></A> has not been called on the
				747	cache.
				748
				749	<p>While expanding, the template system may come across template
				750	sub-includes (<code>{{>SUB_TEMPLATE}}</code>). It will attempt to
				751	fetch these templates from the cache as well; failing that, it will
				752	try to load the template from disk (for <code>ExpandWithData()</code>)
				753	or else fail the expand and return false (for
				754	<code>ExpandFrozen()</code>).</p>
				755
				756	<p>Because <code>ExpandFrozen()</code> never updates the cache, it is
				757	a const method, unlike <code>ExpandWithData()</code>.</p>
				758
				759	<p>Note that <code>TemplateCache</code> does not provide the
				760	convenience <code>ExpandTemplate()</code> routine, as the analogue of
				761	the global <A
				762	HREF="#expand_template"><code>ExpandTemplate()</code></A>. If you are
				763	not interested in the per-expand data, just call
				764	<code>ExpandWithData()</code> with the per-expand data set to NULL.</p>
				765
				766
				767	<h3> ReloadAllIfChanged() </h3>
				768
				769	<p>For every file-based template in the cache (this method ignores
				770	string-based templates), <code>ReloadAllIfChanged()</code> checks the
				771	filesystem to see if the file has changed since it was loaded into the
				772	cache. If so, the cache loads a new version of the file into the
				773	cache. Note that at this point both the old and new versions of the
				774	file exist in the cache! Only the new version is accessible via new
				775	calls to <code>Expand()</code>, but any expansions currently in flight
				776	during the <code>ReloadAllIfChanged()</code> call will continue to use
				777	the old version.</p>
				778
				779	<p>NOTE: <code>ReloadAllIfChanged()</code> never modifies existing
				780	items in the cache in any way. It only loads new entries into the
				781	cache.</p>
				782
				783	<p><code>ReloadAllIfChanged()</code> comes in two flavors, controlled
				784	by the passed-in enum. In "immediate" mode, it synchronously iterates
				785	through the cache and reloads all files that need it. In "lazy" mode,
				786	it waits to reload a given template file until the next time it's
				787	actually used (in a call to <code>Expand*()</code>). "Immediate" mode
				788	is safer in the case where templates depend on each other and the
				789	files change a lot, since all files are reloaded at about the same
				790	time. "Lazy" mode avoids the latency spike of "immediate" mode, and
				791	is preferable in the (common) case that files on disk change only
				792	rarely.</p>
				793
				794
				795	<h3> <A NAME="search_path"> SetTemplateRootDirectory(),
				796	AddAlternateTemplateRootDirectory(), and
				797	template_root_directory() </A> </h3>
				798
				799	<p>By default, filenames passed in to <code>Expand*()</code> are taken
				800	to be relative to the current working directory. These functions
				801	change that behavior. <code>SetTemplateRootDirectory()</code> resets
				802	the search path to be the single path passed in to this function.
				803	Every time <code>AddAlternateTemplateRootDirectory()</code> is called,
				804	it adds another directory to the end of the search path. The template
				805	system will follow the search path, in order, when looking for a
				806	filename.</p>
				807
				808	<p>Note that the template search path is only meaningful when the
				809	filename passed to <code>Expand*()</code> (or specified for a
				810	sub-include) is a relative filename. If the filename is an absolute
				811	filename, starting with <code>/</code>, the search path is
				812	ignored.</p>
				813
				814	<p><code>template_root_directory()</code> returns the first entry in
				815	the search path. There is currently no way to access other entries in
				816	the search path.</p>
				817
				818
				819	<h3> FindTemplateFilename() </h3>
				820
				821	<p><code>FindTemplateFilename()</code> does the work of finding a
				822	template file in the filesystem, using the current template search
				823	path. It takes a relative pathname as input, and returns an absolute
				824	pathname as output, indicating where the template file lives on the
				825	filesystem. If the template file is not found, this method returns
				826	the empty string.</p>
				827
				828
				829	<h3> <A NAME="freeze">Freeze()</A> </h3>
				830
				831	<p><code>Freeze()</code> marks the template cache as immutable. After
				832	this method is called, the cache can no longer be modified by loading
				833	new templates or reloading existing templates. During expansion only
				834	cached included templates will be used; they won't be loaded
				835	on-demand.</p>
				836
				837	<p>Before calling <code>Freeze()</code>, you should make sure your
				838	cache has all the templates it might need, using
				839	<code>LoadTemplate()</code> and <code>StringToTemplateCache()</code>.
				840	Otherwise, <code>ExpandWithData()</code> and
				841	<code>ExpandFrozen()</code> may fail.</p>
				842
				843	<p>Once the cache is frozen, calls to
				844	<code>SetTemplateRootDirectory()</code>,
				845	<code>AddAlternateTemplateRootDirectory()</code>,
				846	<code>Delete()</code>, and <code>ReloadAllIfChanged()</code> will
				847	fail.</p>
				848
				849	<p>After the cache is frozen, the <code>TemplateCache</code> object is
				850	effectively const.</p>
				851
				852
				853	<h3> Delete() </h3>
				854
				855	<p>This method deletes an entry from the cache. If the entry is in
				856	the cache multiple times (each with a different "strip" mode), this
				857	method deletes all of them.</p>
				858
				859
				860	<h3> ClearCache() </h3>
				861
				862	<p>This method deletes all entries from the cache. It can be called
				863	even on a frozen cache.</p>
				864
				865	<p>Note: this method is not typically necessary unless you are testing
				866	for memory leaks. It is intended to be called just before exiting the
				867	program, and after all template expansions are completed. Using it in
				868	that way may prevent unnecessary reporting by the leak checker.</p>
				869
				870
				871	<h3> Clone() </h3>
				872
				873	<p><code>Clone()</code> makes a shallow copy of the given
				874	<code>TemplateCache</code> object, and returns the copy. The new copy
				875	and the old share the same template objects; since it's a shallow
				876	copy, they actually share pointers to the exact same object. (Since
				877	the template cache never changes a template object once it's loaded
				878	into the cache, sharing the pointer isn't a risk.)</p>
				879
				880	<p>The intended use of <code>Clone()</code>, as described above, is to
				881	allow fine control over "epochal" changes in templates. One
				882	<code>TemplateCache</code> can hold all versions of the template files
				883	before the big update; after the update is done, you can clone the old
				884	cache and then call <code>ReloadAllIfChanged()</code> on the clone.
				885	This is a low-cost operation, since the two copies share most
				886	resources. Smart pointers take care of most memory management
				887	issues.</p>
				888
				889	<p>The caller is responsible for calling <code>delete</code> on the
				890	returned <code>TemplateCache</code> object.</p>
				891
				892
				893
				894	<h2> <A NAME="template_namelist">The <code>TemplateNamelist</code> Class</A> </h2>
				895
				896	<p>This class provides information about <A
				897	HREF="guide.html#register">registered</A> templates. Or more
				898	precisely, all templates corresponding to registered filenames.</p>
				899
				900	<p>All methods in this class are static.</p>
				901
				902
				903	<h3> RegisterTemplate() and
				904	RegisterTemplateFilename() </h3>
				905
				906	<p><code>TemplateNamelist::RegisterTemplate()</code> takes a filename
				907	and adds it to the static namelist used by
				908	<code>TemplateNamelist</code>. All other methods of
				909	<code>TemplateNamelist</code> work only on registered filenames.</p>
				910
				911	<p>It's fairly rare to call this method directly. Instead, the more
				912	common use is to use the macro <code>RegisterTemplateFilename</code>
				913	somewhere in the global scope, like so:</p>
				914	<pre>
				915	RegisterTemplateFilename(EXAMPLE_FN, "example.tpl");
				916	</pre>
				917
				918	<p>The reason to prefer the macro is it defines a global variable that
				919	you can use instead of the hard-coded template name. This helps catch
				920	typos. The <code>RegisterTemplateFilename()</code> example is
				921	functionally equivalent to:</p>
				922	<pre>
				923	#define EXAMPLE_FN "example.tpl"
				924	</pre>
				925
				926	<p>It can be used like this:</p>
				927	<pre>
				928	ctemplate::ExpandTemplate(EXAMPLE_FN, ctemplate::DO_NOT_STRIP, ...);
				929	</pre>
				930
				931
				932	<h3> GetMissingList() </h3>
				933
				934	<p><code>TemplateNamelist::GetMissingList()</code> returns a list of
				935	all registered templates (or rather, all filenames) where the file
				936	could not be found on disk.</p>
				937
				938
				939	<h3> AllDoExist() </h3>
				940
				941	<p>Returns true if and only if the missing-list is empty.</p>
				942
				943
				944	<h3> GetBadSyntax() </h3>
				945
				946	<p>Returns a list of all registered templates where the template
				947	contains a syntax error, and thus cannot be used.</p>
				948
				949
				950	<h3> IsAllSyntaxOkay() </h3>
				951
				952	<p>True if and only if the bad-syntax list is empty.</p>
				953
				954
				955	<h3> GetLastmodTime() </h3>
				956
				957	<p>Returns the latest last-modified time for any registered
				958	template-file.</p>
				959
				960
				961	<h2> <A NAME="template_modifier">The TemplateModifier Class</A>
				962	and Associated Functions</h2>
				963
				964	<p>A modifier is a filter that's applied at template-expand time, that
				965	munges the value of the variable before it's output. For instance,
				966	<code><html><body>{{NAME:html_escape}}</body></html></code>
				967	asks the template system to apply the built-in
				968	<code>html_escape</code> modifier when expanding
				969	<code>{{NAME}}</code>. If you set <code>NAME</code> in your
				970	dictionary to be <code>Jim & Bob</code>, what will actually be
				971	emitted in the template is <code>Jim &amp; Bob</code>.</p>
				972
				973	<p>You can chain modifiers together. This template first html-escapes
				974	<code>NAME</code>, and then javascript-escapes that result:</p>
				975	<pre>
				976	<html><body>{{NAME:html_escape:javascript_escape}}</body></html>
				977	</pre>
				978
				979	<p>Modifiers typically have a long, descriptive name and also a
				980	one-letter abbreviation. So this example is equivalent to the
				981	previous one:</p>
				982	<pre>
				983	<html><body>{{NAME:h:j}}</body></html>
				984	</pre>
				985
				986	<p>Some modifiers take an argument, specified after an equals
				987	sign:</p>
				988	<pre>
				989	<html><body>{{NAME:html_escape_with_arg=pre}}</body></html>
				990	</pre>
				991
				992
				993	<h3> Built-in Modifiers </h3>
				994
				995	<p>Here are the modifiers that are built in to the template system.
				996	They are all defined in template_modifiers.cc:</p>
				997
				998	<table border="1" cellpadding="3" summary="List of built-in modifiers">
				999	<tr><th>long name</th><th>short name</th><th>description</th></tr>
				1000
				1001	<tr><td><code>:cleanse_css</code></td><td><code>:c</code></td>
				1002	<td>Removes characters not safe for a CSS value. Safe characters
				1003	are alphanumeric, space, underscore, period, coma, exclamation
				1004	mark, pound, percent, and dash.</td>
				1005	</tr>
				1006
				1007	<tr><td><code>:html_escape</code></td><td><code>:h</code></td>
				1008	<td>html-escapes the variable before output
				1009	(eg <code>&</code> -> <code>&amp;</code>)</td>
				1010	</tr>
				1011
				1012	<tr><td><code>:html_escape_with_arg</code></td><td><code>:H</code></td>
				1013	<td>special purpose html escaping. See
				1014	<a href="#html_escape_args">:H Arguments</a>
				1015	below for details.</td>
				1016	</tr>
				1017
				1018	<tr><td><code>:img_src_url_escape_with_arg</code></td><td><code>:I</code></td>
				1019	<td>special purpose image url escaping. See
				1020	<a href="#url_escape_args">:I and :U Arguments</a>
				1021	below for details.</td>
				1022	</tr>
				1023
				1024	<tr><td><code>:javascript_escape</code></td><td><code>:j</code></td>
				1025	<td>javascript-escapes the variable before output (eg
				1026	<code>"</code> -> <code>\x27</code> and
				1027	<code>&</code> -> <code>\x26</code>)</td>
				1028	</tr>
				1029
				1030	<tr><td><code>:javascript_escape_with_arg</code></td><td><code>:J</code>
				1031	</td>
				1032	<td>special purpose javascript escaping. See
				1033	<a href="#javascript_escape_args">:J Arguments</a>
				1034	below for details.</td>
				1035	</tr>
				1036
				1037	<tr><td><code>:json_escape</code></td><td><code>:o</code></td>
				1038	<td>json-escapes a variable before output as a string in json;
				1039	HTML characters are escaped using Unicode escape sequences
				1040	(e.g <code>&</code> -> <code>\u0026</code>) to comply with
				1041	<a href="http://www.ietf.org/rfc/rfc4627.txt">RFC 4627</a>.
				1042	</td>
				1043	</tr>
				1044
				1045	<tr><td><code>:none</code></td><td></td>
				1046	<td>leaves the variable as is (used to disable <A
				1047	HREF="#auto_escape">auto-escaping</A>)</td>
				1048	</tr>
				1049
				1050	<tr><td><code>:pre_escape</code></td><td><code>:p</code></td>
				1051	<td>pre-escapes the variable before output (same as html_escape but
				1052	whitespace is preserved; useful for <pre>...</pre>)</td>
				1053	</tr>
				1054
				1055	<tr><td><code>:url_escape_with_arg</code></td><td><code>:U</code></td>
				1056	<td>special purpose url escaping. See
				1057	<a href="#url_escape_args">:I and :U Arguments</a>
				1058	below for details.</td>
				1059	</tr>
				1060
				1061	<tr><td><code>:url_query_escape</code></td><td><code>:u</code></td>
				1062	<td>performs URL escaping on the variable before output.
				1063	space is turned into +, and everything other than [0-9a-zA-Z.,_:*/~!()-], is
				1064	transformed into %-style escapes. Use this when you are building
				1065	URLs with variables as parameters:
				1066	<pre><a href="http://google.com/search?q={{QUERY:u}}">{{QUERY:h}}</a></pre>
				1067	</td>
				1068	</tr>
				1069
				1070	<tr><td><code>:xml_escape</code></td><td></td>
				1071	<td>xml-escapes the variable before output
				1072	(the five characters <code><>&"'</code> become
				1073	<code>&lt&gt;&amp;&quot;&#39;</code>)
				1074	suitable for content returned in raw XML. It is not intended
				1075	for escaping content within CDATA blocks.</td>
				1076	</tr>
				1077
				1078	</table>
				1079
				1080	<p>The <code>*_with_arg</code> modifiers require an argument to
				1081	specify the type of escaping to use. The following sections list
				1082	the supported arguments for each of these modifiers.
				1083
				1084	<h4 id="html_escape_args">:H Arguments</h4>
				1085	<p>Here are the values that are supported by
				1086	the <code>html_escape_with_arg</code> modifier:</p>
				1087	<table border="1" cellpadding="3" summary="Arguments for :H modifier">
				1088	<tr><th>value</th><th>description</th></tr>
				1089
				1090	<tr><td><code>=snippet</code></td>
				1091	<td>like <code>html_escape</code>, but allows HTML entities and
				1092	some tags to pass through unchanged. The allowed tags
				1093	are <code><br></code>, <code><wbr></code>, <code><b></code>,
				1094	and <code></b></code>.</td>
				1095	</tr>
				1096
				1097	<tr><td><code>=pre</code></td>
				1098	<td>same as <code>pre_escape</code></td>
				1099	</tr>
				1100
				1101	<tr><td><code>=url</code></td>
				1102	<td>same as <code>:U=html</code> below. For backwards compatibility.</td>
				1103	</tr>
				1104
				1105	<tr><td><code>=attribute</code></td>
				1106	<td>replaces characters not safe for an use in an unquoted
				1107	attribute with underscore. Safe characters are alphanumeric,
				1108	underscore, dash, period, and colon.</td>
				1109	</tr>
				1110
				1111	</table>
				1112
				1113	<h4 id="url_escape_args">:I and :U Arguments</h4>
				1114	<p>Here are the values that are supported by
				1115	the <code>img_src_url_escape_with_arg</code> and
				1116	<code>url_escape_with_arg</code> modifiers:</p>
				1117	<table border="1" cellpadding="3" summary="Arguments for :I and :U modifiers">
				1118	<tr><th>value</th><th>description</th></tr>
				1119
				1120	<tr><td><code>=html</code></td>
				1121	<td>Ensures that a variable contains a safe URL. Safe means that
				1122	it is either a http or https URL, or else it has no protocol
				1123	specified.
				1124	<ul>
				1125	<li>If the URL is safe, the modifier HTML-escapes the URL.
				1126	<li>Otherwise, the modifier replaces the unsafe URL with one of the
				1127	following values:
				1128	<ul>
				1129	<li><code>/images/cleardot.gif</code> (the <code>:I</code>
				1130	modifier)
				1131	<li><code>#</code> (the <code>:U</code> modifier)
				1132	</ul>
				1133	</li>
				1134	</ul>
				1135	<b>Do not use <code>:U</code> for image URLs.</b> Use <code>:I</code>
				1136	instead. <code>#</code> is not a safe replacement for an image URL.
				1137	<code><img src=#></code> can cause each browser to request the
				1138	entire page again.
				1139	</td>
				1140	</tr>
				1141
				1142	<tr><td><code>=javascript</code></td>
				1143	<td>Same as <code>=html</code>, but using javascript escaping
				1144	instead of html escaping.</td>
				1145	</tr>
				1146
				1147	<tr><td><code>=css</code></td>
				1148	<td>Same as <code>=html</code> but using CSS escaping instead
				1149	of html escaping so that the variable can be safely inserted
				1150	within a CSS <code>@import</code> statement or a CSS property.
				1151	The characters in [\r\n()'"<>*\] are transformed
				1152	into %-style escapes.</td>
				1153	</tr>
				1154
				1155	<tr><td><code>=query</code></td>
				1156	<td>(Supported for <code>:U</code> only) Same as
				1157	<code>url_query_escape</code>.</td>
				1158	</tr>
				1159
				1160	</table>
				1161
				1162	<h4 id="javascript_escape_args">:J Arguments</h4>
				1163	<p>Here are the values that are supported by
				1164	the <code>javascript_escape_with_arg</code> modifier:</p>
				1165	<table border="1" cellpadding="3" summary="Arguments for :J modifier">
				1166	<tr><th>value</th><th>description</th></tr>
				1167
				1168	<tr><td><code>=number</code></td>
				1169	<td>Ensures that the variable is a valid number or boolean
				1170	javascript literal. This includes booleans
				1171	<code>true</code> and <code>false</code>, decimal
				1172	numbers (e.g. <code>4.10</code> or <code>-5.01e+10</code>)
				1173	as well as hex numbers (e.g. <code>0x5FF</code>). This modifier
				1174	is intended to ensure the variable not enclosed in
				1175	quotes cannot contain javascript code that may execute. It does
				1176	not guarantee that the variable is syntactically well-formed.
				1177	If the variable is safe, it is returned
				1178	as-is, otherwise it is replaced with <code>null</code>.
				1179	In the future we may add more logic to support objects and
				1180	arrays.</td>
				1181	</tr>
				1182	</table>
				1183
				1184	<h3> Custom Modifiers </h3>
				1185
				1186	<p>In addition to the built-in modifiers, you can write your own
				1187	modifier. Custom modifiers must have a name starting with "x-", and
				1188	the name can contain alphanumeric characters plus dashes and
				1189	underscores. Custom modifiers can also accept values with any
				1190	character except for : and <code>}</code>. For example
				1191	this template could be a valid use of a custom modifier:</p>
				1192
				1193	<pre>
				1194	{{VAR:x-my_modifier:value1,value2,value3 has spaces,etc}}
				1195	</pre>
				1196
				1197	<p>See <code><template_modifiers.h></code> for details on how to
				1198	write a modifier and how to register it. In short, you write a
				1199	modifier by subclassing <code>ctemplate::TemplateModifier</code> and
				1200	overriding the <code>Modify</code> method, and you register it by
				1201	calling <code>ctemplate::AddModifier()</code> Here is an example of
				1202	the code for a custom modifier:</p>
				1203	<pre>
				1204	class StarEscape : public ctemplate::TemplateModifier {
				1205	void Modify(const char* in, size_t inlen,
				1206	const ctemplate::PerExpandData* per_expand_data,
				1207	ctemplate::ExpandEmitter* outbuf, const string& arg) const {
				1208	outbuf->Emit(string("") + string(in, inlen) + string(""));
				1209	}
				1210	};
				1211	</pre>
				1212
				1213
				1214	<h3> Subclassing TemplateModifier </h3>
				1215
				1216	<p>The minimum work to create a custom modifier is to subclass
				1217	<code>TemplateModifier</code> and override the <code>Modify()</code>
				1218	method. <code>Modify()</code> takes as input the value of the text to
				1219	be modified, as well as the <A HREF="#per_expand_data">per expand
				1220	data</A> associated with this <code>Expand()</code> call. The method
				1221	may use this input, plus any other data it may have, to generate
				1222	output, which it should write into the given
				1223	<code>ExpandEmitter</code>.</p>
				1224
				1225	<p>The subclass can also override <code>MightModify()</code>. This is
				1226	useful for modifiers that are typically a no-op (in which case the
				1227	modifier is just doing busy-work, copying its input to the output
				1228	<code>ExpandEmitter</code>). If <code>MightModify()</code> returns
				1229	false, the template system will avoid calling <code>Modify()</code> at
				1230	all on that variable, avoiding the busy-work copy.</p>
				1231
				1232
				1233	<h3> AddModifier() </h3>
				1234
				1235	<p> AddModifier() is used to register a custom modifier,
				1236	so the modifier can be used in templates. The name of the modifier
				1237	must start with <code>x-</code>. </p>
				1238
				1239
				1240	<h3> AddXssSafeModifier() </h3>
				1241
				1242	<p> <code>AddXssSafeModifier()</code> is used to register a custom
				1243	modifier that can work well with the <A
				1244	HREF="auto_escape.html">auto-escape system</A>. It is used when the
				1245	modifier produces output that is "safe" from cross-site scripting
				1246	attacks in all contexts in which it might be used. For instance, a
				1247	modifier that only emits numbers is xss-safe if it's only used in html
				1248	or javascript contexts.</p>
				1249
				1250
				1251	<h3> <A NAME="auto_escape">Auto-escaping and Manual Escaping</A> </h3>
				1252
				1253	<p>If the <A HREF="auto_escape.html">auto-escape pragma</A> is used
				1254	in a document, then all variables will be auto-escaped, even if
				1255	explicit modifiers are used on the variable. The rules are a little
				1256	complicated:</p>
				1257
				1258	<ul>
				1259	<li> If the explicit modifier is a built-in modifier, and that
				1260	modifier is "compatible" with the modifier that auto-escape
				1261	would perform ("compatible" means it safely escapes in at least
				1262	as many contexts as the auto-escape modifier), then only the
				1263	explicit modifier is applied, and no further auto-escaping is
				1264	done. </li>
				1265
				1266	<li> If the explicit modifier is a custom modifier registered using
				1267	AddXssSafeModifier(), no further auto-escaping is
				1268	done. </li>
				1269
				1270	<li> If the explicit modifier is the :none modifier, no
				1271	further auto-escaping is done. This is the mechanism for
				1272	manually turning off auto-escaping. </li>
				1273
				1274	<li> In all other situations, auto-escaping will be performed after
				1275	the explicit modifiers have all run. </li>
				1276	</ul>
				1277
				1278
				1279	<h2> <A NAME="per_expand_data">The <code>PerExpandData</code> Class</A> </h2>
				1280
				1281	<p><code>ExpandWithData()</code> and
				1282	<code>TemplateModifier::Modify()</code> both take a
				1283	<code>PerExpandData</code> object. Per-expand data is applied to all
				1284	templates that are seen while expanding: not only the template you
				1285	called <code>ExpandWithData()</code> on, but also sub-templates that
				1286	are brought in via template-includes (<code>{{>INCLUDE}}</code>).
				1287
				1288	<p>There are several types of per-expand data you can set, by calling
				1289	the appropriate method on a <code>PerExpandData</code> object.</p>
				1290
				1291
				1292	<h3> SetAnnotateOutput() </h3>
				1293
				1294	<p>This is a debugging function. When expanding this template, it adds
				1295	marker-strings to the output to indicate what template-substitutions
				1296	the system made. This takes a string argument which can be used to
				1297	shorten the filenames printed in the annotations: if the filename
				1298	contains the string you give, everything before that string is elided
				1299	from the filename before printing. (It's safe to just always pass in
				1300	the empty string.)</p>
				1301
				1302
				1303	<h3> SetAnnotator() </h3>
				1304
				1305	<p>This overrides the default text-based annotation used by
				1306	<code>SetAnnotateOutput()</code>. If this is set and
				1307	<code>SetAnnotateOutput()</code> is called, the per-expand data will
				1308	use this <A
				1309	HREF="#template_annotator"><code>TemplateAnnotator</code></A> instance
				1310	to do the annotation, rather than the default instance.</p>
				1311
				1312
				1313	<h3> InsertForModifiers() and LookupForModifiers() </h3>
				1314
				1315	<p><code>InsertForModifiers()</code> stores an arbitrary key/value
				1316	pair in the <code>PerExpandData</code> structure. This is used with
				1317	<A HREF="#template_modifier">template modifiers</A>: the
				1318	<code>PerExpandData</code> object passed to
				1319	<code>ExpandWithData()</code> is made available to every template
				1320	modifier that is called during expand time (including any custom
				1321	modifiers). The intended use of this functionality is to allow a
				1322	modifier to work one way when expanding a template with dictionary A,
				1323	and another way when expanding a template with dictionary B. For
				1324	instance, a modifier might encrypt part of a webpage using a user's
				1325	secret-key, which is of course different for every expansion of the
				1326	webpage.</p>
				1327
				1328	<p><code>LookupForModifiers()</code> can be used by a
				1329	template-modifier to read the key/value pair inserted by
				1330	<code>InsertForModifiers()</code>.
				1331	<code>LookupForModifiersAsString()</code> is the same, but returns the
				1332	value as a char* rather than a void*, for convenience.</p>
				1333
				1334
				1335	<h3> SetTemplateExpansionModifier() </h3>
				1336
				1337	<p>This is an advanced feature for those who need a custom hook into
				1338	template expansion. It will not be used by most programmers. It
				1339	takes a template-modifier as its argument, but this template modifier
				1340	is treated specially: instead of applying when an appropriate magic
				1341	string appears in the text of a template, it applies every time a
				1342	template is expanded during a call to <code>ExpandWithData()</code>.
				1343	Note this means that it's called not only after the top-level
				1344	template, that <code>ExpandWithData()</code> is called on, is
				1345	expanded, but also on every sub-template that is expanded due to a
				1346	template-include.</p>
				1347
				1348	<p>This unusual functionality has a few unusual properties. Since the
				1349	template expansion modifier is not called in normal fashion, the
				1350	normal <code>arg</code> argument to the template modifier does not
				1351	make sense. Instead, the <code>arg</code> is set to the path of the
				1352	template which is being expanded. Also, template expansion modifiers
				1353	can be expensive, since they are applied pretty indiscriminately, so
				1354	it can be worth implementing the <code>MightModifiy()</code> predicate
				1355	for the passed-in <code>TemplateModifier</code> to avoid unnecessary
				1356	work.</p>
				1357
				1358
				1359	<h2> <A NAME="template_annotator">The <code>TemplateAnnotator</code>
				1360	Class</A> </h2>
				1361
				1362	<p>The <code>TemplateAnnotator</code> class is used to pass in to <A
				1363	HREF="#per_expand_data"><code>PerExpandData::SetAnnotator()</code></A>,
				1364	to control how expand-time annotation is done. This is meant to be
				1365	used as a debugging routine.</p>
				1366
				1367	<p>This class is an abstract base class; <code>SetAnnotator()</code>
				1368	takes a subclass that implements the various methods of the base
				1369	class. These methods control the action taken when various template
				1370	markers are seen during template expansion.</p>
				1371
				1372	<p><code>template_annotator.h</code> defines the abstract base class,
				1373	and also a concrete subclass that is used by default for annotation if
				1374	<code>SetAnnotator()</code> is not called.</p>
				1375
				1376
				1377	<h2> <A NAME="template_dictionary_peer">The
				1378	<code>TemplateDictionaryPeer</code> Class</A> </h2>
				1379
				1380	<p>By design, it is not possible to view the contents of a
				1381	<code>TemplateDictionary</code>; we want to make sure the interface
				1382	between the logic layer of the application and the presentation layer
				1383	of the template goes in only one direction. While generally this
				1384	keeps programs as clean as possible, it presents problems in testing
				1385	code, which may want to verify that a given
				1386	<code>TemplateDictionary</code> has been filled properly. The
				1387	<code>TemplateDictionaryPeer</code> addresses this need. It lives in
				1388	<code>template_test_util.h</code>.</p>
				1389
				1390	<p>Some of the methods of <code>TemplateDictionaryPeer</code> are
				1391	useful for internal tests only. Below are some of the methods that
				1392	are most useful for user-level tests.</p>
				1393
				1394
				1395	<h3> STS_INIT_FOR_TEST </h3>
				1396
				1397	<p>This macro allows use of <code>STS_INIT</code> for testing, even
				1398	when the input pointer is not guaranteed to be allocated for the
				1399	entire length of the test (it must, of course, be allocated for the
				1400	entire lifetime of the template being tested). Since normally
				1401	<code>STS_INIT</code> requires inputs to have static duration, this
				1402	allows for more flexibility in tests, at the cost of worse memory
				1403	management and decreased code safety (in that it's possible to
				1404	accidentally violate the lifetime requirements).</p>
				1405
				1406
				1407	<h3> GetSectionValue() </h3>
				1408
				1409	<p>This returns the value for the named variable. It uses normal
				1410	template scoping rules to resolve the name.</p>
				1411
				1412
				1413	<h3> IsHiddenSection() and IsHiddenTemplate() </h3>
				1414
				1415	<p>Checks if a section or sub-template is "hidden" (that is, won't be
				1416	displayed at all).</p>
				1417
				1418
				1419	<h3> GetSectionDictionaries() and GetIncludeDictionaries() </h3>
				1420
				1421	<p>Returns all the sub-dictionaries for a given section or
				1422	template-include, in a vector.</>
				1423
				1424
				1425	<h3> Other Testing Functions </h3>
				1426
				1427	<p>template_test_util.h has other useful routines for
				1428	testing, such as ExpandIs(), which tests whether a
				1429	template + dictionary pair expands into an expected string. See the
				1430	header file for details.</p>
				1431
				1432
				1433	<h2> <A NAME="expand_emitter">The <code>ExpandEmitter</code> Class</A> </h2>
				1434
				1435	<p>There are two overloads of <A
				1436	HREF="#expand_template"><code>ExpandTemplate()</code></A>: the first
				1437	emits the expanded template to a C++ string, and the second emits to
				1438	an <code>ExpandEmitter</code>: an abstract base class that serves as a
				1439	data source. It supports just one overloaded method,
				1440	<code>Emit()</code>, that can take a char, a char*, or a C++ string as
				1441	input.</p>
				1442
				1443	<p>Using this class requires subclassing <code>ExpandEmitter</code>
				1444	and providing the various definitions for <code>Emit()</code>. For
				1445	instance, a subclass might provide definitions of <code>Emit()</code>
				1446	that send the input bytes out to a network socket.</p>
				1447
				1448	<p>In addition to defining the abstract base class,
				1449	<code>template_emitter.h</code> provides a sample concrete subclass
				1450	implementation, for emitting to a string.</p>
				1451
				1452
				1453	<h2> <A NAME="template_string">The <code>TemplateString</code> and
				1454	<code>StaticTemplateString</code> Classes</A> </h2>
				1455
				1456	<p><code>TemplateString</code> is a string-like implementation.
				1457	Ctemplate uses <code>TemplateString</code> almost exclusively,
				1458	internally. Many of the public API methods, such as
				1459	<code>TemplateDictionary::SetValue()</code>, also take
				1460	<code>TemplateString</code> as input. <code>TemplateString</code>
				1461	has implicit constructors for both C++ strings and char*'s, so every
				1462	method that takes a <code>TemplateString</code> will also work if
				1463	given a C++ string or a char. If you have a char and know its
				1464	length, you can save a bit of work by explicitly constructing a
				1465	<code>TemplateString</code> with a char* + length, for instance:</p>
				1466	<pre>
				1467	dict->SetValue(ctemplate::TemplateString("MYVAR", 5), value);
				1468	</pre>
				1469
				1470	<p>Some compile-time tools work with <code>TemplateString</code> to
				1471	offload computation from runtime to compile-time. This is possible
				1472	because the Ctemplate code often stores a hash of a string
				1473	rather than a string directly. For static, immutable strings,
				1474	<code>TemplateString</code> can store a pre-computed hash value. This
				1475	functionality is used by <A
				1476	HREF="#make_tpl_varnames_h"><code>make_tpl_varnames_h</code></A>. Thus,
				1477	using this tool to create constants to use for <code>SetValue()</code>
				1478	keys provides not only protection against typos, but a speed
				1479	improvement as well.</p>
				1480
				1481	<p>For immutable strings in your code, you can create efficient
				1482	compile-time template-string objects of your own -- in this case of
				1483	type <code>StaticTemplateString</code> -- by using the
				1484	<code>STS_INIT</code> macro, like so:</p>
				1485	<pre>
				1486	static const StaticTemplateString kSectName =
				1487	STS_INIT(kSectName, "test_SetAddSectionDictionary");
				1488	</pre>
				1489
				1490	<p>The string variable's name, <code>kSectName</code> is repeated
				1491	twice. The variable's value is specified inside the macro. Note that
				1492	this macro should be used at the top level of a file, not inside
				1493	functions (even when the variables are made static), and you should
				1494	define the <code>StaticTemplateString</code> exactly as above:
				1495	<code>static const StaticTemplateString</code>. Otherwise, the
				1496	undefined constructor/destructor order of C++ may result in surprising
				1497	behavior, wherein the <code>StaticTemplateString</code> is not
				1498	initialized when it ought to be.</p>
				1499
				1500
				1501	<h2> The <code>Template</code> Class </h2>
				1502
				1503	<p>In older version of ctemplate, the <code>Template</code> class,
				1504	which holds parsed templates, was a major part of the template
				1505	workflow: the common template use-case would be:</p>
				1506	<pre>
				1507	Template* tpl = Template::GetTemplate(filename, strip_mode);
				1508	TemplateDictionary dict(name);
				1509	tpl->Expand(&dict, &outstring);
				1510	</pre>
				1511
				1512	<p>In current use, this model is deprecated in favor of the single
				1513	<code>ExpandTemplate()</code> call; support for <code>Template</code>
				1514	methods may be removed entirely in future versions of ctemplate.
				1515	However, you may still find older code using this old formulation.</p>
				1516
				1517
				1518	<h2> <A NAME="auto_escaping">Auto-Escaping</A> </h2>
				1519
				1520	<p>The <a href="auto_escape.html">Guide to using Auto Escape</a> has
				1521	an overview of Auto Escape as well as discussion of its limitations.
				1522	<!-- TODO(csilvers): move that information here? -->
				1523	To use it, put the following text at the top of the template:</p>
				1524	<pre>
				1525	{{%AUTOESCAPE context="CONTEXT" [state="STATE"]}}
				1526	</pre>
				1527
				1528	<p>Description of the arguments:</p>
				1529	<ul>
				1530	<li> The context attribute is one of <code>HTML</code>,
				1531	<code>JAVASCRIPT</code>, <code>CSS</code>,
				1532	<code>JSON</code> or <code>XML</code>. It must correspond
				1533	to the context in which the browser will interpret this
				1534	template. <b>Warning:</b> Setting the wrong context will
				1535	result in wrong escaping applied to all variables in
				1536	the given template. In particular, if the template starts with
				1537	a <code><script></code> tag, its context is
				1538	<code>HTML</code> and not <code>JAVASCRIPT</code>. Auto-Escape
				1539	will recognize the <code><script></code> tag and hence
				1540	properly Javascript-escape the variables within it. Similarly,
				1541	if the template starts with a <code><style></code> tag,
				1542	its context is <code>HTML</code> and not <code>CSS</code>.
				1543	</li>
				1544	<li> The state attribute is commonly omitted. It accepts the
				1545	value <code>IN_TAG</code> in the <code>HTML</code> context
				1546	to indicate that the template only contains (one or more)
				1547	HTML attribute name and value pairs that are part of an
				1548	HTML tag formed in a parent template.
				1549	</ul>
				1550
				1551	<p>This will auto-escape every variable in the template. To turn off
				1552	auto-escaping for a particular variable, you can apply the
				1553	<code>none</code> modifier, like so: <code>{{MYVAR:none}}</code>.
				1554	Here is an example of an autoescaped document:</p>
				1555
				1556	<pre>
				1557	{{%AUTOESCAPE context="HTML"}}
				1558
				1559	<body>
				1560	<p>Hello {{USER}}</p>
				1561	<p><a href="{{URL}}">Your Account</a></p>
				1562	<p>Your identifier: {{ID:none}}{{! This is dangerous! }}</p>
				1563	</body>
				1564	</pre>
				1565
				1566
				1567	<h2> Development Tools </h2>
				1568
				1569	<p>This package includes several tools to make it easier to use write
				1570	and use templates.</p>
				1571
				1572
				1573	<h3> <A name="make_tpl_varnames_h">make_tpl_varnames_h:
				1574	Template Syntax Checker and Header File Generator</A> </h3>
				1575
				1576	<p><code>make_tpl_varnames_h</code> is a "lint" style syntax checker
				1577	and header file generator. It takes the names of template files as
				1578	command line arguments and loads each file into a Template object by
				1579	retrieving the file via the Template factory method. The loading of
				1580	the file does pure syntax checking and reports such errors as
				1581	mis-matched section start/end markers, mis-matched open/close
				1582	double-curly braces, such as <code>"{{VAR}"</code>, or invalid
				1583	characters in template variables/names/comments.</p>
				1584
				1585	<p>If the template passes the syntax check, by default the utility
				1586	then creates a header file for use in the executable code that fills
				1587	the dictionary for the template. If the developer includes this
				1588	header file, then constants in the header file may be referenced in
				1589	the dictionary building function, rather than hard-coding strings as
				1590	variable and section names. By using these constants, the compiler
				1591	can notify the developer of spelling errors and mismatched names.
				1592	Here's an example of how this is used, and how it helps prevent
				1593	errors:</p>
				1594
				1595	<pre>
				1596	const char * const kosr_RESULT_NUMBER = "RESULT_NUMBER"; // script output
				1597	dict.SetValue("RESSULT_NUMBER", "4"); // typo is silently missed
				1598	dict.SetValue(kosr_RESSULT_NUMBER, "4"); // compiler catches typo
				1599	</pre>
				1600
				1601	<p>Each constant is named as follows:</p>
				1602
				1603	<ul>
				1604	<li> The initial letter 'k', indicating a defined constant. </li>
				1605
				1606	<li> One or more prefix letters which are derived from the
				1607	template file name. These prefix letters consist of the first
				1608	letter of the file name, followed by the first letter following
				1609	each underscore in the name, with the exception of the letter
				1610	'p' when it is followed by the letters "ost", as is a <A
				1611	HREF="tips.html#versioning">recommended convention</A> for
				1612	template versioning. For example, the prefix letters for the
				1613	file <code>one_search_result_post20020815.tpl</code> are
				1614	<code>osr</code>. </li>
				1615
				1616	<li> An underscore. </li>
				1617
				1618	<li> The variable or section name itself, same casing. </li>
				1619	</ul>
				1620
				1621	<p>As an example, the section name "RESULT_NUMBER" in the file
				1622	one_search_result_post20020815.tpl would be given the constant name
				1623	<code>kosr_RESULT_NUMBER</code> and would appear in the header file as
				1624	<code>const char * const kosr_RESULT_NUMBER = "RESULT_NUMBER";</code>
				1625	-- as in the example above. (The variable is actually a
				1626	<code>StaticTemplateString</code>, not a char*, but the basic idea
				1627	holds.)</p>
				1628
				1629	<p>
				1630	An alternate output directory may be specified by the command line
				1631	flag <code>--header_dir</code>.
				1632	</p>
				1633
				1634	<p>The name of the generated header file is the same as the name of
				1635	the template file with an extension added to the name. By default,
				1636	that extension is <code>.varnames.h</code>. In the above example, the
				1637	header file containing the constant declarations would be named
				1638	<code>one_search_result_post20020815.tpl.varnames.h</code>. An
				1639	alternate extension may be provided via the command line flag
				1640	<code>--outputfile_suffix</code>.</p>
				1641
				1642	<p>Important command line flags:</p>
				1643
				1644	<ul>
				1645	<li> <code>--noheader</code> -- Indicates that a header file
				1646	should not be generated; only syntax checking should be done. </li>
				1647
				1648	<li> <code>--header_dir</code> -- sets the directory where the header
				1649	is written. Default: "./" </li>
				1650
				1651	<li> <code>--template_dir</code> -- sets the template root
				1652	directory. Default: <code>./</code> which is the correct
				1653	specification when it is run from the directory where the templates
				1654	are located. This is only used if the input template filenames
				1655	are specified as relative paths rather than absolute
				1656	paths. </li>
				1657
				1658	<li> <code>--outputfile_suffix</code> -- the extension added to the
				1659	name of the template file to create the name of the generated
				1660	header file. Default: <code>.varnames.h</code>.
				1661	</ul>
				1662
				1663	<p>For a full list of command line flags, run
				1664	<code>make_tpl_varnames_h --help</code>.</p>
				1665
				1666
				1667	<h3> <A name="template_converter">template-converter: convert a
				1668	template to a C++ string</A> </h3>
				1669
				1670	<p><code>StringToTemplateCache()</code> lets you load a template
				1671	from a string instead of a file. Applications may prefer this option
				1672	to reduce the dependencies of the executable, or use it in
				1673	environments where data files are not practical. In such cases,
				1674	<code>template-converter</code> can be used as a template "compiler",
				1675	letting the developer write a template file as a data file in the
				1676	normal way, and then "compiling" it to a C++ string to be included in
				1677	the executable.</p>
				1678
				1679	<p>Usage is <code>template-converter <template filename></code>.
				1680	C++ code is output is to stdout; it can be stored in a .h file or
				1681	included directly into a C++ file. Perl must be installed to use this
				1682	script.</p>
				1683
				1684
				1685	<hr>
				1686	<ul>
				1687	<li> <A HREF="guide.html">User's Guide</A> </li>
				1688	<!--
				1689	<li> <A HREF="reference.html">Reference Manual</A> </li>
				1690	-->
				1691	<li> <A HREF="auto_escape.html">Auto Escape</A> </li>
				1692	<li> <A HREF="tips.html">Tips</A> </li>
				1693	<li> <A HREF="example.html">Example</A> </li>
				1694	</ul>
				1695
				1696	<hr>
				1697	<address>
				1698	Craig Silverstein<br>
				1699	<script type=text/javascript>
				1700	var lm = new Date(document.lastModified);
				1701	document.write(lm.toDateString());
				1702	</script>
				1703	</address>
				1704
				1705	</body>
				1706	</html>
				1707