Mercurial > hg > tema

view doc/manual/index.html @ 1:548a93c24e55

find changesets by author, revision, files, or words in the commit message
Tema 0.1jk - Javakonkurs edition (imported from CVS).
author Mikhail Kryshen <mikhail@kryshen.net>
date Thu, 14 Dec 2006 23:22:05 +0300
parents
children
line source
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2 "DTD/xhtml1-transitional.dtd">
3
4 <html>
5
6 <head>
7 <title>Макропроцессор TEMA</title>
8 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
9 </head>
10
11 <body>
12 <h1>Макропроцессор TEMA</h1>
13
14 Макропроцессор TEMA обрабатывает заданные шаблоны текстовых файлов и
15 заменяет найденные в них инструкции на результаты их выполнения.
16
17 <p><b>Формат инструкций</b></p>
18
19 <blockquote>
20 <code>&lt;%<i>список_функций</i>{:|\|`}<i>данные</i>%&gt;</code>
21 </blockquote>
22 <p>
23 где<br />
24
25 <code><i>список_функций</i></code> - список имен функций, разделенных
26 пробелами. Может быть пустым.<br />
27 <code><i>данные</i></code> - данные, передаваемые функции.
28 </p>
29
30 <p><b>Формат данных</b></p>
31
32 <blockquote>
33 <code>
34 [<i>список_аргументов</i>][<i>текст</i>]
35 </code>
36 </blockquote>
37 <p>
38 где<br />
39
40 <code><i>список_аргументов</i></code> - список аргументов функции, разделенных пробелами.
41 Может быть пустым.<br />
42 <code><i>текст</i></code> - текст, передаваемый функции без разбиения на аргументы.
43 Может быть пустым. Количество аргументов, после которого следует
44 текст, зависит от функции.
45 </p><p>
46 Разделитель между списком функций и данными определяет, как должны
47 обрабатываться данные функции:
48 </p><p>
49 <code>:</code> - рекурсивная обработка,<br />
50 <code>\</code> или <code>`</code> - передать без обработки.
51 </p><p>
52 Если в списке функций задано две и более функции, они выполняются,
53 начиная с последней, так что каждая функция получает в качестве данных
54 результат выполнения следующей функции.
55 </p><p>
56 Каждая функция имеет код возврата - целое число. Код возврата
57 инструкции - код возврата первой в списке функции. Код возврата,
58 получаемый при обработке текста - сумма кодов возврата обработанных
59 инструкций (как правило, смысл этого значения - количество инструкций,
60 замененных на непустой текст).
61 </p><p>
62 Кроме скобок '&lt;', '&gt;', можно использовать скобки '[', ']'.
63 </p>
64
65
66 <h2>Функции</h2>
67
68 <p><code><b>set</b></code></p>
69
70 <table>
71 <tr><td>Аргументы:</td>
72 <td><i>имя</i></td></tr>
73
74 <tr><td>Текст:</td>
75 <td><i>значение</i></td></tr>
76
77 <tr><td>Действие:</td>
78 <td>Устанавливает значение переменной <i>имя</i>.</td></tr>
79
80 <tr><td>Результат:</td>
81 <td><i>имя</i></td></tr>
82
83 <tr><td>Код возврата:</td>
84 <td>1</td></tr>
85 </table>
86
87 <p><code><b>define</b></code></p>
88
89 <table>
90 <tr><td>Аргументы:</td>
91 <td><i>имя</i></td></tr>
92
93 <tr><td>Текст:</td>
94 <td><i>шаблон</i></td></tr>
95
96 <tr><td>Действие:</td><td>Определяет новую функцию <i>имя</i>, при
97 вызове которой обрабатывается <i>шаблон</i>. При обработке доступны
98 функции <code>nextarg</code> для получения очередного аргумента
99 вызываемой функции и <code>data</code> для получения текста.</td></tr>
100
101 <tr><td>Результат:</td>
102 <td><i>имя</i></td></tr>
103
104 <tr><td>Код возврата:</td>
105 <td>1</td></tr>
106 </table>
107
108 <p><code><b>load</b></code></p>
109
110 <table>
111 <tr><td>Аргументы:</td>
112 <td><i>имя</i> <i>имя_класса</i></td></tr>
113
114 <tr><td>Действие:</td>
115
116 <td>Определяет новую функцию <i>имя</i>. Реализация функции определена
117 Java-классом <i>имя_класса</i>, наследующим класс
118 <code>kryshen.tema.Function</code>.</td></tr>
119
120 <tr><td>Результат:</td>
121 <td><i>имя</i></td></tr>
122
123 <tr><td>Код возврата:</td>
124 <td>1</td></tr>
125 </table>
126
127 <p><code><b>prepare</b></code></p>
128
129 <table>
130 <tr><td>Аргументы:</td>
131 <td><i>имя</i></td></tr>
132
133 <tr><td>Текст:</td>
134 <td><i>запрос</i></td></tr>
135
136 <tr><td>Действие:</td>
137 <td>Подготавливает SQL-запрос <i>запрос</i> для выполнения, записывает
138 подготовленный запрос в переменную <i>имя</i>.</td></tr>
139
140 <tr><td>Результат:</td>
141 <td><i>имя</i></td></tr>
142
143 <tr><td>Код возврата:</td>
144 <td>1</td></tr>
145 </table>
146
147 <p><code><b>query</b></code></p>
148
149 <table>
150 <tr><td>Аргументы:</td>
151 <td><i>имя_запроса</i> <i>шаблон</i> <i>парам1</i> ... <i>парамN</i></td></tr>
152
153 <tr><td>Действие:</td>
154 <td>Выполняет запрос с параметрами, подготовленный с помощью функции
155 prepare. Значения параметров подставляются в запрос вместо символа
156 '?'. Значения полей ответа доступны с помощью функции <code>db</code>,
157 как переменные шаблона <i>шаблон</i>. При обработки шаблона также
158 определяется переменная <code>number</code>, содержащая номер текущей
159 строки ответа.</td></tr>
160
161 <tr><td>Результат:</td>
162 <td>результат обработки шаблона <i>шаблон</i> для каждой строки
163 ответа.</td></tr>
164
165 <tr><td>Код возврата:</td>
166 <td>Количество полученных строк ответа.</td></tr>
167 </table>
168
169 <p><code><b>optional</b></code></p>
170
171 <table>
172 <tr><td>Текст:</td>
173 <td><i>данные</i></td></tr>
174
175 <tr><td>Результат:</td><td><i>данные</i>, если при обработке данных
176 был получен код возврата отличный от 0, иначе - пустая
177 строка.</td></tr>
178
179 <tr><td>Код возврата:</td>
180 <td>1, если результат - пустая строка, 0 - иначе.</td></tr>
181 </table>
182
183 <p><code><b>image</b></code></p>
184
185 <table>
186 <tr><td>Аргументы:</td>
187 <td><i>исх_файл</i> <i>кон_файл</i> <i>формат</i> [<i>макс_ширина</i>
188 [<i>макс_высота</i>]]</td></tr>
189
190 <tr><td>Действие:</td>
191 <td>Загружает изображение из файла <i>исх_файл</i> (путь определяется
192 относительно конфигурационного параметра "resource_base") и
193 преобразует его в указанный формат, сохраняя результат в
194 <i>кон_файл</i>. Если заданы максимальная высота и ширина, большие
195 изображения будут уменьшены.</td></tr>
196
197 <tr><td>Результат:</td>
198 <td><i>кон_файл</i> при успешном выполнении, пустая строка - иначе.</td></tr>
199
200 <tr><td>Код возврата:</td>
201 <td>1 при успешном выполнении, 0 - иначе.</td></tr>
202 </table>
203
204
205 <p><code><b>copy</b></code></p>
206
207 <table>
208 <tr><td>Аргументы:</td><td><i>исх_файл</i> <i>кон_файл</i></td></tr>
209
210 <tr><td>Действие:</td><td>Копирует файл <i>исх_файл</i> в файл
211 <i>кон_файл</i> (путь <i>исх_файл</i> определяется относительно
212 конфигурационного параметра "resource_base").</td></tr>
213
214 <tr><td>Результат:</td><td><i>кон_файл</i> при успешном выполнении,
215 пустая строка - иначе.</td></tr>
216
217 <tr><td>Код возврата:</td><td>1 при успешном выполнении, 0 -
218 иначе.</td></tr>
219 </table>
220
221 <p><code><b>write</b></code></p>
222
223 <table>
224 <tr><td>Аргументы:</td><td><i>имя_файла</i></td></tr>
225
226 <tr><td>Текст:</td><td><i>данные</i></td></tr>
227
228 <tr><td>Действие:</td><td>Записывает <i>данные</i> в файл
229 <i>исх_файл</i>.</td></tr>
230
231 <tr><td>Результат:</td><td><i>кон_файл</i> при успешном выполнении,
232 пустая строка - иначе.</td></tr>
233
234 <tr><td>Код возврата:</td><td>1 при успешном выполнении, 0 -
235 иначе.</td></tr>
236 </table>
237
238 <p><code><b>read</b></code></p>
239
240 <table>
241 <tr><td>Текст:</td><td><i>имя_файла</i></td></tr>
242 <tr><td>Действие:</td><td>Читает файл <i>имя_файла</i>.</td></tr>
243 <tr><td>Результат:</td><td>прочитанные данные при успешном выполнении,
244 пустая строка - иначе.</td></tr>
245 <tr><td>Код возврата:</td><td>1 при успешном выполнении, 0 -
246 иначе.</td></tr>
247 </table>
248
249 <p><code><b>include</b></code></p>
250
251 <table>
252 <tr><td>Текст:</td><td><i>имя_файла</i></td></tr>
253 <tr><td>Действие:</td><td>включает шаблон из файла
254 <i>имя_файла</i>.</td></tr>
255 <tr><td>Результат:</td><td>результат обработки шаблона.</td></tr>
256 <tr><td>Код возврата:</td><td>код возврата, полученный при обработке
257 шаблона.</td></tr>
258 </table>
259
260 <p><code><b>!</b></code></p>
261
262 <table>
263 <tr><td>Текст:</td><td><i>данные</i></td></tr>
264
265 <tr><td>Действие:</td><td>нет.</td></tr>
266
267 <tr><td>Результат:</td><td>нет.</td></tr>
268
269 <tr><td>Код возврата:</td><td>код возврата, полученный при обработке
270 текста данных.</td></tr>
271 </table>
272
273 <p><code><b>replace</b></code></p>
274
275 <table>
276 <tr><td>Аргументы:</td><td><i>стр1</i> <i>стр2</i></td></tr>
277
278 <tr><td>Текст:</td><td><i>данные</i></td></tr>
279
280 <tr><td>Результат:</td><td>данные, с замененными вхождениями подстроки
281 <i>стр1</i> на <i>стр2</i>.</td></tr>
282
283 <tr><td>Код возврата:</td><td> код возврата, полученный при обработке
284 текста данных.</td></tr>
285 </table>
286
287 <p><code><b>xml_escape</b></code></p>
288
289 <table>
290 <tr><td>Текст:</td><td><i>данные</i></td></tr>
291 <tr><td>Результат:</td><td>текст <i>данные</i>, в котором символы
292 '&amp;', '&lt;', '&gt;', '`', '\' заменены на соответствующие сущности
293 XML.</td></tr>
294
295 <tr><td>Код возврата:</td><td> код возврата, полученный при обработке
296 текста данных.</td></tr>
297 </table>
298
299 <p><code><b>xml_cdata</b></code></p>
300
301 <table>
302 <tr><td>Текст:</td><td><i>данные</i></td></tr>
303
304 <tr><td>Результат:</td><td>данные в виде блока XML CDATA.</td></tr>
305
306 <tr><td>Код возврата:</td><td> код возврата, полученный при обработке
307 текста данных. </td></tr>
308 </table>
309
310 <p>
311 Макропроцессор TEMA расширяем: возможно добавление в систему новых
312 функций, реализованных в виде классов на языке Java.
313 </p>
314
315 <h2>Запуск</h2>
316
317 <p>java -jar tema.jar [<i>опции</i>]
318 </p><p>
319 Опции:
320 </p>
321 <table>
322 <tr><td>-d[emo]</td><td>Демонстрационный режим</td></tr>
323 <tr><td>-v[ersion]</td><td>Вывод версии</td></tr>
324 <tr><td>-h[help] -u[sage]</td><td>Вывод справки</td></tr>
325 </table>
326
327 <p>
328 При запуске читается файл "tema.properties" из текущего каталога.<br />
329 Пример файла "tema.properties":
330 </p>
331
332 <pre>
333 # Настройка источника данных
334 # resource : jdbc:odbc:database
335 # driver : sun.jdbc.odbc.JdbcOdbcDriver
336
337 # Базовый каталог ресурсов
338 # resource_base : .
339
340 # Шаблон, с которого начинается обработка
341 main_template : main.template
342
343 # Кодировки файлов
344 # input_encoding : UTF-8
345 # output_encoding : UTF-8
346
347 # Кэширование шаблонов
348 # cache_read : true
349
350 # Вывод результата разбора шаблона main.template в stderr
351 # output : stderr
352
353 # Вывод сообщений об ошибках в файл
354 # log : dbreader.log
355 </pre>
356
357 </body>
358 </html>