Clearsilver应用文档

clearsilver的中文文档几本上没有，所以按官网的英文版翻译了一个。本人能力有限，如有错误，不吝赐教。原文地址：http://www.clearsilver.net/docs/
就clearsilver应用而言，最主要的就是数据保存与模板设计部分，只要将这两部分的语法了解了，就可以方便地使用clearsilver了，而对于c部分来说，其实只是将这两部分融合下，几本上是固定不动

的。下面分两部分来介绍，数据保存格式，模板设计语法。
数据保存格式
对于clearsilver来说，数据一般都保存在一个*.hdf的文件里。HDF意为分层的数据文件。它支持两种不同的语法来表示不同的层次，而且这两种方法可以混合起来使用。
第一种是用点号来表示。
例如：    Page.Name =My Index
                  Page.Menu.0 = Home
                  Page.Menu.1 = Help
第二种是用{}来表示层次结构。
例如：    Page{
                           Name = My Index
                           Menu{
                                    0 = Home
                                    1 = Help
                                    }
                           }
我们可以用这两种方式来任意地表示需要的数据结构。同时我们也可以向后不断地扩展，如果层次出现重复的变量，会同平时常见的情况一样，后一次赋值会将前一次替换。例如：我们可以在上个page

后面再加上
Page{
                           Name = My Index2
                           Menu{
                                    0 {
                                              Name = hello
                                    }
                                    }
                           }
这样的话最终        Page.Name = My index2
                                    Page.Menu.0 = Home
                                    Page.Menu.0.Name = hello
因为clearsilver提供了对hdf文件的读写接口，所以它是支持动态配置的，但是hdf最好还是用来保存为模板文件提供的静态数据。
对于hdf还提供了两个非常重要的语法
1、  变量赋值
例如：Page.Name : Page.Menu.0.Name
这就意味着将Page.Menu.0.Name的值赋给Page.Name，所以Page.Menu.0.Name必须提前定义。
2、  像linux终端中定义一个多行的字符串一样，hdf中数据也可以如此定义
例如：Page.Name <<EOM
                   This is the first line
                   This is the second line
                   ….
                   EOM
模板语法
对于clearsilver模板文件，一般会被创建为*.cst或者是*.cs，里面内嵌着clearsilver模板命令。模板文件定义了hdf文件中的数据的表现形式。内嵌的模板命令格式如下：
<?cs 具体的clearsilver 命令?>
例如：<?cs var:Page.Name?>
模板命令被分为四类（16个）：
1、  substitution替换类：var, evar, lvar, include,linclude, set, name
2、  flow control判断类：if, else, elif, alt
3、 iteration   迭代类：each, loop,with
4、  macros    宏定义类：def,call
对于判断类，迭代类，宏定义类在使用时同html中的表单使用一样，同时需要有一个开始符和结束符。
例如<?cs if … ?>
                           ….
                  <?cs /if?>
另外clearsilver也支持注释，注释的格式为 <?cs # …..?>
下面我们按照模板命令的类别来逐个介绍模板命令。
1、            substitution替换类 (var,evar, lvar, include, linclude, set, name)
var:这个是简单的变量替换，例如数据文件中定义了Page.Name =hello，则在模板文件中<?csvar:Page.Name?>代表的就是值hello
evar:它和var很类似，但是它的数据获得是在clearsilver的数据加载解析进来的时候，所以即使模板中有命令改变了变量的值，也不会影响到evar输出的值。
lvar:它和evar很类似，但是它的赋值时间是在模板渲染的时候，而不是解析的时候。所以在渲染的时候可能会出现语法错误。
name:获 得所给的数据最低层次的名称。例如：<?csname:Page.Namex?>所得到的结果就是最你层次的Namex。在进行迭代类及宏定义类命令中会经常使用该函数获得别名变量的真实名字。同时也有一个

函数实现name相同的功能，<?cs var:name(Page.Namex)?>和<?cs name:Page.Namex?>是一样的结果。
include:它可以将其他的模板文件包含进来同时解析该文件，被包含的变量可以是一个字符串，也可以是一个变量。例如<?csinclude:”header.cs” ?>
linclude:它和include类似，但是在渲染模板时加载和解析
set:设置变量，一般是只有在需要的时候才用set命令，因为一般的hdf文件中的数据会是一个静态数据。
2、            flow control判断类（if, else,elif, alt）
if/elif/else这个和其他程序的语法类似。例子如下：
<?cs if:a?>
        <?cs ….?>
<?cs elif ?>
        <?cs …?>
<?cs else ?>
        <?cs …?>
<?cs /if ?>
alt:它其实是if varelse的缩写。相当于对后面的值为false时运行。例如：
        <?cs alt:a ?>
                  ……
        <?cs /alt ?>

3、            iteration 迭代类(each, loop,with)
each:each将遍历所有的子节点，例如：有这样一个数据集
        Page {
  Access = Public
  Content = myword.cs
  Menu {
    0 {
     Name = Home
     URL = /
    }
    1 {
     Name = Preferences
     URL = /prefs
    }
    2 {
     Name = Help
     URL = /help.html
    }
    3 {
     Name = Support
     URL = /feedback/
    }
  }
}
如果对Page进行each操作将遍历Page.Access,Page.Content和Page.Menu。如果对Page.Menu进行each操作将遍历Page.Menu.0,Page.Menu.1,Page.Menu.2和Page.Menu.3。如下是操作实例:
        <?cs each:item = Page.Menu ?>
                  <?cs name:item ?> -<ahref=”<?cs var:item.URL?>”>
                           <?cs var:item.Name ?>
                           </a><br>
        <?cs /each ?>
运行结果为：
        0 - <ahref="/">Home</a><br>
  1 - <ahref="/prefs">Preferences</a><br>
  2 - <ahref="/help.html">Help</a><br>
  3 - <ahref="/feedback/">Support</a><br>
with:with操作主要是将一个数组类的数据将它的某条记录用另一个变量名替换。例如：
        <?cs with:item = Page.Menu[foo - #1]?>
                  <?cs name:item ?>
        <?cs /with?>
        如果foo=3的话，则结果为2
loop:用来创建一数字循环。它的参数为开始数字，结束数字，步长。Clearsilver保证loop循环有终止条件。例如：
        <?cs loop:x = #1, #12, #-2 ?>
                  <?cs var:x ?>
        <?cs /loop ?>
        <?cs loop:x = 12, 1 ,-2?>
                  <?cs var:x ?>
        <?cs /loop ?>
4、            macros 宏定义类：def,call
def:定义宏
call:引用宏
例如：定义了如下宏
        <?cs def:map_val(val ,map) ?>
                  <?cs each:item = map ?>
                           <cs if:val == item ?>
                                    <?cs var:item.val ?>
                           <?cs /if ?>
                  <?cs /each ?>
        <?cs /def ?>
假设有数据：
Lang.Dates {
  Weekdays {
    0 = 0
    0.val =Sunday
    1 = 1
    1.val =Monday
    2 = 2
    2.val =Tuesday
    3 = 3
    3.val =Wednesday
    4 = 4
    4.val =Thursday
    5 = 5
    5.val =Friday
    6 = 6
    6.val =Saturday
  }
}
那么用call调用宏
        <?cs call:map_val(#6, Lang.Dates.Weekdays)?>
最后的结果为Saturday，但是前面有很多空格，这是由于    <?cs var:item.val ?>前的空格导致的。我们可以
<?cs def:map_val(val, map)?><?cs each:item = map
   ?><?cs if:val == item
     ?><?cs var:item.val?><?cs
     /if ?><?cs
    /each?><?cs
/def ?>
这样来书写模板就避免了前面的空格输出。
模板表达式Clearsilver下一些常见的语法规则在任意的参数下都会用到。例如：
Page.Title
     Page["Title"]
       Page[varname]
     Page["Title"] == "Home"
     (#Page.Count > #1) || (?Page.Next)
Clearsilver有四种不同的参数类型。
1、 数字：它是一个可以转换为数字的字符串，同时可以用#操作符来强制将字符串转换为数字类型。例：103，0x1a, -23, +14,#83
2、  字符串：单引号或双引号表示引出的字符串
3、 变量：是一个局部变量（在call/def,each,with,loop中定义的变量）或是hdf文件中的数据变量。如果变量名是一个数字型的，必须使用$符号来获得变量值
4、  数值变量：值为数字的变量

Clearsilver有四种不同的值类型：变量、字符串、数字、boolean型。数字的运算，对于数字型的字符串也成立，但是一个除为，即“+”，对于数字型字符串为字符串相连，对于数字为相加。

Clearsilver操作符（按照优先级从低到高）

操作符

说明

值类型

，

，操作

 

||

或

Boolean

&&

与

Boolean

==

相等

Boolean

!=

不等

Boolean

> 

大于

Boolean

>=

大于等于

Boolean

< 

小于

Boolean

<=

小于等于

Boolean

+

字符串相连/加

String/Numeric

-

减

Numeric

*

乘

Numeric

/

除

Numeric

%

取余

Numeric

+

正数

Numeric

-

负数

Numeric

#

强制数字化

Numeric

$

强制变量

Variable

!

非

Boolean

?

 

Boolean

.

子变量名

Variable

[]

扩展变量名,类.

Variable

()

函数调用

 

 

 

 

 

函数表达式

Clearsilver提供了一些函数。所有的函数返回都是一个字符串或数字。函数可以在表达式的任何变量可以使用的位置使用。

函数名

参数

说明

subcount(var)

HDF变量

返回变量子节点个数

name(local)

局部变量

返回HDF变量名称，相当于name:local

First(local)

局部变量

如果local是loop或each中的第一个则返回true

last(local)

局部变量

如果local是loop或each中的最后一个则返回true

Abs(expr)

数学表达式

绝对值

Max(expr1,expr2)

数学表达式

返回较大的值

Min(expr1,expr2)

数学表达式

返回较小的值

string.slice(expr, start, end)

String,num,num

截取字符串的一部分

string.find(string, substr)

String

如果找到了返回出现位置，否则-1

string.length(expr)

String表达式

String表达式长度

_(expr)

String表达式

只有当支持gettext时使用

 

ClearsilverAPI允许用户自己添加字符串操作函数。这些函数只有一个字符串参数，返回结果也只有一个字符串。Clearsilver CGIKit为clearsilver提供了好些Web过滤器函数。这些函数可以通过cgi_register_strfuncs()添加到C