Mercurial > hg > tema
view doc/manual/manual.tema @ 3:a20217d78068
Tema current (imported from CVS).
| author | Mikhail Kryshen <mikhail@kryshen.net> |
|---|---|
| date | Thu, 06 Nov 2008 23:30:18 +0300 |
| parents | 6c41a0b43e58 |
| children | 5ebf123f3486 |
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 [%!\ TODO: next_arg, data, has_more_data %]\\
112 <%function:export
113 arguments <%:definition name%>
114 input_data <%:static variable value (optional)%>
115 output <%:function data%>
116 description <%:Exports the definition to the global (outermost) context.%>
117 %>
119 <%function:unset
120 arguments <%:def1, def2, ...%>
121 output <%:nothing%>
122 description <%:Unsets the definitions.%>
123 %>
125 <%function:invoke
126 arguments <%:function, arg1, arg2, ..., data%>
127 output <%:function output%>
128 description <%:Invokes function.%>
129 %>
131 <%function:load
132 arguments <%:name, class, url1, url2, ...%>
133 output <%:name%>
134 description <%:Instantiate specified class as a Tema function definition.
135 URL arguments are optional.%>
136 %>
138 <%function:super
139 input_data <%:code%>
140 output <%:output generated by the code%>
141 description <%:Evaluates the specified template code in the super-context
142 (i.e. context of the calling function or context executing
143 the database query).%>
144 %>
146 <%function:replace
147 arguments <%:s1, s2, data%>
148 description <%:\\
149 Replaces all occurrences of <%code:s1%> with <%code:s2%> in data.%>
150 %>
152 [%!\ TODO: all functions defined in Strings.java %]\\
154 <%subsection:Input / output%>
156 <%function:copy
157 arguments <%:src, dest%>
158 description <%:Copies file <%code:src%> to <%code:dest%>.%>
159 output <%:dest%>
160 %>
162 <%function:write
163 arguments <%:name%>
164 input_data <%:text%>
165 description <%:Writes text to file.%>
166 output <%:name%>
167 %>
169 <%function:read
170 arguments <%:name%>
171 description <%:Reads file.%>
172 output <%:File contents.%>
173 %>
175 <%function:include
176 arguments <%:name%>
177 description <%:Includes template.%>
178 output <%:Result of processing the template.%>
179 %>
181 <%function:file
182 arguments <%:base, name%>
183 output <%:Path constructed from the base directory and file name.%>
184 %>
186 <%subsection:Conditionals%>
188 <%function:optional
189 input_data <%:text%>
190 output <%:Function data if it's value is non-zero or empty text.%>
191 %>
193 <%function:while
194 input_data <%:code%>
195 description <%:Repeatedly outputs it's evaluated data while it has non-zero value.%>
196 %>
198 [%!\ TODO: all functions defined in Control.java %]\\
200 <%subsection:Database%>
202 <%function:db_connect
203 arguments <%:connection name%>
204 input_data <%:resource%>
205 description <%:Establishes connection with the database.
206 Load the appropriate database driver using the <%code:load%> function
207 before using <%code:db_connect%>
208 (e.g. [%code\<%load:driver sun.jdbc.odbc.JdbcOdbcDriver%>%]).%>
209 %>
211 <%function:db_prepare
212 arguments <%:query name, connection name%>
213 input_data <%:SQL statement%>
214 %>
216 <%function:db_query
217 arguments <%:query, template, arg1, arg2, ...%>
218 description <%:Executes query, evaluating the template for each result row.%>
219 %>
221 <%function:db
222 input_data <%:column name%>
223 output <%:value from the query result.%>
224 description <%:Available in the template for the <%code:db_query%> function.%>
225 %>
227 <%function:db_row
228 output <%:current row number in the result set.%>
229 description <%:Available in the template for the <%code:db_query%> function.%>
230 %>
232 [%!\ TODO: all functions defined in ImageConverter.java %]\\
234 <%section:Running Tema%>
236 <%par:Change to the dist subdirectory in the distribution package and
237 issue the following command:%>
239 <%par:<%code:java -jar tema.jar [options] [files]%>%>
241 <%par:The following options are recognized:%>
242 <%itemize:
243 <%:<%code:--demo%> --- run demo console with a code example;%>
244 <%:<%code:-h, --help%> --- print help message;%>
245 <%:<%code:--input-encoding <arg>%> --- set the input encoding;%>
246 <%:<%code:--log <arg>%> --- log all error messages to the specified file;%>
247 <%:<%code:-o, --output <arg>%> --- set the output file;%>
248 <%:<%code:--output-encoding <arg>%> --- set the output encoding;%>
249 <%:<%code:-v, --version%> --- print the version information and exit.%>
250 %>
252 <%if:<%not embedded:%>
253 <%section:Homepage%>
255 <%par link:http://kryshen.net/tema/%>
256 %>