Clearsilver Application Documentation

Clearsilver's Chinese documents are not on a few books, so the English version of the official website has been translated by one. I have limited ability, if there are mistakes, I would like to enlighten. Original address: http://www.clearsilver.net/docs/
As far as the Clearsilver application is concerned, the most important is the data preservation and template design part, as long as the two parts of the syntax to understand, you can easily use the clearsilver, and for the C part, in fact, just the two parts of the fusion, a few are fixed

Of Below are two parts to introduce, data saving format, template design syntax.
Data Save format
For Clearsilver, data is generally stored in a *.HDF file. HDF means a hierarchical data file. It supports two different syntaxes to represent different levels, and these two methods can be used in a mixed form.
The first is indicated by a dot number.
Example: Page.name =my Index
page.menu.0 = Home
Page.menu.1 = Help
The second is to use {} to represent the hierarchy.
Example: page{
Name = My Index
menu{
0 = Home
1 = Help
}
}
We can use these two methods to arbitrarily represent the data structure we need. At the same time, we can also expand backwards, if there are duplicate variables at the level, as usual, the next assignment will replace the previous one. For example, we can have the last page

Plus the back.
page{
Name = My Index2
menu{
0 {
Name = Hello
}
}
}
In this case, the final page.name = My index2
page.menu.0 = Home
Page.menu.0.name = Hello
Because Clearsilver provides read and write interfaces to HDF files, it is supported for dynamic configuration, but HDF is best used to save static data provided as template files.
For HDF also provides two very important syntax
1. Assigning values to variables
Example: Page.name:page.menu.0.name
This means that the value of Page.menu.0.name is assigned to Page.name, so page.menu.0.name must be defined in advance.
2, like a multi-line string defined in the Linux terminal, the data in HDF can also be defined as such
Example: Page.name <<eom
The first line
The second line
....
EOM
Template syntax
For clearsilver template files, they are typically created as *.CST or *.cs, with clearsilver template commands embedded inside them. The template file defines the representation of the data in the HDF file. The embedded template command format is as follows:
<?cs Specific Clearsilver command?>
Example: <?cs var:page.name?>
The template commands are divided into four classes (16):
1. Substitution Replacement class: Var, evar, Lvar, Include,linclude, set, name
2. Flow control judgment Class: If, else, Elif, alt
3, Iteration Iteration class: each, Loop,with
4, Macros macro definition class: Def,call
For a judgment class, an iterative class, the macro definition class is used in the same way as a form in HTML and requires a starting and ending character.
For example <?cs if ...? >
....
<?cs/if?>
In addition, Clearsilver also support comments, the format of the note is <?cs # ... >
Let's follow the template command by the category of the template command.
1. Substitution Replacement Class (Var,evar, Lvar, include, Linclude, set, name)
var: this is a simple variable substitution, for example, Page.name =hello is defined in the data file, the value Hello is represented in the template file <?csvar:Page.Name?>
Evar: It is similar to Var, but its data acquisition is in the Clearsilver data load parsing, so even if the template has a command to change the value of the variable, it will not affect the value of the Evar output.
Lvar: It is similar to Evar, but its assignment time is when the template is rendered, not when it is parsed. Therefore, there may be syntax errors when rendering.
Name: Gets the lowest level of the given data. For example, the result of:<?csname:page.namex?> is the Namex of your level. This function is often used in the iteration class and macro definition class commands to obtain the real name of the alias variable. There is also a

The function implements name the same function, <?cs var:name (Page.namex)?> and <?cs name:page.namex?> are the same results.
Include: it can include other template files to parse the file at the same time, the included variable can be a string, or it can be a variable. For example <?csinclude: "Header.cs"?>
Linclude: It is similar to include, but loads and resolves when rendering a template
Set: Sets the variable, usually only when needed to use the SET command, because the general HDF file data will be a static data.
2. Flow control judgment Class (if, Else,elif, Alt)
If/elif/else This is similar to the syntax of other programs. Examples are as follows:
<?cs if:a?>
<?cs ....?>
<?cs elif?>
<?cs ...? >
<?cs Else?>
<?cs ...? >
<?cs/if?>
ALT: It is actually an abbreviation for if Varelse. Runs when the value is false on the back. For example:
<?cs alt:a?>
......
<?cs/alt?>

3. Iteration Iteration Class (each, Loop,with)
Each:each will traverse all child nodes, for example: there is a dataset
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/
}
}
}
If you do each of the Page, you will traverse Page.access,page.content and Page.menu. If each operation is performed on Page.menu, the page.menu.0,page.menu.1,page.menu.2 and page.menu.3 are traversed. Here is an example of the operation:
<?cs Each:item = Page.menu?>
<?cs name:item?>-<ahref= "<?cs Var:item. Url?> ">
<?cs Var:item. Name?>
</a><br>
<?cs/each?>
The result of the operation is:
0-<ahref= "/" >Home</a><br>
1-<ahref= "/prefs" >Preferences</a><br>
2-<ahref= "/help.html" >Help</a><br>
3-<ahref= "/feedback/" >Support</a><br>
The with:with operation is primarily to replace one of its records with another variable name in the data of an array class. For example:
<?cs With:item = page.menu[foo-#1]?>
<?cs Name:item?>
<?cs/with?>
If foo=3, the result is 2.
Loop: Used to create a number loop. Its parameters are the start number, the ending number, and the step size. The Clearsilver guarantees that the loop loop has a termination condition. For example:
<?cs loop:x = #1, #12, #-2?>
<?cs var:x?>
<?cs/loop?>
<?cs loop:x = 1,-2?>
<?cs var:x?>
<?cs/loop?>
4, Macros macro definition class: Def,call
DEF: Defining macros
Call: Referencing macros
For example, define the following macro
<?cs Def:map_val (val, map)?>
<?cs Each:item = Map?>
<cs If:val = = Item?>
<?cs Var:item.val?>
<?cs/if?>
<?cs/each?>
<?cs/def?>
Suppose you have data:
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
}
}
Then call the macro by calling
<?cs Call:map_val (#6, Lang.Dates.Weekdays)?>
The final result is Saturday, but there are a lot of spaces ahead, which is due to the space <?cs Var:item.val?> ago. We can
<?cs Def:map_val (val, map)? ><?cs Each:item = Map
? ><?cs If:val = = Item
? ><?cs Var:item.val?><?cs
/if? ><?cs
/each?><?cs
/def?>
This allows you to write a template that avoids the preceding whitespace output.
Template expressions Clearsilver Some common syntax rules are used under arbitrary parameters. For example:
Page.title
page["Title"]
Page[varname]
page["Title"] = = "Home"
(#Page. Count > #1) | | (? Page.next)
The clearsilver has four different parameter types.
1, Number: It is a string that can be converted to a number, and a # operator can be used to force a string to be converted to a numeric type. Example: 103,0x1a, -23, +14, #83
2, String: Single or double quotation marks to indicate the string
3. Variable: is a local variable (a variable defined in Call/def,each,with,loop) or a data variable in a HDF file. If the variable name is a numeric type, you must use the $ symbol to get the value of the variable
4. Numeric variable: A variable with a numeric value

Clearsilver has four different value types: variable, string, numeric, Boolean. Numeric operations, for the numeric type of string is also established, but a except for, that is, "+", for the numeric string strings are concatenated, for the number is added.

Clearsilver operator (from lowest to highest priority)

Operator	Description	Value type
，	Operation
||	Or	Boolean
&&	And	Boolean
==	Equal	Boolean
!=	Range	Boolean
>	Greater than	Boolean
>=	Greater than or equal	Boolean
<	Less than	Boolean
<=	Less than or equal	Boolean
+	Strings Connected/Added	String/numeric
-	Reducing	Numeric
*	By	Numeric
/	Except	Numeric
%	Take surplus	Numeric
+	Positive	Numeric
-	Negative	Numeric
#	Forcing digitization	Numeric
$	Coercion variables	Variable
!	Non -	Boolean
?		Boolean
.	Child variable Name	Variable
[]	Extended variable name, class.	Variable
()	Function call

function Expression

Clearsilver provides a number of functions. All function returns are a string or a number. A function can be used where any variable of an expression can be used.

Name of function	Parameters	Description
Subcount (Var)	HDF variable	Returns the number of variable quantum nodes
Name (local)	Local variables	Returns the HDF variable name, equivalent to Name:local
First (local)	Local variables	Returns true if local is the first in loop or each
Last (local)	Local variables	Returns true if local is the last in loop or each
Abs (expr)	Mathematical expressions	Absolute
Max (EXPR1,EXPR2)	Mathematical expressions	Returns a larger value
Min (EXPR1,EXPR2)	Mathematical expressions	Returns a smaller value
String.slice (expr, start, end)	String,num,num	Intercept part of a string
String.find (String, substr)	String	If a return occurrence is found, otherwise-1
String.Length (expr)	string expression	string expression length
_ (expr)	string expression	Use only when GetText is supported

CLEARSILVERAPI allows the user to add their own string manipulation functions. These functions have only one string argument, and the returned result has only one string. Clearsilver Cgikit provides a number of web filter functions for Clearsilver. These functions can be added via Cgi_register_strfuncs () to C