TreeDL: руководство пользователя

Инструмент предназначен для обработки описания структуры дерева на языке TreeDL. Он обеспечивает проверку синтаксической и семантической корректности описания структуры дерева, генерацию его HTML представления с перекрестными ссылками, трансляцию описания структуры дерева в целевой язык программирования и другие действия, которые могут быть реализованы с помощью подключаемых модулей.

Chapter 2. Системные требования

Java Runtime Environment версии 1.4 или более новая. Рекомендуется Sun JRE 1.4.2 или более новая (http://java.sun.com).

Chapter 3. Установка инструмента

Инструмент поставляется в виде архива с именем treedl-<version>-<status>-<date>-standalone.zip. Где <version> - версия инструмента, <status> - уровень стабильности (alpha, beta, stable и т.п.) и <date> - дата выхода версии. При разархивировании этого файла будет создан каталог treedl-<version>-<status>-<date> со следующими подкаталогами:

bin/ - запускаемые файлы treedl.exe (Intel x86, Win32) и treedl (*nix shell script)

docs/ - документация

lib/ - библиотеки

src/ - исходные тексты инструмента

Chapter 4. Структура командной строки

treedl [-Jjvmoption...] file [action...]

jvmoption - параметры java-машины;

file - файл для обработки;

action - действия, которые последовательно будут выполнены над файлом. Если действия не указаны, происходит только проверка синтаксической корректности файла.

Пример:

treedl -J-Dtreedl.properties.file=TreeDL.tdl.properties TreeDL.tdl check translate xref

java-машине будет передан параметр -Dtreedl.properties.file=TreeDL.tdl.properties, над файлом TreeDL.tdl будут последовательно выполнены действия check translate xref.

При запуске без параметров выводится описание командной строки. Расширенная информация о возможностях инструмента выводится при задании знака минус вместо имени файла:

treedl [-Jjvmoption...] - [plugin...]

Если имена подключаемых модулей plugin не указаны, выводится список доступных подключаемых модулей с указанием их вида, в том числе и действий.

Если имена подключаемых модулей указаны - выводится описание каждого из них.

Chapter 5. Конфигурация

Инструмент использует следующие системные свойства:

Имя свойства	Описание
`treedl.properties.file`	Имя файла конфигурации инструмента. В первую очередь ищется ресурс с таким именем, затем файл. Файл содержит список свойств в стандартном формате. Значение по умолчанию: `treedl.properties`
`treedl.plugins.file`	Имя файла со списком доступных подключаемых модулей. В первую очередь ищется ресурс с таким именем, затем файл. Файл содержит список свойств в стандартном формате. Значение по умолчанию: `treedl.plugins`
`treedl.mbox.class`	Имя класса, обрабатывающего сообщения об ошибках. По умолчанию сообщения об ошибках выводятся в стандартный поток ошибок. Значение по умолчанию: `com.unitesk.atp.messages.PrintStreamMessageBox`
`treedl.language`	Целевой язык модуля. Это свойство используется только для модулей, в которых не указано свойство модуля `treedl.language`.

Значение свойства treedl.properties.file может быть указано только в командной строке, значения остальных свойств могут быть указаны как в командной строке, так и в файле конфигурации, если он указан.

Стандартный формат списка свойств описан в документации Sun JDK для метода load( java.io.InputStream ) класса java.lang.Properties.

Инструмент treedl версии LL.ll.TT.tt поддерживает версии языка TreeDL LL.0-LL.ll. Версия языка TreeDL задается значением свойства модуля:

Сущность	Имя свойства	Описание
модуль	`treedl.version`	Используемая версия языка TreeDL в виде `LL.ll`.

Chapter 6. Подключаемые модули

Table of Contents

Проверка корректности описания структуры дерева

Генерация HTML представления описания дерева с перекрёстными ссылками

Трансляция описания структуры дерева в язык программирования

Модуль трансляции в язык программирования Java
Модуль трансляции в язык программирования Java5
Модуль трансляции в язык программирования C#

Генерация визитеров

Генерация интерфейса и реализаций фабрик создания вершин

Генерация обходчиков

Генерация шаблонов сообщений для библиотеки atplib-3.x.x

Генерация шаблонов сообщений для библиотеки atplib-4.x.x

Отладочный вывод внутреннего представления описания структуры дерева

Основная функциональность инструмента реализована с помощью подключаемых модулей. Доступные подключаемые модули перечислены в файле, который задает свойство treedl.plugins.file. Подключаемому модулю с именем <plugin> доступны свойства с именами вида treedl.<plugin>.<property>, с помощью которых осуществляется его настройка. Кроме того, подключаемый модуль может пользоваться декларативной информацией, указанной в описании структуры дерева.

Часть подключаемых модулей реализует действия. Имена действий могут быть указаны в командной строке запуска инструмента. Ниже перечислены действия, входящие в поставку инструмента.

Action	Description
`check`	the section called “Проверка корректности описания структуры дерева”
`xref`	the section called “Генерация HTML представления описания дерева с перекрёстными ссылками”
`translate`	the section called “Трансляция описания структуры дерева в язык программирования”
`visitor`	the section called “Генерация визитеров”
`factory`	the section called “Генерация интерфейса и реализаций фабрик создания вершин”
`walker`	the section called “Генерация обходчиков”
`messages`	the section called “Генерация шаблонов сообщений для библиотеки atplib-3.x.x”
`dump`	the section called “Отладочный вывод внутреннего представления описания структуры дерева”

Проверка корректности описания структуры дерева

Проверка корректности описания структуры дерева выполняется действием check. Проверяемые семантические ограничения описаны в документе "TreeDL: язык описания структуры деревьев".

Используемые системные свойства:

Имя Описание

treedl.check.source.path Список каталогов, в которых производится поиск TreeDL файлов, содержащих описания используемых базовых модулей. Базовый модуль с полным именем <QID> ищется в файле с путем <PQID>.tdl (<PQID> - результат замены '.' на '/' в имени <QID>) относительно каждого каталога в списке treedl.check.source.path, затем относительно текущего каталога, затем ищется ресурс с таким путем и именем.

Имя	Описание
`treedl.check.source.path`	Список каталогов, в которых производится поиск TreeDL файлов, содержащих описания используемых базовых модулей. Базовый модуль с полным именем `<QID>` ищется в файле с путем `<PQID>``.tdl` (`<PQID>` - результат замены `'.'` на `'/'` в имени `<QID>`) относительно каждого каталога в списке `treedl.check.source.path`, затем относительно текущего каталога, затем ищется ресурс с таким путем и именем.

Используемые свойства сущностей:

Сущность	Имя свойства	Описание
модуль	`treedl.language`	Целевой язык модуля. Значение по умолчанию: `code`. Значение по умолчанию означает, что модуль не нацелен на конкретный язык программирования.

Генерация HTML представления описания дерева с перекрёстными ссылками

С помощью действия xref для семантически корректного описания дерева генерируется HTML представление, снабженное перекрёстными ссылками между использованиями и определениями сущностей. Это представление удобно использовать в качестве документации.

Используемые системные свойства:

Имя	Описание
`treedl.xref.check.action`	Имя действия, которое будет вызвано для проверки семантической корректности описания дерева. Значение по умолчанию: check.
`treedl.xref.links.file`	Имя файла, содержащего соответствие между именами базовых модулей и URL каталогов, содержащих сгенерированные html-файлы для них. Файл имеет стандартный формат списка свойств. Имя свойства - это полное имя модуля. Значение - URL каталога, содержащего сгенерированные html-файлы для этого модуля. Значение по умолчанию - `treedl.xref.links`
`treedl.xref.output.dir`	Каталог, куда будут помещены сгенерированные html-файлы. Значение по умолчанию - текущий каталог.
`treedl.xref.update`	`true` - генерировать файл только в том случае, если он не существует или старее исходного TreeDL-файла. При любом другом значении этого свойства файлы будут генерироваться всегда. Значение по умолчанию - `true`.

Трансляция описания структуры дерева в язык программирования

C помощью действия translate производится трансляция описания структуры дерева и операций над ним в целевой язык программирования.

Имя	Описание
`treedl.translate.check.action`	Имя действия, которое будет вызвано для проверки семантической корректности описания дерева. Значение по умолчанию: check.
`treedl.translate.output.dir`	Каталог, относительно которого будут размещены сгенерированные файлы. Значение по умолчанию - текущий каталог.
`treedl.translate.update`	`true` - генерировать файл только в том случае, если он не существует или старее исходного TreeDL-файла. При любом другом значении этого свойства файлы будут генерироваться всегда. Значение по умолчанию - `true`.

Используемые свойства сущностей:

Сущность	Имя свойства	Описание
модуль	`treedl.language`	Целевой язык модуля. Значение по умолчанию: `code`. Значение по умолчанию означает, что модуль не нацелен на конкретный язык программирования.

Для трансляции в язык language, определенный свойством модуля treedl.language, используется подключаемый модуль трансляции с именем language_translate. Модули трансляции определены для следующих языков:

Язык	Описание
`java`	Язык программирования Java.
`java5`	Язык программирования Java. Используются возможности языка, появившиеся в версии 1.5
`csharp`	Язык программирования C#.

Модуль трансляции в язык программирования Java

При трансляции в язык программирования Java используются следующие системные свойства:

Имя свойства	Описание
`treedl.translate.smap.generate`	`true` - генерировать SMAP-файл, содержащий отображение номеров строк исходного TreeDL файла в номера строк сгенерированного Java файла. Значение по умолчанию: `false`

Используемые свойства сущностей:

Сущность	Имя свойства	Описание
модуль	`treedl.visitor`	Имя интерфейса визитера для модуля описания структуры дерева. Значение по умолчанию: `Module`_Visitor, где `Module` - полное имя модуля. Если задано пустое значение `""` этого свойства, поддержка визитеров не генерируется.
модуль	`translate.@node.class`	Имя класса, от которого будут унаследованы все типы вершин, для которых не задан базовый тип вершины. Если задано пустое значение `""` этого свойства, никакой базовый класс не используется. Значение по умолчанию - `com.unitesk.atp.tree.TreeClass.NodeClass`
тип вершины	`translate.@node.default.constructor`	`true` - генерировать конструктор без параметров. Значение по умолчанию - `false`.
атрибут или ребенок	`translate.@attribute.check.null`	`true` - генерировать проверку значения не optional атрибутов на `null`. Значение по умолчанию - `true`.
атрибут или ребенок	`translate.@attribute.check.setonce`	`true` - генерировать проверку однократной инициализации `setonce` атрибутов. Значение по умолчанию - `true`.
атрибут или ребенок	`translate.@attribute.check.size`	`true` - генерировать проверку количества элементов в списках для атрибутов, не допускающих пустые списки. Значение по умолчанию - `true`.
атрибут или ребенок	`translate.@attribute.@bool.is`	`true` - генерировать метод is`AttributeName` (синоним метода get`AttributeName`) для атрибутов типа `bool`. Значение по умолчанию - `true`.
атрибут или ребенок	`translate.@attribute.list.add`	`true` - генерировать add`AttributeName` метод для списков. Значение по умолчанию - `false`.
атрибут или ребенок	`translate.@attribute.list.remove`	`true` - генерировать remove`AttributeName` метод для списков. Значение по умолчанию - `false`.
атрибут или ребенок	`translate.@attribute.list.size`	`true` - генерировать size`AttributeName` метод для списков. Значение по умолчанию - `true`.
атрибут или ребенок	`translate.@attribute.list.get`	`true` - генерировать get`AttributeName`( int i ) метод для списков. Значение по умолчанию - `true`.
атрибут или ребенок	`translate.@attribute.list.min`	Генерировать проверку минимальной длины списка атрибутов. Значение по умолчанию определяется модификатором типа атрибута (`*` или `+`).
атрибут или ребенок	`translate.@attribute.list.max`	Генерировать проверку максимальной длины списка атрибутов. По умолчанию максимальная длина списка не ограничена.
перечислимый тип	`translate.@enum.check`	`true` - генерировать check`AttributeName` метод для перечислимых типов. Значение по умолчанию - `true`.
операция	`translate.@operation.public`	`true` - генерировать модификатор `public` для метода, реализующего операцию. Значение по умолчанию - `true`
операция	`translate.@operation.static`	`true` - генерировать модификатор `static` для метода, реализующего операцию. Значение по умолчанию - `true`

Свойство, указанное для модуля распространяется на всех членов соответствующего вида, определенных в этом модуле.

Модуль трансляции в язык программирования Java5

Модуль трансляции в язык программирования Java 5 использует те же самые системные свойства и свойства сущностей, что и модуль трансляции в Java.

Модуль трансляции в язык программирования C#

При трансляции в язык программирования Java используются следующие свойства сущностей:

Сущность	Имя свойства	Описание
модуль	`treedl.visitor`	Имя интерфейса визитера для модуля описания структуры дерева. Значение по умолчанию: `Module`_Visitor, где `Module` - полное имя модуля. Если задано пустое значение `""` этого свойства, поддержка визитеров не генерируется.
модуль	`translate.@node.class`	Имя класса, от которого будут унаследованы все типы вершин, для которых не задан базовый тип вершины. Если задано пустое значение `""` этого свойства, никакой базовый класс не используется. Значение по умолчанию - `com.unitesk.atp.tree.TreeClass.NodeClass`
тип вершины	`translate.@node.default.constructor`	`true` - генерировать конструктор без параметров. Значение по умолчанию - `false`.
атрибут или ребенок	`translate.@attribute.check.null`	`true` - генерировать проверку значения не optional атрибутов на `null`. Значение по умолчанию - `true`.
атрибут или ребенок	`translate.@attribute.check.setonce`	`true` - генерировать проверку однократной инициализации `setonce` атрибутов. Значение по умолчанию - `true`.
атрибут или ребенок	`translate.@attribute.check.size`	`true` - генерировать проверку количества элементов в списках для атрибутов, не допускающих пустые списки. Значение по умолчанию - `true`.
атрибут или ребенок	`translate.@attribute.list.min`	Генерировать проверку минимальной длины списка атрибутов. Значение по умолчанию определяется модификатором типа атрибута (`*` или `+`).
атрибут или ребенок	`translate.@attribute.list.max`	Генерировать проверку максимальной длины списка атрибутов. По умолчанию максимальная длина списка не ограничена.
перечислимый тип	`translate.@enum.check`	`true` - генерировать check`AttributeName` метод для перечислимых типов. Значение по умолчанию - `true`.
операция	`translate.@operation.public`	`true` - генерировать модификатор `public` для метода, реализующего операцию. Значение по умолчанию - `true`
операция	`translate.@operation.static`	`true` - генерировать модификатор `static` для метода, реализующего операцию. Значение по умолчанию - `true`

Генерация визитеров

Действие visitor реализует генерацию двух визитеров - пустого и копирующего дерево.

Используемые системные свойства:

Имя	Описание
`treedl.visitor.check.action`	Имя действия, которое будет вызвано для проверки семантической корректности описания дерева. Значение по умолчанию: check.
`treedl.visitor.output.dir`	Каталог, относительно которого будут размещены сгенерированные файлы. Значение по умолчанию - текущий каталог.
`treedl.visitor.update`	`true` - генерировать файл только в том случае, если он не существует или старее исходного TreeDL-файла. При любом другом значении этого свойства файлы будут генерироваться всегда. Значение по умолчанию - `true`.
`treedl.visitor.empty.name`	Имя пустого визитёра. Если не задано, этот визитёр не будет сгенерирован.
`treedl.visitor.copy.name`	Имя копирующего визитёра. Если не задано, этот визитёр не будет сгенерирован.

Для генерации визитеров на языке language, определенном свойством модуля treedl.language, используются подключаемые модули генерации с именами language_visitor_empty и language_visitor_copy. Модули генерации определены для следующих языков:

Язык	Описание
`java`	Язык программирования Java.
`java5`	Язык программирования Java. Используются возможности языка, появившиеся в версии 1.5
`csharp`	Язык программирования C#.

Генерация интерфейса и реализаций фабрик создания вершин

Действие factory реализует генерацию интерфейса и реализаций фабрик создания вершин.

Используемые системные свойства:

Имя	Описание
`treedl.factory.check.action`	Имя действия, которое будет вызвано для проверки семантической корректности описания дерева. Значение по умолчанию: check.
`treedl.factory.output.dir`	Каталог, относительно которого будут размещены сгенерированные файлы. Значение по умолчанию - текущий каталог.
`treedl.factory.update`	`true` - генерировать файл только в том случае, если он не существует или старее исходного TreeDL-файла. При любом другом значении этого свойства файлы будут генерироваться всегда. Значение по умолчанию - `true`.
`treedl.factory.interface.name`	Имя интерфейса фабрики создания вершин. Задание этого свойства обязательно.
`treedl.factory.null.name`	Имя реализации фабрики, которая всегда возвращает null вместо вершины. Если не задано - эта реализация фабрики не будет сгенерирована.
`treedl.factory.node.name`	Имя фабрики, которая создает вершину по заданным параметрам конструктора. Если не задано - эта реализация фабрики не будет сгенерирована.

Для генерации фабрик на языке language, определенном свойством модуля treedl.language, используются подключаемые модули генерации с именами language_factory_interface, language_factory_null и language_factory_node. Модули генерации определены для следующих языков:

Язык	Описание
`java`	Язык программирования Java.
`java5`	Язык программирования Java. Используются возможности языка, появившиеся в версии 1.5
`csharp`	Язык программирования C#.

Генерация обходчиков

Действие walker реализует генерацию обходчиков дерева.

Используемые системные свойства:

Имя	Описание
`treedl.walker.check.action`	Имя действия, которое будет вызвано для проверки семантической корректности описания дерева. Значение по умолчанию: check.
`treedl.walker.output.dir`	Каталог, относительно которого будут размещены сгенерированные файлы. Значение по умолчанию - текущий каталог.
`treedl.walker.update`	`true` - генерировать файл только в том случае, если он не существует или старее исходного TreeDL-файла. При любом другом значении этого свойства файлы будут генерироваться всегда. Значение по умолчанию - `true`.
`treedl.walker.depth_first.name`	Имя обходчика. Если не задано - обходчик не будет сгенерирован.

Для генерации обходчиков на языке language, определенном свойством модуля treedl.language, используется подключаемый модуль генерации с именем language_walker_depth_first. Модули генерации определены для следующих языков:

Язык	Описание
`java`	Язык программирования Java.
`java5`	Язык программирования Java. Используются возможности языка, появившиеся в версии 1.5
`csharp`	Язык программирования C#.

Генерация шаблонов сообщений для библиотеки atplib-3.x.x

Действие messages реализует генерацию ресурсов, содержащих шаблоны сообщений. Обработка сообщения производится библиотекой atplib-3.x.x.

Используемые системные свойства:

Имя	Описание
`treedl.messages.check.action`	Имя действия, которое будет вызвано для проверки семантической корректности описания дерева. Значение по умолчанию: check.
`treedl.messages.output.dir`	Каталог, относительно которого будут размещены сгенерированные файлы. Значение по умолчанию - текущий каталог.
`treedl.messages.update`	`true` - генерировать файл только в том случае, если он не существует или старее исходного TreeDL-файла. При любом другом значении этого свойства файлы будут генерироваться всегда. Значение по умолчанию - `true`.

Используемые свойства сущностей:

Сущность	Имя свойства	Описание
модуль	`messages.mbox.class`	Класс MessageBox, для которого будут сгенерированы файлы с шаблонами сообщений.
тип вершины	`messages.group`	Группа, к которой относится данный класс сообщения.
тип вершины	`messages.pattern[.locale]`	Шаблон сообщения. `locale` - необязательная часть имени свойства, определяющая локализацию сообщения. Могут быть указаны несколько свойств, различающиеся локализацией.

Для типа вершин Message, представляющего тип сообщения, генерируется файл Message.properties[_locale], содержащий свойство, имя которого задается свойством модуля messages.mbox.class, а значение задается соответствующим свойством messages.pattern[.locale] типа вершины с префиксом из имени группы сообщений (задается свойством типа вершины messages.group) и порядковым номером сообщения в группе. Порядковый номер сообщения в группе вычисляется автоматически.

Генерация шаблонов сообщений для библиотеки atplib-4.x.x

Действие messages2 реализует генерацию ресурсов, содержащих шаблоны сообщений. Обработка сообщения производится библиотекой atplib-4.x.x.

Используемые системные свойства:

Имя	Описание
`treedl.messages2.check.action`	Имя действия, которое будет вызвано для проверки семантической корректности описания дерева. Значение по умолчанию: check.
`treedl.messages2.output.dir`	Каталог, относительно которого будут размещены сгенерированные файлы. Значение по умолчанию - текущий каталог.
`treedl.messages2.update`	`true` - генерировать файл только в том случае, если он не существует или старее исходного TreeDL-файла. При любом другом значении этого свойства файлы будут генерироваться всегда. Значение по умолчанию - `true`.

Используемые свойства сущностей:

Сущность	Имя свойства	Описание
модуль	`messages2.suffix`	Класс MessageBox, для которого будут сгенерированы файлы с шаблонами сообщений.
тип вершины	`messages2.pattern[.locale[.suffix]]`	Шаблон сообщения. `locale` - необязательная часть имени свойства, определяющая локализацию сообщения. Могут быть указаны несколько свойств, различающиеся локализацией. Для каждой указанной локализации может быть определено несколько свойств с различными суффиксами.

Для модуля описания Messages, содержащего типы сообщений, генерируется файл Messages.properties[_locale], содержащий свойства с именами MessageClass/suffix и значениями, которые задаются соответствующими свойствами messages2.pattern[.locale[.suffix]] типа вершины.

Отладочный вывод внутреннего представления описания структуры дерева

Действие dump реализует отладочный вывод внутреннего представления описания структуры дерева.

Используемые системные свойства:

Имя	Описание
`treedl.dump.output.file`	Файл, в который будет помещен отладочный вывод внутреннего представления описания структуры дерева. Значение по умолчанию - `input_file_name.dump`, где `input_file_name` - имя входного файла.
`treedl.dump.indent.step`	Шаг отступа. Значение по умолчанию - 4.

Appendix 1. История изменений

2.3.1

добавлено: действие messages2
исправлено: восстановление парсера после ошибок
исправено: обработка ошибок чекером
обход ошибки в обработке свойства user.dir
входной файл закрывается после обработки
Значение по умолчанию свойства treedl.translate.smap.generate изменено на false.

2.3.0

добавлено: генерация на языке C#;
добавлено: целевой язык модуля может быть задан не только как свойство модуля, но и как системное свойство treedl.language;
добавлено: свойство модуля treedl.version;
добавлено: свойства сущностей translate.@attribute.@bool.is, translate.@attribute.list.remove, translate.@attribute.list.min, translate.@attribute.list.max;
добавлено: поддержка изменений языка версии 2.3.