TreeDL: User's guide

TreeDL tool's purpose is the processing of tree structure description. The tool checks syntax and semantic correctness of tree structure description, generates HTML representation with cross-references, and translates tree structure description to target programming language. Additional actions on tree structure description can be implemented as plugins.

Chapter 2. System Requirements

Java Runtime Environment 1.4 or newer. Sun JRE 1.4.2 or newer is recommended (http://java.sun.com).

Chapter 3. Installation

The tool is distributed as a single archive treedl-<version>-<status>-<date>-standalone.zip. Here <version> is tool's version, <status> - status of release (alpha, beta, stable и т.п.), and <date> is release date. Unzipping of this file creates dirrectory treedl-<version>-<status>-<date> with the following subdirectories:

bin/ - executable files treedl.exe (Intel x86, Win32) and treedl (*nix shell script)

docs/ - documentation

lib/ - libraries

src/ - sources

Chapter 4. Command line

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

jvmoption - parameters passed to java virtual machine (JVM);

file - file for processing;

action - actions that will be sequentially executed over the given file. If no actions specified, only syntax correctness will be checked.

Example:

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

The parameter -Dtreedl.properties.file=TreeDL.tdl.properties will be passed to JVM, actions check translate xref will be sequentially executed over TreeDL.tdl file.

The tool started without parameters shows the description of command line. Additional information about plugins is shown when tool is started with minus sign instead of file name:

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

If plugin names plugin are not specified, the tools shows the list of names of available plugins including actions.

If plugin names are specified, the description of each of these plugins is shown.

Chapter 5. Configuration

TreeDL tool uses the following system properites:

Property name	Description
`treedl.properties.file`	Name of configuration file name. First, the tool searches for the resource with this name, then for file with this name. The file has standard properties file format. The default value is `treedl.properties`
`treedl.plugins.file`	Name of plugins configuration file. First, the tool searches for the resource with this name, then for file with this name. The file has standard properties file format. The default value is `treedl.plugins`
`treedl.mbox.class`	Name of message box class. By default error messages are printed to standard error stream. The default value is `com.unitesk.atp.messages.PrintStreamMessageBox`
`treedl.language`	Target language of module. This property used only for modules where module property `treedl.language` is not specified.

A value of treedl.properties.file property can be specified only in command line, values of other properties can be specified in command line or in configuration file.

Properties file format is described in Sun JDK documentation for method load( java.io.InputStream ) of class java.lang.Properties.

treedl tool of version LL.ll.TT.tt supports TreeDL language of versions LL.0-LL.ll. TreeDL language version is specified by the following module property:

Entity	Property name	Description
module	`treedl.version`	TreeDL language version in form of `LL.ll`.

Chapter 6. Plugins

Table of Contents

Semantic checking of tree structure description

Generation of HTML representation with cross-references

Translation of tree description to target programming language

Translation plugin for Java programming language
Translation plugin for Java 5 programming language
Translation plugin for C# programming language

Generation of empty and copy visitors

Generation of interface and implementations of node factories

Generation of tree walkers

Generation of message format files for atplib-3.x.x

Generation of message format files for atplib-4.x.x

Debugging output of internal represenation of input tree description

The most of tool's functionality is implemented by plugins. Available plugins are listed in plugins configuration file specified by treedl.plugins.file property. A plugin with name <plugin> can use system properties named treedl.<plugin>.<property>. And plugin can use declarative information from tree structure description.

Some plugins implement actions. Names of action plugins can be used in command line of tool. Actions included in tool's distribution are listed below:

Action	Description
`check`	the section called “Semantic checking of tree structure description”
`xref`	the section called “Generation of HTML representation with cross-references”
`translate`	the section called “Translation of tree description to target programming language”
`visitor`	the section called “Generation of empty and copy visitors”
`factory`	the section called “Generation of interface and implementations of node factories”
`walker`	the section called “Generation of tree walkers”
`messages`	the section called “Generation of message format files for atplib-3.x.x”
`messages2`	the section called “Generation of message format files for atplib-3.x.x”
`dump`	the section called “Debugging output of internal represenation of input tree description”

Semantic checking of tree structure description

Semantic checking of tree structure description is performed by check action. Checked semantic restrictions are described in "TreeDL: Tree Description Language" document.

Used system properties:

Property name	Description
`treedl.check.source.path`	Path to search for TreeDL files with base modules. Base module with full name `<QID>` searched in file `<PQID>``.tdl` (`<PQID>` is `<QID>` where `'.'` are replaced by `'/'`) relative to one of directories of path `treedl.check.source.path`, then searched relative to the current directory, then in resources.

Used entity properties:

Entity	Property name	Description
module	`treedl.language`	Target language of module. The default value is `code`. Default value means that module is not targeted to any particular language.

Generation of HTML representation with cross-references

HTML representation of semantically correct input tree structure description is generated by xref action. Type declarations and usages are cross-referenced. This HTML representatino can be used as documentation.

Used system properties:

Property name	Description
`treedl.xref.check.action`	Name of an action that is used for semantic checking of input tree structure description. The default value is check.
`treedl.xref.links.file`	Name of a file with map from base module names and URLs of directories where their HTML represenations are stored. The file has standard properties file format. Property name is full name of base module. Property value is URL of directory where HTML represenation of this module is stored. The default value is `treedl.xref.links`
`treedl.xref.output.dir`	Output directory for generated files. The default value is the current directory.
`treedl.xref.update`	If `true` then file will be generated only if it does not exist or older than input TreeDL file. Otherwise file will be generated unconditionally. The default value is `true`.

Translation of tree description to target programming language

Translation of semantically correct input tree description to target programming language is performed by translate action.

Property name	Description
`treedl.translate.check.action`	Name of an action that is used for semantic checking of input tree structure description. The default value is check.
`treedl.translate.output.dir`	Output directory for generated files. The default value is the current directory.
`treedl.translate.update`	If `true` then file will be generated only if it does not exist or older than input TreeDL file. Otherwise file will be generated unconditionally. The default value is `true`.

Used entity properties:

Entity	Property name	Description
module	`treedl.language`	Target language of module. The default value is `code`. Default value means that module is not targeted to any particular language.

Translation to language language defined by module property treedl.language is implemented by translation plugin with name language_translate. There are translation plugins for the following languages:

Language	Description
`java`	Java programming language
`java5`	Java programming language with new features introduced by JDK 1.5 (Java 5)
csharp	C# programming language

Translation plugin for Java programming language

Java translation plugin uses the following system properties:

Property name	Description
`treedl.translate.smap.generate`	If `true` then SMAP-file with line mapping of line numbers from input TreeDL file to generated Java file will be generated. The default value is `false`

Used entity properties:

Entity	Property name	Description
module	`treedl.visitor`	Visitor interface name for structure description module. The default value is `Module`_Visitor where `Module` is the full name of module. If empty value `""` is used, visitor support is not generated.
module	`translate.@node.class`	Name of super class for all classes generated from node types that don't specify base node type. If empty value `""` is used, no extends-clause is generated. The default value is `com.unitesk.atp.tree.TreeClass.NodeClass`
node type	`translate.@node.default.constructor`	If `true` then constructor without parameters will be generated. Default value is `false`.
attribute or child	`translate.@attribute.check.null`	If `true` then generate check for null value of non-optional attributes. Default value is `true`.
attribute or child	`translate.@attribute.check.setonce`	If `true` then generate check for one-time initialization of setonce attributes. Default value is `true`.
attribute or child	`translate.@attribute.check.size`	If `true` then generate check for zero list size for list attributes not allowing empty lists. Default value is `true`.
attribute or child	`translate.@attribute.@bool.is`	If `true` then generate is`AttributeName` method (synonym of get`AttributeName`) for attributes of `bool` type. Default value is `true`.
attribute or child	`translate.@attribute.list.add`	If `true` then add`AttributeName` method will be generated for list attributes. Default value is `false`.
attribute or child	`translate.@attribute.list.remove`	If `true` then r`emoveAttributeName` method will be generated for list attributes. Default value is `false`.
attribute or child	`translate.@attribute.list.size`	If `true` then size`AttributeName` method will be generated for list attributes. Default value is `true`.
attribute or child	`translate.@attribute.list.get`	If `true` then get`AttributeName`( int i ) method will be generated for list attributes. Default value is `true`.
attribute or child	`translate.@attribute.list.min`	Generate check of minimum size of list attribute. By default minimum size is defined by type modifiers (`*` or `+`).
attribute or child	`translate.@attribute.list.max`	Generate check of maximum size of list attribute. By default maximum size of list attribute is not limited.
enum type	`translate.@enum.check`	If `true` then генерировать check`AttributeName` метод для перечислимых типов. Default value is `true`.
operation	`translate.@operation.public`	If `true` then `public` modifier will be generated for a method that implements operation. The default value is `true`
operation	`translate.@operation.static`	If `true` then `static` modifier will be generated for a method that implements operation. The default value is `true`

Properties specified for module affect all members of that module.

Translation plugin for Java 5 programming language

Translation plugin for the Java 5 programming language uses the same system properties and entity properties as the section called “Translation plugin for Java programming language”.

Translation plugin for C# programming language

C# translation plugin uses the following entity properties:

Entity	Property name	Description
module	`treedl.visitor`	Visitor interface name for structure description module. The default value is `Module`_Visitor where `Module` is the full name of module. If empty value `""` is used, visitor support is not generated.
module	`translate.@node.class`	Name of super class for all classes generated from node types that don't specify base node type. If empty value `""` is used, no extends-clause is generated. The default value is `com.unitesk.atp.tree.TreeClass.NodeClass`
node type	`translate.@node.default.constructor`	If `true` then constructor without parameters will be generated. Default value is `false`.
attribute or child	`translate.@attribute.check.null`	If `true` then generate check for null value of non-optional attributes. Default value is `true`.
attribute or child	`translate.@attribute.check.setonce`	If `true` then generate check for one-time initialization of setonce attributes. Default value is `true`.
attribute or child	`translate.@attribute.check.size`	If `true` then generate check for zero list size for list attributes not allowing empty lists. Default value is `true`.
attribute or child	`translate.@attribute.list.min`	Generate check of minimum size of list attribute. By default minimum size is defined by type modifiers (`*` or `+`).
attribute or child	`translate.@attribute.list.max`	Generate check of maximum size of list attribute. By default maximum size of list attribute is not limited.
enum type	`translate.@enum.check`	If `true` then генерировать check`AttributeName` метод для перечислимых типов. Default value is `true`.
operation	`translate.@operation.public`	If `true` then `public` modifier will be generated for a method that implements operation. The default value is `true`
operation	`translate.@operation.static`	If `true` then `static` modifier will be generated for a method that implements operation. The default value is `true`

Properties specified for module affect all members of that module.

Generation of empty and copy visitors

Generation of empty and copy visitors is implemented by visitor action.

Used system properties:

Property name	Description
`treedl.visitor.check.action`	Name of an action that is used for semantic checking of input tree structure description. The default value is check.
`treedl.visitor.output.dir`	Output directory for generated files. The default value is the current directory.
`treedl.visitor.update`	If `true` then file will be generated only if it does not exist or older than input TreeDL file. Otherwise file will be generated unconditionally. The default value is `true`.
`treedl.visitor.empty.name`	Name of empty visitor. If not specified then empty visitor is not generated.
`treedl.visitor.copy.name`	Name of copy visitor. If not specified then copy visitor is not generated.

Generation of visitors in language language defined by module property treedl.language is implemented by generation plugins with name language_visitor_empty and language_visitor_copy. There are generation plugins for the following languages:

Language	Description
`java`	Java programming language
`java5`	Java programming language with new features introduced by JDK 1.5 (Java 5)
`charp`	C# programming language

Generation of interface and implementations of node factories

Generation of interface and implementations of node factories is implemented by factory action.

Used system properties:

Property name	Description
`treedl.factory.check.action`	Name of an action that is used for semantic checking of input tree structure description. The default value is check.
`treedl.factory.output.dir`	Output directory for generated files. The default value is the current directory.
`treedl.factory.update`	If `true` then file will be generated only if it does not exist or older than input TreeDL file. Otherwise file will be generated unconditionally. The default value is `true`.
`treedl.factory.interface.name`	Name of interface of node factory. If this property is not specified nothing is generated by this action.
`treedl.factory.null.name`	Name of implementation of node factory that returns `null` instead of nodes. If this property is not specified, this factory implementation is not generated.
`treedl.factory.node.name`	Name of implementation of node factory that actually returns nodes. If this property is not specified, this factory implementation is not generated.

Generation of factories in language language defined by module property treedl.language is implemented by generation plugins with name language_factory_interface, language_factory_null, and language_factory_node. There are generation plugins for the following languages:

Language	Description
`java`	Java programming language
`java5`	Java programming language with new features introduced by JDK 1.5 (Java 5)
`charp`	C# programming language

Generation of tree walkers

Generation of tree walkers is implemented by walker action.

Used system properties:

Property name	Description
`treedl.walker.check.action`	Name of an action that is used for semantic checking of input tree structure description. The default value is check.
`treedl.walker.output.dir`	Output directory for generated files. The default value is the current directory.
`treedl.walker.update`	If `true` then file will be generated only if it does not exist or older than input TreeDL file. Otherwise file will be generated unconditionally. The default value is `true`.
`treedl.walker.depth_first.name`	Name of depth-first tree walker. If this name is not specified then depth-first tree walker is not generated.

Generation of walkers in language language defined by module property treedl.language is implemented by generation plugin with name language_walker_depth_first. There are generation plugins for the following languages:

Language	Description
`java`	Java programming language
`java5`	Java programming language with new features introduced by JDK 1.5 (Java 5)
`charp`	C# programming language

Generation of message format files for atplib-3.x.x

Generation of resource files that contain message format patterns is implemented by messages action. Message processing is implemented by atplib-3.x.x library.

Used system properties:

Property name	Description
`treedl.messages.check.action`	Name of an action that is used for semantic checking of input tree structure description. The default value is check.
`treedl.messages.output.dir`	Output directory for generated files. The default value is the current directory.
`treedl.messages.update`	If `true` then file will be generated only if it does not exist or older than input TreeDL file. Otherwise file will be generated unconditionally. The default value is `true`.

Used entity properties:

Entity	Property name	Description
module	`messages.mbox.class`	Name of message box class which message patterns are generated for.
node type	`messages.group`	Group of message class.
node type	`messages.pattern[.locale]`	Message pattern. `locale` is optional part of property name that specifies locale. There can be defined several properties with different locales.

For node type Message that represent message class, resource files Message.properties[_locale] are generated for each locale. These files contain property with name specified by module property messages.mbox.class, and value specified by property messages.pattern[.locale] for corresponding locale, prefixed by message group and number of message in group. Message group is specified by property messages.group. Message number is calculated automatically.

Generation of message format files for atplib-4.x.x

Generation of resource files that contain message format patterns is implemented by messages action. Message processing is implemented by atplib-4.x.x library.

Used system properties:

Property name	Description
`treedl.messages2.check.action`	Name of an action that is used for semantic checking of input tree structure description. The default value is check.
`treedl.messages2.output.dir`	Output directory for generated files. The default value is the current directory.
`treedl.messages2.update`	If `true` then file will be generated only if it does not exist or older than input TreeDL file. Otherwise file will be generated unconditionally. The default value is `true`.

Used entity properties:

Entity	Property name	Description
module	`messages2.suffix`	Name of default property suffix which message patterns are generated for.
node type	`messages2.pattern[.locale[.suffix]]`	Message pattern. `locale` is optional part of property name that specifies locale. There can be defined several properties with different locales. For each specified locale can be defined several properties for different suffixes.

For tree description module Messages that encloses message classes, resource file Messages.properties[_locale] are generated for each locale. This file contains properties with name MessageClass/suffix, and value specified by property messages2.pattern[.locale[.suffix]] for corresponding locale.

Debugging output of internal represenation of input tree description

Debug dump of internal representation of input tree is implemented by dump action.

Used system properties:

Property name	Description
`treedl.dump.output.file`	Output file name. The default value is `input_file_name.dump`, where `input_file_name` is name of input file.
`treedl.dump.indent.step`	Indent step. The default value is 4.

Appendix 1. History of changes

2.3.1

add: messages2 action
fixed parser error recovery
checker error handling
workaround for bug with user.dir property
close input file after parsing
default value of treedl.translate.smap.generate property changed to false.

2.3.0

add: C# generation;
add: target language of module can be specified not only as module property, but as system property treedl.language;
add: module property treedl.version;
add: entity properties translate.@attribute.@bool.is, translate.@attribute.list.remove, translate.@attribute.list.min, translate.@attribute.list.max;
add: language changes of version 2.3.