Documentation:Using Tom

From Tom

Jump to: navigation, search
Doc : Tools

Installation  > Compiling from sources  > Using Tom  > Using Gom  > Configuring your environment  > Tom Server  > EMF Mapping Generator

Contents

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, Caml or Ada) extended by Tom constructs. Each Tom program can define its own data structures and manipulate them in order to write pattern-matching based algorithms.

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, .tom.ml, or .adb 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, ocamlc for Caml and gnatmake for Ada.

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: Only if a manual installation was performed (without using the kit), 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. If you used the install kit, the CLASSPATH was updated accordingly at the install time.

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:


--aCode | -a Generate Ada code (default is Java)
--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)
--config | -X <file> Define an alternate XML configuration file
Allow to define the plugins instantiated by the Tom platform
--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
--multithread | -mt Sets the multithread mode
--newTyper | -nt New TyperPlugin (not activated by default)
This option allows to activate the new typer instead of the older. Note that subtyping has been included in Tom since 2.9 release.
--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
--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 <file>| -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
--version | -V Print the version of Tom
--wall | -W Print all warnings
Useful in debugging phase

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 and the distributed examples.

The Tom ant task takes the following arguments:

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

Installation  > Compiling from sources  > Using Tom  > Using Gom  > Configuring your environment  > Tom Server  > EMF Mapping Generator

Tom Documentation
Guided Tour :: Tutorial :: Language Reference :: Tools
Personal tools
Create a book