Mercurial > hg > tema

view misc/manual-ru-old/index.html @ 23:55fe63bb7858

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fix error reporting.
author Mikhail Kryshen <mikhail@kryshen.net>
date Wed, 22 Apr 2009 03:30:59 +0400
parents 6c41a0b43e58
children
line wrap: on
line source

<!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>

<p>Макропроцессор TEMA обрабатывает заданные шаблоны текстовых файлов и
заменяет найденные в них инструкции на результаты их выполнения.
</p><p>
Особенности:
</p>
<ul>
  <li>Расширяемость: возможно динамически подключать новые функии,
  реализованные в виде классов на Java.</li>
  <li>Работа с базами данных: использование SQL-запросов для получения
  данных.</li>
  <li>Поточная обработка данных: инструкции обрабатываются по мере
  чтения текста без необходимости загрузки файла в оперативную память
  и выполнения полного синтаксического разбора.</li>
</ul>

<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>