Previous

Next

Chapter 10 Using Tom

10.1 The Tom compiler

The Tom compiler is a non-intrusive pattern matching compiler. It takes a Tom program, combination of a host programming language (Java, C or Caml) extended by Tom constructs. Each Tom program can define its own data structures and manipulate them in order to write pattern-matching based algorithms.

10.2 Development process

As mentioned earlier, Tom generates host language code. The command tom invokes the compiler on a Tom source file and generates a new source file (with .java, .tom.c, or .tom.ml extension, depending on the compilation command-line). The generated code has to be compiled/interpreted by a tool which can handle the corresponding host language: javac for Java, cc for C and ocamlc for Caml.

A typical development cycle is the following:

edit a Tom program (by convention, a Tom source code has the .t extension)
run the Tom compiler on this file
compile the generated file (javac file.java, or cc file.tom.c,...)
execute the program (java file, or a.out,...)

As cc and javac, tom can compile several input files. By default, the generated files are saved in the same directory as the corresponding input files. When compiling a Java file (i.e. a Tom file where Java is the host language), Tom is smart enough to parse the package definition and generate the pure-Java file in the same package architecture. Similarly to javac, tom supports a -d option which allows the user to indicate where the files have to be generated. To be compatible with cc and classical Makefile, Tom also supports a -o option which can be used to specify the name of the generated file.

Note: Windows users can use the provided shell script javacForTom.bat in order to compile the java files that are generated by Tom. Another script, javaForTom.bat can be used to execute the java bytecode. We recommend the use of these scripts since they update the CLASSPATH according to the '*.jar' files that are in the distribution.

10.3 Command line tool

tom [options] filename[.t]

The command takes only one file argument, the name of the input file to be compiled. By convention the input file name is expected to be of the form filename.t, whatever the used host language is.

Options:

-X <file> Define an alternate XML configuration file

Allow to define the plugins instantiated by the Tom platform

--cCode | -c Generate C code (default is Java)

The output file has the extension .tom.c

--camlCode Generate Caml code (default is Java)

--camlSemantics Verify with caml semantics for match)

--compile Activate the compiler (by default)

--destdir | -d Specify where to place generated files.

By default, Tom generates files close to the input file. However (like javac), this option allows to specify a directory where generated files have to be put. When compiling a Java file, Tom is smart enough to parse the package definition and generate the pure-Java file in the same package architecture.

--eclipse Activate Eclipse mode

--encoding <charset> | -e Specify the character encoding

--expand Activate the expander (by default)

--help | -h Show the help

Give a brief description of each available options

--import <path> | -I Path to included files

Even if inclusion can be performed using relative path, this option specifies list of path where Tom look for when an inclusion has to be done by %include construct

--intermediate | -i Generate intermediate files

The compiler manipulates Abstract Syntax Trees. This option dumps the AST after each phase (parsing, checking, expansion, compilation) This option is useful to analyze the compilation process

--jCode | -j Generate Java code (by default)

--lazyType | -l Use universal type

This option makes Tom using a less restrictive backend. In Java, the universal sort Object is used more often. This reduces static typing but allows to manipulate inherited data-structures

--noDeclaration | -D Do not generate code for declarations

Avoid multiple declaration of symbols when structures are inherited or when multiple inclusion of common data structures are performed

--noOutput Do not generate code

No output file is generated. It allows to see warnings and errors without generating the result

--noReduce Do not simplify extracted constraints (depends on –verify)

--noStatic Generate non static functions

--noSyntaxCheck Do not perform syntax checking

--noTypeCheck Do not perform type checking

--optimize | -O Optimize generated code

Add an optimization phase to the compilation process. This removes unused variables and performs some inlining.

--optimize2 | -O2 Further optimize generated code (does not imply -O)

--output | -o Set output file name

By default, Tom infers the name of the generated file by replacing the initial file extension by .java, .tom.c or .tom.ml, depending on the chosen target language. This option allows to explicitly give the name of the generated file.

--pCode Generate Python code

--parse Activate the parser (by default)

--pretty | -p Generate readable code with indentation

By default, the generated code is synchronized with the source code. This simplifies error reporting but makes the code more difficult to read. This option beautifies the generated code.

--prettyPIL | -pil Prettyprint the intermediate language

--protected Generate protected functions

In Java, this option forces the generation of protected functions, instead of private ones, for symbol manipulation functions

--verbose | -v Set verbose mode on

Give duration information about each compilation passes

--verify Verify correctness of match compilation

--version | -V Print the version of Tom

--wall Print all warnings

Useful in debugging phase

10.4 Ant task

Tom provides an ant task for running the Tom compiler within the apache ant build system.

The Tom ant task is very close in use to the javac ant task. Since this task is not part of the official ant tasks, you have first to declare this task in your buildfile, in order to use it.

This is done by the following code:

<taskdef name="tom" classname="tom.engine.tools.ant.TomTask"> <classpath refid="tom.classpath"/> </taskdef>

where tom.classpath is a path reference containing all the jar's in Tom's distribution.

This task is used to produce Java code from Tom programs. A typical use of the tom ant task is:

<tom config="${stable.configfile}" srcdir="${src.src}" destdir="${src.gen}" options="-I ${src.mapping}"> <include name="**/*.t"/> </tom>

Here, we want to compile all Tom source files in {src.src}, having the generated code in {src.gen}, and we configure the compiler to use the {stable.configfile} config file, and pass the options we want, just as we do for Tom in command line.

Another use of this task is:

<tom config="${stable.configfile}" srcdir="${src.src}" outputfile="${src.gen}/tom/engine/parser/TomLanguage.g" options="-I ${src.mapping} -I ${src.gen}/tom/engine/adt"> <include name="**/TomLanguage.g.t"/> </tom>

Here we compile only one Tom file, and specify directly the output file name we want to use.

The main usecases for the Tom ant task can be found in Tom's own buildfile.

The Tom ant task takes the following arguments:

Attribute	Description	Required
srcdir	Location of the Tom files.	Yes, unless nested `<src>` elements are present
destdir	Location of the java files.	No
outputfile	Destination file to compile the source. This require to have only one source file.	No
config	Location of the Tom configuration file.	No
logfile	Which log file to use.	No
optimize	Indicates whether source should be compiled with optimization; defaults to `off`	No
stamp	Indicates whether the generated code should use stamps or not, to simulate concrete ADT. Defaults to `false`	No
failonerror	Indicates whether the build will continue even if there are compilation errors; defaults to `true`	No
options	Custom options to pass to the Tom compiler	No
verbose	Asks the compiler for verbose output; defaults to `no`	No
pretty	Asks the compiler to generate more human readable code; defaults to `no`	No
nowarn	Asks the compiler not to report all warnings; defaults to `no`	No
classpath	The classpath to use, given as a reference to a path defined elsewhere. This variable is not used currently.	No

Previous

Next