Mercurial > hg > tema
view doc/manual/manual.tema @ 2:6c41a0b43e58
Tema 0.3 (imported from CVS).
| author | Mikhail Kryshen <mikhail@kryshen.net> |
|---|---|
| date | Tue, 19 Feb 2008 20:32:17 +0300 |
| parents | |
| children | a20217d78068 |
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, code%>
102 description <%:\\
103 Defines new function.
104 Use <%code:next_arg%>, <%code:data%>, and <%code:has_more_data%>
105 functions to access function arguments.%>
106 output <%:name%>
107 %>
109 [%!\ TODO: next_arg, data, has_more_data %]\\
111 <%function:export
112 arguments <%:definition name%>
113 input_data <%:static variable value (optional)%>
114 output <%:function data%>
115 description <%:Exports the definition to the global (outermost) context.%>
116 %>
118 <%function:unset
119 arguments <%:def1, def2, ...%>
120 output <%:nothing%>
121 description <%:Unsets the definitions.%>
122 %>
124 <%function:invoke
125 arguments <%:function, arg1, arg2, ..., data%>
126 output <%:function output%>
127 description <%:Invokes function.%>
128 %>
130 <%function:load
131 arguments <%:name, class, url1, url2, ...%>
132 output <%:name%>
133 description <%:Instantiate specified class as a Tema function definition.
134 URL arguments are optional.%>
135 %>
137 <%function:super
138 input_data <%:code%>
139 output <%:output generated by the code%>
140 description <%:Evaluates the specified template code in the super-context
141 (i.e. context of the calling function or context executing
142 the database query).%>
143 %>
145 <%function:replace
146 arguments <%:s1, s2, data%>
147 description <%:\\
148 Replaces all occurrences of <%code:s1%> with <%code:s2%> in data.%>
149 %>
151 [%!\ TODO: all functions defined in Strings.java %]\\
153 <%subsection:Input / output%>
155 <%function:copy
156 arguments <%:src, dest%>
157 description <%:Copies file <%code:src%> to <%code:dest%>.%>
158 output <%:dest%>
159 %>
161 <%function:write
162 arguments <%:name%>
163 input_data <%:text%>
164 description <%:Writes text to file.%>
165 output <%:name%>
166 %>
168 <%function:read
169 arguments <%:name%>
170 description <%:Reads file.%>
171 output <%:File contents.%>
172 %>
174 <%function:include
175 arguments <%:name%>
176 description <%:Includes template.%>
177 output <%:Result of processing the template.%>
178 %>
180 <%function:file
181 arguments <%:base, name%>
182 output <%:Path constructed from the base directory and file name.%>
183 %>
185 <%subsection:Conditionals%>
187 <%function:optional
188 input_data <%:text%>
189 output <%:Function data if it's value is non-zero or empty text.%>
190 %>
192 <%function:while
193 input_data <%:code%>
194 description <%:Repeatedly outputs it's evaluated data while it has non-zero value.%>
195 %>
197 [%!\ TODO: all functions defined in Control.java %]\\
199 <%subsection:Database%>
201 <%function:db_connect
202 arguments <%:connection name%>
203 input_data <%:resource%>
204 description <%:Establishes connection with the database.
205 Load the appropriate database driver using the <%code:load%> function
206 before using <%code:db_connect%>
207 (e.g. [%code\<%load:driver sun.jdbc.odbc.JdbcOdbcDriver%>%]).%>
208 %>
210 <%function:db_prepare
211 arguments <%:query name, connection name%>
212 input_data <%:SQL statement%>
213 %>
215 <%function:db_query
216 arguments <%:query, template, arg1, arg2, ...%>
217 description <%:Executes query, evaluating the template for each result row.%>
218 %>
220 <%function:db
221 input_data <%:column name%>
222 output <%:value from the query result.%>
223 description <%:Available in the template for the <%code:db_query%> function.%>
224 %>
226 <%function:db_row
227 output <%:current row number in the result set.%>
228 description <%:Available in the template for the <%code:db_query%> function.%>
229 %>
231 [%!\ TODO: all functions defined in ImageConverter.java %]\\
233 <%section:Running Tema%>
235 <%par:Change to the dist subdirectory in the distribution package and
236 issue the following command:%>
238 <%par:<%code:java -jar tema.jar [options] [files]%>%>
240 <%par:The following options are recognized:%>
241 <%itemize:
242 <%:<%code:--demo%> --- run demo console with a code example;%>
243 <%:<%code:-h, --help%> --- print help message;%>
244 <%:<%code:--input-encoding <arg>%> --- set the input encoding;%>
245 <%:<%code:--log <arg>%> --- log all error messages to the specified file;%>
246 <%:<%code:-o, --output <arg>%> --- set the output file;%>
247 <%:<%code:--output-encoding <arg>%> --- set the output encoding;%>
248 <%:<%code:-v, --version%> --- print the version information and exit.%>
249 %>
251 <%section:Homepage%>
253 <%par link:http://kryshen.pp.ru/tema/%>