1
2Creating Templates for Using with Htpl Library
3================================================================
4
5
6Macros
7============================
8
9Macro starts and ends with '@' sign. When line's parsing is done the macro
10is substututed with its value.
11
12  Example: '@var1@' expands to the value of macro 'var1'.
13
14To place a '@' sign to template, escape it with a '\' sign.
15
16  Example: '\@var1\@' expands to string '@var1@'.
17
18If macro's name is not found in the list of local variables of template, then
19it is assumed that this macro is a system environment variable.
20
21  Example: '@sysvar@' expands to the value of environment variable 'sysvar'.
22
23
24Sections
25============================
26
27Parser directives:
28#include <filename>
29#section <name>
30#endsection
31
32Template file consists of one or several sections. (It can contain no sections,
33but such file should not be called a template.)
34
35Section begins with "#section <name>" and ends with "#endsection" directives.
36Each directive should be located on a separate line.
37
38Each section should be located in one file: it cannot begin in one file and
39end in another included file.
40
41If line of template is out of any section, it is simply skipped when template
42parsing is performed. So, such lines can be used as comments.
43
44  Example:
45
46  #section header
47   ...
48  #endsection
49
50  #include template.tpl
51
52  #section footer
53   ...
54  #endsection
55
56
57Condition blocks
58================================
59
60Parser directives:
61#if <expression>
62#ifdef <variable>
63#ifndef <variable>
64#elseif <expression>
65#else
66#endif
67
68Condition directives are used to parse lines of section by condition.
69
70The following expressions can be used with if or elseif commands:
71  @var@ == value
72  @var@ != value
73  @var@ =~ pattern
74  @var@ !~ pattern
75
76Part of line that contains an expression is expanded before expression is
77evaluated.
78
79If condition is true, then all the lines till #endif directive will be parsed,
80or they will be skipped if expression is false.
81
82"ifdef" block is true if <variable>'s value is defined.
83
84"ifndef" block is true if <variable>'s value is not defined.
85
86Condition block can be included in another condition block.
87
88  Example:
89
90  #if "@var@" == "value"   <-- beginning of first condition block
91   ...
92  #ifdef @var1@            <-- beginning of second condition block
93   ...
94  #endif                   <-- end of second condition block
95   ...
96  #else                    <-- continue of first condition block
97   ...
98  #endif                   <-- end of first condition block
99
100
101Formatting
102================================
103
104There are two methods of formatting:
1051) formatting macros
1062) formatting strings
107
108To format a macro you should write % sign after its name and write format
109pattern. Pattern can be written in 2 ways:
110
1111) <align sign><maximum length>
112
113  In this case macro's name will be drawn aligned to <align sign>
114  not more than <maximum length> characters.
115
1162) <align sign><align sign><align sign><align sign>  (repeats several times)
117
118  The same, but maximum length is calculated by length of all macro
119  (including '@' signs).
120
121Align signs:
122  '<' - align to left (default)
123  '>' - align to right
124  '|' - align to center
125
126  Examples:
127
128  Macro:  @time%40@
129  Output: "Sat Jul 27 15:35:18 EEST 2002      "
130
131  Macro:  @time%|40@
132  Output: "   Sat Jul 27 15:35:18 EEST 2002   "
133
134  Macro:   @time%||||||||||||||||||||||||||||@
135  Output: "   Sat Jul 27 15:35:18 EEST 2002   "
136
137  Macro:   @time%<<<<<<<<<<<<<<<<<<<<<<<<<<<<@
138  Output: "Sat Jul 27 15:35:18 EEST 2002      "
139
140  Macro:   @time%>>>>>>>>>>>>>>>>>>>>>>>>>>>>@
141  Output: "      Sat Jul 27 15:35:18 EEST 2002"
142
143To format a string you should write format pattern between '%' signs at the end
144of string to be formatted. Format pattern:
145
146  <maximum length>{<fill substring>}
147
148'{}' pattern indicates a place to be filled with <fill substring> untill
149the formatted line length is <maximum length>.
150
151  Example:
152
153  Template line...
154
155  @status%1@ @areaTag@ {} "@description@"%76{.}%
156
157  ..will be expanded to:
158
159  * 910.ANNOUNCE ........................................ "Fileecho announces"
160
161