Chapter 15  Using Tom

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

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

15.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:

---

--config | -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)
--csCode	Generate C# code
--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)
--genIntrospector | -gi	Generate a class that implements Introspector to apply strategies on non visitable terms
--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
--inline	Inline mapping
--inlineplus	Force inlining, even if no $ is used
--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
--type	Typer (activated by default)
--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

---

15.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 the path reference containing all the jar’s in Tom’s distribution predefined in the file ${TOM_HOME}/lib/tom-common.xml.

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

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

Here, we want to compile all Tom source files in {src.dir}, having the generated code in {gen.dir}, and we configure the compiler to use the {tom.configfile} config file, and pass the options we want like, for example {-I} to indicate the mapping needed for compilation, just as we do for Tom in command line.

Another use of this task is:

<tom config="${tom.configfile}"
     srcdir="${src.dir}"
     outputfile="${gen.dir}/Example.java"
     options="-I ${mapping.dir}">
  <include name="**/Example.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: