View source

{{FAQ_header}}

==General==
===Under which license is {{tom}} available?===
{{tom}} is [http://www.opensource.org/docs/definition.html open source] software, and the license is such that it is possible to redistribute all code generated by {{tom}} with no restrictions.
Any user of {{tom}} is allowed to distribute the files generated by {{tom}} under the license he prefers. However, the core of the compiler itself is distributed under the [http://www.opensource.org/licenses/gpl-2.0.php GNU General Public License].

The general licensing scheme is described [[Licensing_conditions#General_licensing_scheme|here]], and all licensing information is detailed in the [[Licensing_conditions]] document.

===How can I install {{tom}}?===
Everything is explained in the [[Documentation:Installation|installation guide]].

===Can I distribute an application written in {{tom}}?===
Yes, the generated code and the runtime library is free. See [[Licensing_conditions]] for more details.

===What runtime is needed to run an application written in {{tom}}?===
To make things simple, we provide a <code>tom-runtime-full.jar</code> library that contains everything that could be needed.
If you do not care about the size of the runtime library, just distribute your application with this library.

If you want, you can also have a finer control by selecting only the parts of the runtime library that are needed by your application:
* there are some situations where no runtime is needed, in particular when using {{tom}} in C mode, or when only pattern matching is used (on user defined data-structures),
* when using more advanced features,  such as strategies, <code>tom-runtime.jar</code> is needed,
* when using {{gom}}, <code>aterm.jar</code>, <code>jjtraveler.jar</code>, and <code>shared-objects.jar</code> are needed,
* when using {{xml}} syntax in {{tom}}, <code>xercesImpl.jar</code> and <code>xml-apis.jar</code> become needed,
* when using graphical visualization of terms, <code>grappa1_2.jar</code> is needed.

The following instructions may help you to build a more tailored classpath:
 (sh)
   TOM_LIB_RUNTIME=`echo ${TOM_HOME}/lib/runtime/*.jar | tr ' ' ':'`
   TOM_LIB_TOOLS=`echo ${TOM_HOME}/lib/tools/*.jar | tr ' ' ':'`
   export CLASSPATH=.:$TOM_LIB_RUNTIME:$TOM_LIB_TOOLS:$CLASSPATH

 (bash)
  for i in "${TOM_HOME}"/lib/runtime/*.jar
  do
    TOM_LIB_RUNTIME="$TOM_LIB_RUNTIME:$i"
  done
  for i in "${TOM_HOME}"/lib/tools/*.jar
  do
    TOM_LIB_TOOLS="$TOM_LIB_TOOLS:$i"
  done
  export CLASSPATH=.:${TOM_LIB_TOOLS}:${TOM_LIB_TOOLS}${CLASSPATH}

 (csh)
   set TOM_LIB_RUNTIME=`echo ${TOM_HOME}/lib/runtime/*.jar | tr ' ' ':'`
   set TOM_LIB_TOOLS=`echo ${TOM_HOME}/lib/tools/*.jar | tr ' ' ':'`
   setenv CLASSPATH .:$TOM_LIB_RUNTIME:$TOM_LIB_TOOLS:$CLASSPATH


===Can I use the latest cutting edge version?===
Yes, but you have to [[Documentation:Compiling_trunk|compile the compiler]] yourself.

===How can I complain about {{tom}}?===
You can submit a bug report on the [http://gforge.inria.fr/tracker/?group_id=78 forge], or drop a mail on the [http://websympa.loria.fr/wwsympa/subrequest/tom-users tom-users] mailing list.

==The {{tom}} language==
===Is associative-commutative (AC) matching supported?===
Yes Tom supports AC matching since the version 2.8. To use Tom AC, you have to activate it in your gom code.

===How to model sorts and subsorts?===
We are currently designing and implementing an extension that supports subsorts. 
see [[Documentation:Tom#Sort_and_subsort_definition_constructs|Sorts and subsorts]] for more details.

==Technical==

===How to visualize a term?===
In addition to the standard textual representation there is a [[Documentation:Runtime_Library#Term_viewer|library]].
Just call 
* <code>tom.library.utils.Viewer.toDot(term)</code> ([http://www.graphviz.org/ DOT] representation)
* <code>tom.library.utils.Viewer.toTree(term)</code> (tree-based ascii representation)
* <code>tom.library.utils.Viewer.display(term)</code> (direct graphical visualization in a JFrame).

It can be used with terms and term-graphs (terms with pointers).

[[Image:TermVisualization1.jpg]][[Image:TermVisualization2.jpg]]

===Can I add Java code to generated {{gom}} classes?===
Yes, using the [[Documentation:Gom#Hooks_to_alter_the_generated_API|<code>:block {}</code> hook]].

===How to share a strategy between different files?===
Be sure to use a recent version of {{tom}} such that generated creation functions are <tt>public</tt> instead of <tt>private</tt>.

Assume you define a strategy <tt>R()</tt>:
<source lang="tom">
import term.types.*;
class Test {
  %include { term/Term.tom}
  %include { sl.tom }
  %strategy R() extends Fail() {
    visit Term {
      a() -> b()
    }
  }
}
</source>
If you want to use <tt>R()</tt> in another file, you just have to create a simple mapping:
<source lang="tom">
%op Strategy R() {
  make() { new Test.R() }
}
</source>

Then, you can use <tt>`R()</tt> as usual (don't forget to import sl: <tt>%include { sl.tom }</tt>):
<source lang="tom">
import term.types.*;
import tom.library.sl.*;
public class Main {
  %include { term/Term.tom }
  %include { sl.tom }
  %op Strategy R() {
    make() { new Test.R() }
  }
  public final static void main(String[] args) {
    Term t = `a();
    try {
      System.out.println(`R().visit(t));
    } catch(VisitFailure e) {
      System.out.println("failure");
    }
  }
}
</source>

===How to use constants in a pattern?===
A solution is to pass the constant as another parameter in the <code>%match</code> construct, and use non-linear patterns to check the constant.

<source lang="tom">
%match(t, `Constant()) {
  f(x,y), x -> { System.out.println("Constant found as first child"); }
  f(x,y), y -> { System.out.println("Constant found as second child"); }
}
</source>

Which is equivalent to the following constraint-based version.

<source lang="tom">
%match(t) {
  f(x,y) && x << `Constant() -> { System.out.println("Constant found as first child"); }
  f(x,y) && y << `Constant() -> { System.out.println("Constant found as second child"); }
}
</source>

This of course extends to java variables.

<source lang="tom">
public void findName(String name, StringList l) {
  %match(l) {
    SList(_*,n,_*) && n << name -> { System.out.println(name + " found"); }
  }
}
</source>

===Why does my backquote construct not compile?===
explain the use of functions in AU operators (%op needed to declare the function)

===Can I call a strategy in a strategy itself?===

There exist different situations:
* you can always call a sub-strategy in the {{java}} part of a {{Keyword|%strategy}} construct: you just have to call <code>visitLight</code> or <code>visit</code> on another subject:

<source lang="tom">
`OuterStrat.visit(t1); // or visitLight

%strategy OuterStrat() {
  ... -> { `InnerStrat().visit(t2); } // or visitLight
}
</source>


* if you want to apply another strategy on the current subject (and you want to maintain the position information), then you have to use the <code>visit</code> method in the following way:

<source lang="tom">
`TopDown(OuterStrat).visit(t1);

%strategy OuterStrat() {
  ... -> { 
    // apply InnerStrat on t1 at the current position
    `InnerStrat().visit(getEnvironment());
  }
}
</source>
Since an environment is maintained, you have to apply the sub-strategy on the current environment, using <code>visit(getEnvironment())</code>.

===How can I make a strategy fail?===
This is simple: just apply the startegy <code>Fail()</code> to any object.
<source lang="tom">
`Fail().visitLight(...);
</source>

===How to use a congruence strategy operator?===
# when using %gom (see [[Documentation:Gom#Using_Gom_with_Tom|Using {{gom}} with {{tom}}]]):<br />you have to use the <code>--withCongruenceStrategies</code> option: <code>%gom(--withCongruenceStrategies) { ... }</code>
# when including a mapping generated by {{gom}} (see [[Documentation:Gom#Using_Gom_with_Tom|Using {{gom}} with {{tom}}]]):<br />just add an  {{Terminal|<nowiki>_</nowiki>}} at the beginning of the included {{tom}} file: <code>%include{ .../_term.tom }</code> for instance.
# when generating an introspector (see [[Documentation:Strategies#Applying_a_strategy_on_a_user_defined_data-structures_.28.2A.29|Introspector]]):<br />this is not possible. At present, congruence strategies can only be used when {{gom}} is used to generate the data-structure.

==Not yet answered questions==
===How efficient is the code generated by Tom?===
===What happens if the data-structure is modified during matching?===

===How does Tom depend on the Api's and semantics of Gom generated structures?===
# On the maximal sharing
# On the 'setters'
#On 'compareTo()'
#On 'compareToLPO()'
#On 'equivalent(shared.SharedObject obj)'
#On 'public shared.SharedObject duplicate()'

{{tom}} (i.e. the compiler) does not depend on the Api of {{gom}} generated structures (i.e. nothing is known by the compiler). 

However, when generating code, {{gom}} also generates a mapping. This one depends and exploits the particularity of the generated code.
# It uses <code>==</code> to compare terms in constant time, thanks to maximal sharing
# It does not use the 'setters'. They are generated to allow a {{java}} programmer to use the data-structure directly, in a convenient way
# It does not use the 'compareTo()' nor  'compareToLPO()'. These methods are just there to help comparing terms
# It does not use 'equivalent' nor 'duplicate'. These methods are used internally, by the shared-object-factory to build terms with maximal sharing

When compiling <code>%strategy</code> constructs, the data-structure is supposed to implement <code>tom.library.sl.Visitable</code>.

===How could "grammar inheritance" become supported in Tom?===

See http://www.antlr2.org/doc/inheritance.html.

Would like to have a Java grammar (Class, Method, etc) and then to define another grammar for Struts, for example, to have ActionClass and ActionMethod.
Then when matching Class to also find ActionClass.