8、ctemplate,帮助文档，简记（1）

1、TemplateDictionary, 用来在主函数中扩展模板。（used to expand a template file. It is used by the main functions for expanding a template, found in template.h.）

TemplateCache，模板对象的集合。

TemplateNamelist provides various introspection routines on collections of Template objects.

TemplateModifier and PerExpandData are used to modify the values of a TemplateDictionary at expand time. TemplateAnnotator does too, but is intended for debugging purposes. TemplateDictionaryPeer 用来测试模板代码。

ExpandEmitter 提供将一个扩展模板发布成任意的输出。

TemplateString 类似string的类。

2、Start section and end section markers, which delimit sections which may appear zero, one, or N times in the output. Section markers look like this: {{#FOO}}...{{/FOO}}

就是我们前面翻译的“片断”。

3、Template-include markers look like this: {{>FOO}}。类似sections ，可以出现一次或多次。

4、ExpandTemplate()：模板系统的主要工作函数。

ctemplate::ExpandTemplate("example.tpl", ctemplate::DO_NOT_STRIP, &dict, &output);

成功，返回真，失败返回false。

As always, the "filename" can also be a key to a string-based template, inserted directly into the cache via StringToTemplateCache().

Expand()是这个函数的重载版本。

ctemplate::Template* tpl = ctemplate::Template::GetTemplate("./ctexample.tpl", ctemplate::DO_NOT_STRIP);

    std::string output;

    tpl->Expand(&output, &dict);

5、设置一个模板

ctemplate::DO_NOT_STRIP:逐字输出模板

ctemplate::STRIP_BLANK_LINES: 删除空行

ctemplate::STRIP_WHITESPACE:删除空行和每一行的首尾空白字符。

6、ExpandWithData()

类似ExpandTemplate

ctemplate::TemplateDictionary dict(...);

   ctemplate::PerExpandData per_expand_data;

   string output;

   ctemplate::ExpandWithData(filename, strip_mode, &output, &dict,

                             &per_expand_data);

per_expand_data为NUL，就是ExpandTemplate。

7、LoadTemplate()：从磁盘（文件）读入模板

loads the file into the default template cache. Future calls to ExpandTemplate() or ExpandWithData() will get the parsed template from the cache, without needing to go to disk.

read from disk, parsed, and inserted into the cache.

这个函数，会在加载过程中，把所有相关的错误全部detect到。This will catch all errors except for errors involving sub-templates.

8、StringToTemplateCache()：从字符串读入模板

9、default_template_cache() and mutable_default_template_cache() 是两个高级特性。上面讲到的，ExpandTemplate(), LoadTemplate()之类，都是TemplateCache class的静态实例，可以通过default_template_cache这两个函数访问。

10、In general, an application will need to call a TemplateDictionary method for every marker in the associated template。

11、Data Dictionaries，就是一个map。

section（我们称呼的片断），是一系列字典数据。

整个字典结构就是一颗树：主字典，一系列的辅字典，及包含模板。查找maker时，由下而上查找。

12、SetValue，设置maker({{}})中变量的值，以一个string作为输入，C++string和Cchar*都将被自动转换成TemplateString。

dict.SetValue("NAME", "John Smith");

13、SetIntValue()，以整形值作为输入

dict3->SetIntValue("VALUE", winnings);

14、SetFormattedValue() is a convenience routine. SetFormattedValue(key, arg1, arg2, ...) is logically equivalent to

   char buffer[A_BIG_ENOUGH_NUMBER];

   sprintf(buffer, arg1, arg2, ...);

   SetValue(key, buffer);

dict3->SetFormattedValue("TAXED_VALUE","%.2f", winnings *0.83);

15、SetGlobalValue() ，类似SetIntValue，但是针对全局字典的。Since the global dictionary（所有模板字典共享） is shared across all template dictionaries, this is a static method on TemplateDictionary. It is thread-safe. It is also relatively slow.

    SetTemplateGlobalValue() is like SetValue(), but the values are preserved across template-includes.（仅限于包含的模板中）。

示例代码

模板

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}}.

逻辑代码

   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);

结果

   Jane McJane has won One Million dollars!  And it's all yours, John Doe.  It is worth One Million.

The second expand yields this:

   To: John Doe.  Amount: .

参考

【1】 http://google-ctemplate.googlecode.com/svn/trunk/doc/reference.html