Mercurial > hg > tema

diff doc/manual/index.html @ 1:548a93c24e55 release_0_1jk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Tema 0.1jk - Javakonkurs edition (imported from CVS).
author Mikhail Kryshen <mikhail@kryshen.net>
date Thu, 14 Dec 2006 23:22:05 +0300 (2006-12-14)
parents
children
line wrap: on
line diff
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/index.html	Thu Dec 14 23:22:05 2006 +0300
@@ -0,0 +1,358 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
+          "DTD/xhtml1-transitional.dtd">
+
+<html>
+
+<head>
+  <title>Макропроцессор TEMA</title>
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+</head>
+
+<body>
+<h1>Макропроцессор TEMA</h1>
+
+Макропроцессор TEMA обрабатывает заданные шаблоны текстовых файлов и
+заменяет найденные в них инструкции на результаты их выполнения.
+
+<p><b>Формат инструкций</b></p>
+
+<blockquote>
+  <code>&lt;%<i>список_функций</i>{:|\|`}<i>данные</i>%&gt;</code>  
+</blockquote>
+<p>
+где<br />
+
+<code><i>список_функций</i></code> - список имен функций, разделенных
+    пробелами. Может быть пустым.<br />
+<code><i>данные</i></code> - данные, передаваемые функции.
+</p>
+
+<p><b>Формат данных</b></p>
+
+<blockquote>
+  <code>
+    [<i>список_аргументов</i>][<i>текст</i>]
+  </code>
+</blockquote>
+<p>
+где<br />
+
+<code><i>список_аргументов</i></code> - список аргументов функции, разделенных пробелами.
+    Может быть пустым.<br />
+<code><i>текст</i></code> - текст, передаваемый функции без разбиения на аргументы.
+    Может быть пустым. Количество аргументов, после которого следует
+    текст, зависит от функции.
+</p><p>
+Разделитель между списком функций и данными определяет, как должны
+обрабатываться данные функции:
+</p><p>
+<code>:</code> - рекурсивная обработка,<br />
+<code>\</code> или <code>`</code> - передать без обработки.
+</p><p>
+Если в списке функций задано две и более функции, они выполняются,
+начиная с последней, так что каждая функция получает в качестве данных
+результат выполнения следующей функции.
+</p><p>
+Каждая функция имеет код возврата - целое число. Код возврата
+инструкции - код возврата первой в списке функции. Код возврата,
+получаемый при обработке текста - сумма кодов возврата обработанных
+инструкций (как правило, смысл этого значения - количество инструкций,
+замененных на непустой текст).
+</p><p>
+Кроме скобок '&lt;', '&gt;', можно использовать скобки '[', ']'.
+</p>
+
+
+<h2>Функции</h2>
+
+<p><code><b>set</b></code></p>
+
+<table>
+<tr><td>Аргументы:</td>
+<td><i>имя</i></td></tr>
+
+<tr><td>Текст:</td>
+<td><i>значение</i></td></tr>
+
+<tr><td>Действие:</td>
+<td>Устанавливает значение переменной <i>имя</i>.</td></tr>
+
+<tr><td>Результат:</td>
+<td><i>имя</i></td></tr>
+
+<tr><td>Код возврата:</td>
+<td>1</td></tr>
+</table>
+
+<p><code><b>define</b></code></p>
+
+<table>
+<tr><td>Аргументы:</td>
+<td><i>имя</i></td></tr>
+
+<tr><td>Текст:</td>
+<td><i>шаблон</i></td></tr>
+
+<tr><td>Действие:</td><td>Определяет новую функцию <i>имя</i>, при
+вызове которой обрабатывается <i>шаблон</i>. При обработке доступны
+функции <code>nextarg</code> для получения очередного аргумента
+вызываемой функции и <code>data</code> для получения текста.</td></tr>
+
+<tr><td>Результат:</td>
+<td><i>имя</i></td></tr>
+
+<tr><td>Код возврата:</td>
+<td>1</td></tr>
+</table>
+
+<p><code><b>load</b></code></p>
+
+<table>
+<tr><td>Аргументы:</td>
+<td><i>имя</i> <i>имя_класса</i></td></tr>
+
+<tr><td>Действие:</td>
+
+<td>Определяет новую функцию <i>имя</i>. Реализация функции определена
+Java-классом <i>имя_класса</i>, наследующим класс
+<code>kryshen.tema.Function</code>.</td></tr>
+
+<tr><td>Результат:</td>
+<td><i>имя</i></td></tr>
+
+<tr><td>Код возврата:</td>
+<td>1</td></tr>
+</table>
+
+<p><code><b>prepare</b></code></p>
+
+<table>
+<tr><td>Аргументы:</td>
+<td><i>имя</i></td></tr>
+
+<tr><td>Текст:</td>
+<td><i>запрос</i></td></tr>
+
+<tr><td>Действие:</td>
+<td>Подготавливает SQL-запрос <i>запрос</i> для выполнения, записывает
+подготовленный запрос в переменную <i>имя</i>.</td></tr>
+
+<tr><td>Результат:</td>
+<td><i>имя</i></td></tr>
+
+<tr><td>Код возврата:</td>
+<td>1</td></tr>
+</table>
+
+<p><code><b>query</b></code></p>
+
+<table>
+<tr><td>Аргументы:</td>
+<td><i>имя_запроса</i> <i>шаблон</i> <i>парам1</i> ... <i>парамN</i></td></tr>
+
+<tr><td>Действие:</td>
+<td>Выполняет запрос с параметрами, подготовленный с помощью функции
+prepare. Значения параметров подставляются в запрос вместо символа
+'?'. Значения полей ответа доступны с помощью функции <code>db</code>,
+как переменные шаблона <i>шаблон</i>. При обработки шаблона также
+определяется переменная <code>number</code>, содержащая номер текущей
+строки ответа.</td></tr>
+
+<tr><td>Результат:</td>
+<td>результат обработки шаблона <i>шаблон</i> для каждой строки
+ответа.</td></tr>
+
+<tr><td>Код возврата:</td>
+<td>Количество полученных строк ответа.</td></tr>
+</table>
+
+<p><code><b>optional</b></code></p>
+
+<table>
+<tr><td>Текст:</td>
+<td><i>данные</i></td></tr>
+
+<tr><td>Результат:</td><td><i>данные</i>, если при обработке данных
+был получен код возврата отличный от 0, иначе - пустая
+строка.</td></tr>
+
+<tr><td>Код возврата:</td>
+<td>1, если результат - пустая строка, 0 - иначе.</td></tr>
+</table>
+
+<p><code><b>image</b></code></p>
+
+<table>
+<tr><td>Аргументы:</td>
+<td><i>исх_файл</i> <i>кон_файл</i> <i>формат</i> [<i>макс_ширина</i>
+[<i>макс_высота</i>]]</td></tr>
+
+<tr><td>Действие:</td>
+<td>Загружает изображение из файла <i>исх_файл</i> (путь определяется
+относительно конфигурационного параметра "resource_base") и
+преобразует его в указанный формат, сохраняя результат в
+<i>кон_файл</i>. Если заданы максимальная высота и ширина, большие
+изображения будут уменьшены.</td></tr>
+
+<tr><td>Результат:</td>
+<td><i>кон_файл</i> при успешном выполнении, пустая строка - иначе.</td></tr>
+
+<tr><td>Код возврата:</td>
+<td>1 при успешном выполнении, 0 - иначе.</td></tr>
+</table>
+
+
+<p><code><b>copy</b></code></p>
+
+<table>
+<tr><td>Аргументы:</td><td><i>исх_файл</i> <i>кон_файл</i></td></tr>
+
+<tr><td>Действие:</td><td>Копирует файл <i>исх_файл</i> в файл
+<i>кон_файл</i> (путь <i>исх_файл</i> определяется относительно
+конфигурационного параметра "resource_base").</td></tr>
+
+<tr><td>Результат:</td><td><i>кон_файл</i> при успешном выполнении,
+пустая строка - иначе.</td></tr>
+
+<tr><td>Код возврата:</td><td>1 при успешном выполнении, 0 -
+иначе.</td></tr>
+</table>
+
+<p><code><b>write</b></code></p>
+
+<table>
+<tr><td>Аргументы:</td><td><i>имя_файла</i></td></tr>
+
+<tr><td>Текст:</td><td><i>данные</i></td></tr>
+
+<tr><td>Действие:</td><td>Записывает <i>данные</i> в файл
+<i>исх_файл</i>.</td></tr>
+
+<tr><td>Результат:</td><td><i>кон_файл</i> при успешном выполнении,
+пустая строка - иначе.</td></tr>
+
+<tr><td>Код возврата:</td><td>1 при успешном выполнении, 0 -
+иначе.</td></tr>
+</table>
+
+<p><code><b>read</b></code></p>
+
+<table>
+<tr><td>Текст:</td><td><i>имя_файла</i></td></tr>
+<tr><td>Действие:</td><td>Читает файл <i>имя_файла</i>.</td></tr>
+<tr><td>Результат:</td><td>прочитанные данные при успешном выполнении,
+  пустая строка - иначе.</td></tr>
+<tr><td>Код возврата:</td><td>1 при успешном выполнении, 0 -
+иначе.</td></tr>
+</table>
+
+<p><code><b>include</b></code></p>
+
+<table>
+<tr><td>Текст:</td><td><i>имя_файла</i></td></tr>
+<tr><td>Действие:</td><td>включает шаблон из файла
+<i>имя_файла</i>.</td></tr>
+<tr><td>Результат:</td><td>результат обработки шаблона.</td></tr>
+<tr><td>Код возврата:</td><td>код возврата, полученный при обработке
+шаблона.</td></tr>
+</table>
+
+<p><code><b>!</b></code></p>
+
+<table>
+<tr><td>Текст:</td><td><i>данные</i></td></tr>
+
+<tr><td>Действие:</td><td>нет.</td></tr>
+
+<tr><td>Результат:</td><td>нет.</td></tr>
+
+<tr><td>Код возврата:</td><td>код возврата, полученный при обработке
+текста данных.</td></tr>
+</table>
+
+<p><code><b>replace</b></code></p>
+
+<table>
+<tr><td>Аргументы:</td><td><i>стр1</i> <i>стр2</i></td></tr>
+
+<tr><td>Текст:</td><td><i>данные</i></td></tr>
+
+<tr><td>Результат:</td><td>данные, с замененными вхождениями подстроки
+<i>стр1</i> на <i>стр2</i>.</td></tr>
+
+<tr><td>Код возврата:</td><td> код возврата, полученный при обработке
+текста данных.</td></tr>
+</table>
+
+<p><code><b>xml_escape</b></code></p>
+
+<table>
+<tr><td>Текст:</td><td><i>данные</i></td></tr>
+<tr><td>Результат:</td><td>текст <i>данные</i>, в котором символы
+'&amp;', '&lt;', '&gt;', '`', '\' заменены на соответствующие сущности
+XML.</td></tr>
+
+<tr><td>Код возврата:</td><td> код возврата, полученный при обработке
+текста данных.</td></tr>
+</table>
+
+<p><code><b>xml_cdata</b></code></p>
+
+<table>
+<tr><td>Текст:</td><td><i>данные</i></td></tr>
+
+<tr><td>Результат:</td><td>данные в виде блока XML CDATA.</td></tr>
+
+<tr><td>Код возврата:</td><td> код возврата, полученный при обработке
+текста данных.  </td></tr>
+</table>
+
+<p>
+Макропроцессор TEMA расширяем: возможно добавление в систему новых
+функций, реализованных в виде классов на языке Java.
+</p>
+
+<h2>Запуск</h2>
+
+<p>java -jar tema.jar [<i>опции</i>]
+</p><p>
+Опции:
+</p>
+<table>
+<tr><td>-d[emo]</td><td>Демонстрационный режим</td></tr>
+<tr><td>-v[ersion]</td><td>Вывод версии</td></tr>
+<tr><td>-h[help] -u[sage]</td><td>Вывод справки</td></tr>
+</table>
+
+<p>
+При запуске читается файл "tema.properties" из текущего каталога.<br />
+Пример файла "tema.properties":
+</p>
+
+<pre>
+# Настройка источника данных
+# resource          : jdbc:odbc:database
+# driver            : sun.jdbc.odbc.JdbcOdbcDriver
+
+# Базовый каталог ресурсов
+# resource_base     : .
+
+# Шаблон, с которого начинается обработка
+main_template     : main.template
+
+# Кодировки файлов
+# input_encoding    : UTF-8
+# output_encoding   : UTF-8
+
+# Кэширование шаблонов
+# cache_read        : true
+
+# Вывод результата разбора шаблона main.template в stderr
+# output            : stderr
+
+# Вывод сообщений об ошибках в файл
+# log               : dbreader.log
+</pre>
+
+</body>
+</html>