TreeDL: User's guide


Table of Contents

1. Purpose
2. System Requirements
3. Installation
4. Command line
5. Configuration
6. Plugins
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
1. History of changes

Chapter 1. Purpose

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

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:

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 isAttributeName method (synonym of getAttributeName) for attributes of bool type. Default value is true.
attribute or child translate.@attribute.list.add If true then addAttributeName method will be generated for list attributes. Default value is false.
attribute or child translate.@attribute.list.remove If true then removeAttributeName method will be generated for list attributes. Default value is false.
attribute or child translate.@attribute.list.size If true then sizeAttributeName method will be generated for list attributes. Default value is true.
attribute or child translate.@attribute.list.get If true then getAttributeName( 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 checkAttributeName . 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 checkAttributeName . 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.