GRMustache的使用（HTML模板渲染工具）For iOS

GRMustache的使用（HTML模板渲染工具）For iOS  

GRMustache是一个类似templateEngine的html渲染工具，可以更加有效的帮助大家完成数据生成HTML的过程。
直达地址：https://github.com/groue/GRMustache
无论是GRMustache，还是templateEngine。他们都帮助大家避免了使用
 -[NSString stringByReplacingOccurrencesOfString:withString:]:
方法时，繁琐且频繁低效的字符串操作。可以更加优雅高效的生成HTML文件。

本篇博客源地址：http://386502324.blog.163.com/blog/static/113469377201555103951794/
由于博客后期可能还会修改，转载的内容可能不全或有错误，请浏览博客源地址。

一：导入方法
该类库支持cocospod导入管理。省去了繁琐的静态库导入以及后期的更新维护。

二：使用方法
在这里就直接拷贝官方的使用示例了。

//  输出  "Hello Arthur!"
NSString  *rendering = [GRMustacheTemplate  renderObject: @{  @"name" :  @"Arthur"  } fromString: @"Hello {{name}}!"  error:NULL ];
//  从 bundle 文件中读取输出字符串
NSString  *rendering = [GRMustacheTemplate  renderObject: user  fromResource: @"Profile"  bundle:nil  error:NULL ];
重用 templates ，避免一个同样的 templates 被多次解析
GRMustacheTemplate *template = [GRMustacheTemplate  templateFromResource: @"Profile"  bundle:nil  error:nil ];
rendering = [template  renderObject: arthur  error:NULL ];
rendering = [template  renderObject: barbara  error:NULL ];
rendering = ...

三：注意点
二是官方提供的小示例，在此还想说的是
直达链接：http://mustache.github.io/mustache.5.html
一些特殊情况的定义。
文档已经说的非常清楚，再次就不再赘述。
简单描述下，有些特殊的情况：比如使用{{{ }}}
有时候接口返回的数据中含有<p></p>等标签，如果使用{{ }}完成替换，可能会导致这些特殊的字符被转义，也就是导致格式丢失。
这篇文档就是用来处理这些特殊情况的。
如果需要，还请自行阅读该文档。

四：类的实现

了解下几个主要的类。从而明白这个类库的原理。

1：GRMustache
使用该类库需要手动引入头文件的类。
The GRMustache class provides with global-level information and configuration of the GRMustache library.
GRMustache类提供了通用的信息和库的配置。（也就是方便大家引入其他类） 。

2：GRMustacheTemplate（模板）
GRMustacheTemplate是该类库使用的最基本的类。我们在使用类库时，都需要该类的实例或者他的类方法。就想操作系统的窗口，让我们更简单的使用这个类，提供了该类最基本的功能接口。
初始化方法比较简单，这里就不再赘述。
本博客的第二块内容【使用方法】中，有该类的最基础方法

3：GRMustacheConfiguration构造配置器（解析规则） （重点介绍下。）

配置器的作用是设置tagStartDelimiter（左标签）和_tagEndDelimiter（右标签），GRMustacheContentType，以及GRMustacheContext，以便让解析器使用。

1：通过查看API文档，我们可以得知，配置器有三种级别
①：Globally  全局的唯一配置器
[GRMustacheConfiguration defaultConfiguration]

②：For all templates of a template repository 针对一个模板库的配置器
GRMustacheTemplateRepository *repo = [GRMustacheTemplateRepository templateRepositoryWithDirectory: @"/path/to/templates" ];

// Have all templates in /path/to/templates render HTML
repo.configuration.contentType = GRMustacheContentTypeHTML;

// Load the HTML template `profile.mustache`:
GRMustacheTemplate *template = [repo  templateNamed: @"profile"  error:NULL ];

③：For a single template.作者没有给实例。。暂时先空着。。

2：三个属性（property）

①：baseContext 
Mustache的渲染是根据从上下文的堆栈中获取到的值进行的。上下文的堆栈使用base context完成初始化，通过你提供给template的objects扩展生成Mustache sections，并按照他的位置进行渲染。
默认的configuration包含默认的basecontext。已经预先配置在了GRMustache的标准库中。
标准库已经预定义了一些值，例如localize（本地化）和uppercase（大写）

例如 ,  下面的  template:
{{# localize }}Hello {{ uppercase(name) }}!{{/ localize }}
会被渲染为 :
Bonjour ARTHUR ! （法语：您好，亚瑟） hello 被转义为作者国家的文字，也就是法语。

Provided with a name and a localization for "Hello %@!" string in the Localizable.strings file of the main bundle.
你可以扩展  the base context:
//  所有的模板 :
[[GRMustache  defaultConfiguration ]  extendBaseContextWithObject: myCustomLibrary]

//  某个 template repository 下的模板 :
GRMustacheTemplateRepository *repo = [GRMustacheTemplateRepository templateRepositoryWith...];
[repo.configuration  extendBaseContextWithObject: myCustomLibrary]
你也可以重设 ,  从而不再使用标准库中的上下文

[GRMustache  defaultConfiguration ].baseContext = [GRMustacheContext  context ];
repo.configuration.baseContext = [GRMustacheContext  context ];
你也可以关注  priority keys （优先键值）。他们将始终被渲染成同样的值（不能被改变或覆盖）

//  保证 {{my_important_value}} 的渲染结果始终一致， 并且不能 被其他自定义数据（库）覆盖 :
id  library = @{  @"my_important_value" : ... };
[repo.configuration  extendBaseContextWithProtectedObject: library];
See the GRMustacheContext Class Reference for a full documentation of the GRMustacheContext class. （链接可点）
base context也可以在template的层级上被定义（译者注：相对上面都是通过构造器实例定义而言）

GRMustacheTemplate *template = [GRMustacheTemplate templateFrom...];
[template extendBaseContextWith...];    // base context  的扩展
template.baseContext = ...;              // base context  的替换

②：contentType（内容类型）
默认的配置器使用了GRMustacheContentTypeHTML的内容类型，意味着所有的模板都会默认被渲染成HTML，输入值会被转码。
GRMustache也支持文本模板，渲染文本不会被转码（转义）。
This subject is fully covered in the HTML vs. Text Templates Guide.

③：tagStartDelimiter and tagEndDelimiter（左标签和右标签）
你可以通过以下两种方法层级进行标签的替换。
//  所有模板使用  <%  和  %>  作为替换标签 :
[GRMustacheConfiguration  defaultConfiguration ].tagStartDelimiter =  @"< % " ;
[GRMustacheConfiguration  defaultConfiguration ].tagEndDelimiter =  @" % >" ;

//  只是某个 template repository 使用自定义的起始标签 :
GRMustacheTemplateRepository *repo = [GRMustacheTemplateRepository templateRepositoryWith...];
repo.configuration.tagStartDelimiter =  @"[[" ;
repo.configuration.tagEndDelimiter =  @"]]" ;
另外，标签也可以在单个模板级别上进行设置"Set Delimiters Tag" 比如 {{=<% %>=}}: 标签会变为<% name %>

4：GRMustacheTemplateRepository（模板库）

一个GRMustacheTemplateRepository实例含有一系列的模板和修饰符，可以通过嵌入符相互嵌入，如{{>name}}。
这个类可以帮助你处理那些mustacheTemplate无法直接实现的情况

①：当[GRMustacheTemplate templateFrom...] 不符合你的需要( Templates Guide).
例如, 你的模板没有存储在文件中, 或者他没有被编码成UTF8的格式.
②：当你的模板被储存在多层级的路径下，但是你先想要直接使用它的直接通过修饰符partials.
{{> header }} loads a header partial template stored next to its enclosing template, but {{> /partials/header }}, with a leading slash, loads a template located at the absolute path /partials/header from the root of the template repository.
③：当你想要一组模板配置特定的 configuration。例如你想让其中一些模板渲染成文本，而让另一些模板渲染成HTML

5：GRMustacheTemplateParser（解析器）

GRMustacheTemplateParser接收一个Mustache template的字符串，并生成tokens。解析器的代理compiler类会去接收这些生成的tokens，生成语法结构树并去生成一个templateAST。
（顺便吐槽一句，这个类库的作者是法国人，把法国人的英语再翻译成汉语真是好痛苦。。）
接下来看一下他的初始化方法：- (instancetype)initWithConfiguration:(GRMustacheConfiguration *)configuration;
解析器是根据一个GRMustacheConfiguration的实例生成的。也就是说，设置好GRMustacheConfiguration（也就是解析的规则），解析器将按照此配置进行解析。

6：GRMustacheCompiler（编译器）

GRMustacheCompiler 作为代理接收GRMustacheTemplateParser 生成的GRMustacheTokens,生成一个遵循 GRMustacheTemplateASTNode protoco 的syntax tree类templateAST .

7：GRMustacheTemplateAST（语法树）

The GRMustacheTemplateAST represents the abstract syntax tree of a template.
GRMustacheTemplateAST呈现出模板的抽象语法树。

8：GRMustacheCompiler（编译器）

engine利用templateAST和context最终生成字符串。并且传出。


五：综述该类库的工作原理：

①：GRMustacheTemplateRepository创建template实例。
②：template实例创建templateParser（解析模板生成token传出）以及compiler（接收token并生成语法树）。
parser和compiler生成templateAST。
③：template实例通过GRMustacheTemplateRepository 的basecontext以及用户传入的object生成context。
④：template实例创建renderingEngine实例engine。engine利用templateAST和context最终生成字符串。并且传出。
当然，在解析的过程中还涉及到很多类。在这里就不一一提及了。

六：声明
由于本人水平有限，本博客可能有不准确或者错误的地方，还请大家海涵并指正。