Mercurial > hg > tema
view doc/manual/manual.tema @ 17:5ebf123f3486
Documentation update and code cleanup.
| author | Mikhail Kryshen <mikhail@kryshen.net> |
|---|---|
| date | Tue, 24 Mar 2009 19:36:09 +0300 |
| parents | a20217d78068 |
| children | 1bd3a6740cfb d3a8871e6e73 |
line source
1 [%!\
2 Tema User Manual.
3 %]\\
5 <%silent include:document.tema%>\\
7 <%document:
8 title <%:Tema -- template macro processor%>
9 author <%:Mikhail Kryshen%>
10 content
12 <%section:Introduction%>
14 <%par:Tema is a macro processor and template engine. It reads the input file
15 recursively expanding any macro found in the text.%>
17 <%par:Distinctive features:%>
18 <%itemize:
19 <%:Extensible: implement new functions as Java classes.%>
20 <%:Database access.%>
21 <%:Processes and outputs data as early as possible (function could start
22 to output data before all it's arguments are read and parsed).%>
23 <%:Apache Ant integration.%>
24 %>
26 <%par:Tema macro has the following syntax:%>
28 <%par:[%code\<%function_list{:|#|\|`}[escape]text%>[escape]%]%>
30 <%par:<%code:function_list%> is the list of text-processing functions.
31 Functions will be applied to text in reverse order.%>
33 <%par:<%code:text%> could contain space-separated list of arguments
34 followed by arbitrary data. Number of arguments is determined by the last
35 function in the <%code:function_list%>.%>
37 <%par:<%code\[arg1 arg2...] [data]%>%>
39 <%par:The text is separated from the list of functions by one of the
40 following characters:%>
42 <%itemize:
43 <%\':' -- process text recursively.%>
44 <%\'#' -- parse text but do not replace any embedded macro.%>
45 <%\'\', '`' -- do not parse text (ignore any '<%' sequences).%>
46 %>
48 <%par:<%code:escape%> is either '\' or '\\':%>
50 <%itemize:
51 <%:<%:\%> -- the following newline symbol will be removed;%>
52 <%:<%:\\%> -- the following sequence of the whitespace characters will be removed.%>
53 %>
55 <%par:You could use <%\'[%' and '%]'%> character sequences to denote macro
56 as an alternative to [%\'<%' and '%>'%].%>
58 <%par:Every function returns integer value. The general convention is to
59 return non-zero for successful operation. The value of the macro substitution
60 is the return value of the first function in the function list. The value of
61 any Tema text is the sum value of all macro in the text, except the value of
62 the text without any macro equals -1.%>
64 <%par:Internally, Tema function could be represented by any Java object.
65 Instances of kryshen.tema.Function and kryshen.tema.Context are handled
66 specially. For any other type of object, function output would be the value
67 returned by the method <%code:toString()%>.%>
69 <%section:Built-in functions%>
71 <%par emph:Notice: some functions are not yet described in this manual.
72 For the complete list of built-in functions refer to the API documentation
73 and source code.%>
75 <%function:tema
76 output <%:Tema version%>
77 %>
79 <%function:echo
80 output <%:function data%>
81 %>
83 <%function:!
84 output nothing
85 description <%:Ignores the input text (':' separator works as '#').
86 Use for commenting (e.g. <%code\[%!\ comment %]%>).%>
87 %>
89 <%function:silent
90 output nothing
91 %>
93 <%function:set
94 arguments <%:definition name%>
95 input_data <%:variable value%>
96 output <%:function data%>
97 description <%:Defines new function as a static variable.%>
98 %>
100 <%function:define
101 arguments <%:name%>
102 input_data <%:code%>
103 description <%:\\
104 Defines new function.
105 Use <%code:next_arg%>, <%code:data%>, and <%code:has_more_data%>
106 functions to access function arguments.%>
107 output <%:name%>
108 %>
110 <%function:next_arg
111 description <%:\\
112 Works in context of <%code:define%> function.
113 Parses the next argument from the calling function input.%>
114 output <%:next argument text%>
115 %>
117 <%function:data
118 description <%:\\
119 Works in context of <%code:define%> function.
120 Outputs remaining text passed to the calling function.%>
121 output <%:next argument text%>
122 %>
124 <%function:has_more_data
125 description <%:\\
126 Works in context of <%code:define%> function. Returns non-zero value if
127 the calling function has more input data available.
128 %>
129 %>
131 <%function:export
132 arguments <%:definition name%>
133 input_data <%:static variable value (optional)%>
134 output <%:function data%>
135 description <%:Exports the definition to the global (outermost) context.%>
136 %>
138 <%function:unset
139 arguments <%:def1, def2, ...%>
140 output <%:nothing%>
141 description <%:Unsets the definitions.%>
142 %>
144 <%function:invoke
145 arguments <%:function, arg1, arg2, ..., data%>
146 output <%:function output%>
147 description <%:Invokes function.%>
148 %>
150 <%function:load
151 arguments <%:name, class, url1, url2, ...%>
152 output <%:name%>
153 description <%:Instantiate specified class as a Tema function definition.
154 URL arguments are optional.%>
155 %>
157 <%function:super
158 input_data <%:code%>
159 output <%:output generated by the code%>
160 description <%:Evaluates the specified template code in the super-context
161 (i.e. context of the calling function or context executing
162 the database query).%>
163 %>
165 <%function:replace
166 arguments <%:s1, s2, data%>
167 description <%:\\
168 Replaces all occurrences of <%code:s1%> with <%code:s2%> in data.%>
169 %>
171 [%!\ TODO: all functions defined in Strings.java %]\\
173 <%subsection:Input / output%>
175 <%function:copy
176 arguments <%:src, dest%>
177 description <%:Copies file <%code:src%> to <%code:dest%>.%>
178 output <%:dest%>
179 %>
181 <%function:write
182 arguments <%:name%>
183 input_data <%:text%>
184 description <%:Writes text to file.%>
185 output <%:name%>
186 %>
188 <%function:read
189 arguments <%:name%>
190 description <%:Reads file.%>
191 output <%:File contents.%>
192 %>
194 <%function:include
195 arguments <%:name%>
196 description <%:Includes template.%>
197 output <%:Result of processing the template.%>
198 %>
200 <%function:file
201 arguments <%:base, name%>
202 output <%:Path constructed from the base directory and file name.%>
203 %>
205 <%subsection:Conditionals%>
207 <%function:optional
208 input_data <%:text%>
209 output <%:Function data if it's value is non-zero or empty text.%>
210 %>
212 <%function:while
213 input_data <%:code%>
214 description <%:Repeatedly outputs it's evaluated data while parses with non-zero value.%>
215 %>
217 <%function:if
218 arguments <%:condition%>
219 input_data <%:text%>
220 description <%:Outputs the input text if the condition parses with non-zero value.%>
221 %>
223 [%!\ TODO: all functions defined in Control.java %]\\
225 <%subsection:Database%>
227 <%function:db_connect
228 arguments <%:connection name%>
229 input_data <%:resource%>
230 description <%:Establishes connection with the database.
231 Load the appropriate database driver using the <%code:load%> function
232 before using <%code:db_connect%>
233 (e.g. [%code\<%load:driver sun.jdbc.odbc.JdbcOdbcDriver%>%]).%>
234 %>
236 <%function:db_prepare
237 arguments <%:query name, connection name%>
238 input_data <%:SQL statement%>
239 %>
241 <%function:db_query
242 arguments <%:query, template, arg1, arg2, ...%>
243 description <%:Executes query, evaluating the template for each result row.%>
244 %>
246 <%function:db
247 input_data <%:column name%>
248 output <%:value from the query result.%>
249 description <%:Available in the template for the <%code:db_query%> function.%>
250 %>
252 <%function:db_row
253 output <%:current row number in the result set.%>
254 description <%:Available in the template for the <%code:db_query%> function.%>
255 %>
257 [%!\ TODO: all functions defined in ImageConverter.java %]\\
259 <%section:Running Tema%>
261 <%par:Change to the dist subdirectory in the distribution package and
262 issue the following command:%>
264 <%par:<%code:java -jar tema.jar [options] [files]%>%>
266 <%par:The following options are recognized:%>
267 <%itemize:
268 <%:<%code:--demo%> --- run demo console with a code example;%>
269 <%:<%code:-h, --help%> --- print help message;%>
270 <%:<%code:--input-encoding <arg>%> --- set the input encoding;%>
271 <%:<%code:--log <arg>%> --- log all error messages to the specified file;%>
272 <%:<%code:-o, --output <arg>%> --- set the output file;%>
273 <%:<%code:--output-encoding <arg>%> --- set the output encoding;%>
274 <%:<%code:-v, --version%> --- print the version information and exit.%>
275 %>
277 <%if:<%not embedded:%>
278 <%section:Homepage%>
280 <%par link:http://kryshen.net/tema/%>
281 %>