JJTree Task

## JJTree

### Description

Invokes the JJTree preprocessor for the JavaCC compiler compiler. It inserts parse tree building actions at various places in the JavaCC source that it generates. The output of JJTree is run through JavaCC to create the parser.

To use the `jjtree` task, set the target attribute to the name of the JJTree grammar file to process. You also need to specify the directory containing the JavaCC installation using the javacchome attribute, so that Ant can find the JavaCC classes. Optionally, you can also set the outputdirectory to write the generated JavaCC grammar and node files to a specific directory. Otherwise `jjtree` writes the generated JavaCC grammar and node files to the directory containing the JJTree grammar file. As an extra option, you can also set the outputfile to write the generated JavaCC grammar file to a specific (directory and) file. Otherwise `jjtree` writes the generated JavaCC grammar file as the JJTree grammar file with a suffix `.jj`.

This task only invokes JJTree if the grammar file is newer than the generated JavaCC file.

### Parameters

Attribute | Description | Required
--- | --- | ---
target | The JJTree grammar file to process. | Yes
javacchome | The directory containing the JavaCC distribution. | Yes
outputdirectory | The directory to write the generated JavaCC grammar and node files to. If not set, the files are written to the directory containing the grammar file. | No
outputfile | The file to write the generated JavaCC grammar file to. If not set, the file is written with the same name as the JJTree grammar file but with a the suffix `.jj`. This is a filename relative to outputdirectory if specified, the project's basedir. | No
buildnodefiles | Sets the BUILD_NODE_FILES grammar option. This is a boolean option. | No
multi | Sets the MULTI grammar option. This is a boolean option. | No
nodedefaultvoid | Sets the NODE_DEFAULT_VOID grammar option. This is a boolean option. | No
nodefactory | Sets the NODE_FACTORY grammar option. This is boolean option. | No
nodescopehook | Sets the NODE_SCOPE_HOOK grammar option. This is a boolean option. | No
nodeusesparser | Sets the NODE_USES_PARSER grammar option. This is a boolean option. | No
static | Sets the STATIC grammar option. This is a boolean option. | No
visitor | Sets the VISITOR grammar option. This is a boolean option. | No
nodepackage | Sets the NODE_PACKAGE grammar option. This is a string option. | No
visitorexception | Sets the VISITOR_EXCEPTION grammar option. This is a string option. | No
nodeprefix | Sets the NODE_PREFIX grammar option. This is a string option. | No
maxmemory | Max amount of memory to allocate to the forked JVM. since Ant 1.8.3 | No

### Example

Invoke JJTree on grammar file `src/Parser.jjt`, writing the generated grammar file, `Parser.jj`, to `build/src`. The grammar option NODE_USES_PARSER is set to true when invoking JJTree.

    <jjtree target="src/Parser.jjt"
            outputdirectory="build/src"
            javacchome="c:/program files/JavaCC"
            nodeusesparser="true"/>

### Comparison of output locations between command line JJTree and different Ant `taskdef` versions

Command line JJTree options and generated files (working directory: `/tmp`) | Ant 1.5.3 versus command line | Ant 1.6 versus command line
--- | --- | ---
    jjtree  grammar.jjt
        /tmp/grammar.jj
        /tmp/<generated>.java
| Same | Same
    jjtree  relative/grammar.jjt
        /tmp/grammar.jj
        /tmp/<generated>.java
    /tmp/relative/grammar.jj
    /tmp/relative/<generated>.java
| Same
    jjtree /tmp/absolute/grammar.jjt
        /tmp/grammar.jj
        /tmp/<generated>.java
    /tmp/absolute/grammar.jj
    /tmp/absolute/<generated>.java
| Same
    jjtree -OUTPUT_DIRECTORY:relative grammar.jjt
        /tmp/relative/grammar.jj
        /tmp/relative/<generated>.java
| Same | Same
    jjtree -OUTPUT_DIRECTORY:relative relative/grammar.jjt
        /tmp/relative/grammar.jj
        /tmp/relative/<generated>.java
| Same | Same
    jjtree -OUTPUT_DIRECTORY:relative /tmp/absolute/grammar.jjt
        /tmp/relative/grammar.jj
        /tmp/relative/<generated>.java
| Same | Same
    jjtree -OUTPUT_DIRECTORY:/tmp/absolute/ grammar.jjt
        /tmp/absolute/grammar.jj
        /tmp/absolute/<generated>.java
| Same | Same
    jjtree -OUTPUT_DIRECTORY:/tmp/absolute/ relative/grammar.jjt
        /tmp/absolute/grammar.jj
        /tmp/absolute/<generated>.java
| Same | Same
    jjtree -OUTPUT_DIRECTORY:/tmp/absolute/ /tmp/absolute/grammar.jjt
        /tmp/absolute/grammar.jj
        /tmp/absolute/<generated>.java
| Same | Same
    jjtree -OUTPUT_FILE:output.jj grammar.jjt
        /tmp/output.jj
        /tmp/<generated>.java
| Not Supported | Same
    jjtree -OUTPUT_FILE:output.jj relative/grammar.jjt
        /tmp/output.jj
        /tmp/<generated>.java
| Not Supported | Same
    jjtree -OUTPUT_FILE:output.jj /tmp/absolute/grammar.jjt
        /tmp/output.jj
        /tmp/<generated>.java
| Not Supported | Same
    jjtree -OUTPUT_FILE:output.jj -OUTPUT_DIRECTORY:relative grammar.jjt
        /tmp/relative/output.jj
        /tmp/relative/<generated>.java
| Not Supported | Same
    jjtree -OUTPUT_FILE:output.jj -OUTPUT_DIRECTORY:relative relative/grammar.jjt
        /tmp/relative/output.jj
        /tmp/relative/<generated>.java
| Not Supported | Same
    jjtree -OUTPUT_FILE:output.jj -OUTPUT_DIRECTORY:relative /tmp/absolute/grammar.jjt
        /tmp/relative/output.jj
        /tmp/relative/<generated>.java
| Not Supported | Same
    jjtree -OUTPUT_FILE:output.jj -OUTPUT_DIRECTORY:/tmp/absolute/ grammar.jjt
        /tmp/absolute/output.jj
        /tmp/absolute/<generated>.java
| Not Supported | Same
    jjtree -OUTPUT_FILE:output.jj -OUTPUT_DIRECTORY:/tmp/absolute/ relative/grammar.jjt
        /tmp/absolute/output.jj
        /tmp/absolute/<generated>.java
| Not Supported | Same
    jjtree -OUTPUT_FILE:output.jj -OUTPUT_DIRECTORY:/tmp/absolute/ /tmp/absolute/grammar.jjt
        /tmp/absolute/output.jj
        /tmp/absolute/<generated>.java
| Not Supported | Same
    jjtree -OUTPUT_FILE:subdir/output.jj grammar.jjt
        /tmp/subdir/output.jj
        /tmp/<generated>.java
| Not Supported | Same
    jjtree -OUTPUT_FILE:subdir/output.jj relative/grammar.jjt
        /tmp/subdir/output.jj
        /tmp/<generated>.java
| Not Supported | Same
    jjtree -OUTPUT_FILE:subdir/output.jj /tmp/absolute/grammar.jjt
        /tmp/subdir/output.jj
        /tmp/<generated>.java
| Not Supported | Same
    jjtree -OUTPUT_FILE:subdir/output.jj -OUTPUT_DIRECTORY:relative grammar.jjt
        /tmp/relative/subdir/output.jj
        /tmp/relative/<generated>.java
| Not Supported | Same
    jjtree -OUTPUT_FILE:subdir/output.jj -OUTPUT_DIRECTORY:relative relative/grammar.jjt
        /tmp/relative/subdir/output.jj
        /tmp/relative/<generated>.java
| Not Supported | Same
    jjtree -OUTPUT_FILE:subdir/output.jj -OUTPUT_DIRECTORY:relative /tmp/absolute/grammar.jjt
        /tmp/relative/subdir/output.jj
        /tmp/relative/<generated>.java
| Not Supported | Same
    jjtree -OUTPUT_FILE:subdir/output.jj -OUTPUT_DIRECTORY:/tmp/absolute/ grammar.jjt
        /tmp/absolute/subdir/output.jj
        /tmp/absolute/<generated>.java
| Not Supported | Same
    jjtree -OUTPUT_FILE:subdir/output.jj -OUTPUT_DIRECTORY:/tmp/absolute/ relative/grammar.jjt
        /tmp/absolute/subdir/output.jj
        /tmp/absolute/<generated>.java
| Not Supported | Same
    jjtree -OUTPUT_FILE:subdir/output.jj -OUTPUT_DIRECTORY:/tmp/absolute/ /tmp/absolute/grammar.jjt
        /tmp/absolute/subdir/output.jj
        /tmp/absolute/<generated>.java
| Not Supported | Same
    jjtree -OUTPUT_FILE:/tmp/subdir/output.jj grammar.jjt
        /tmp/subdir/output.jj
        /tmp/<generated>.java
| Not Supported | Same
    jjtree -OUTPUT_FILE:/tmp/subdir/output.jj relative/grammar.jjt
        /tmp/subdir/output.jj
        /tmp/<generated>.java
| Not Supported | Same
    jjtree -OUTPUT_FILE:/tmp/subdir/output.jj /tmp/absolute/grammar.jjt
        /tmp/subdir/output.jj
        /tmp/<generated>.java
| Not Supported | Same
    jjtree -OUTPUT_FILE:D:/tmp/subdir/output.jj grammar.jjt
        /tmp/subdir/output.jj
        /tmp/<generated>.java
| Not Supported | Not Supported*
    jjtree -OUTPUT_FILE:D:/tmp/subdir/output.jj relative/grammar.jjt
        /tmp/subdir/output.jj
        /tmp/<generated>.java
| Not Supported | Not Supported*
    jjtree -OUTPUT_FILE:D:/tmp/subdir/output.jj /tmp/absolute/grammar.jjt
        /tmp/subdir/output.jj
        /tmp/<generated>.java
| Not Supported | Not Supported*
    jjtree -OUTPUT_FILE:/tmp/subdir/output.jj -OUTPUT_DIRECTORY:relative grammar.jjt
        /tmp/relative/tmp/subdir/output.jj
        /tmp/relative/<generated>.java
| Not Supported | Same
    jjtree -OUTPUT_FILE:/tmp/subdir/output.jj -OUTPUT_DIRECTORY:relative relative/grammar.jjt
        /tmp/relative/tmp/subdir/output.jj
        /tmp/relative/<generated>.java
| Not Supported | Same
    jjtree -OUTPUT_FILE:/tmp/subdir/output.jj -OUTPUT_DIRECTORY:relative /tmp/absolute/grammar.jjt
        /tmp/relative/tmp/subdir/output.jj
        /tmp/relative/<generated>.java
| Not Supported | Same
    jjtree -OUTPUT_FILE:/tmp/subdir/output.jj -OUTPUT_DIRECTORY:/tmp/absolute/ grammar.jjt
        /tmp/absolute/tmp/subdir/output.jj
        /tmp/absolute/<generated>.java
| Not Supported | Same
    jjtree -OUTPUT_FILE:/tmp/subdir/output.jj -OUTPUT_DIRECTORY:/tmp/absolute/ relative/grammar.jjt
        /tmp/absolute/tmp/subdir/output.jj
        /tmp/absolute/<generated>.java
| Not Supported | Same
    jjtree -OUTPUT_FILE:/tmp/subdir/output.jj -OUTPUT_DIRECTORY:/tmp/absolute/ /tmp/absolute/grammar.jjt
        /tmp/absolute/tmp/subdir/output.jj
        /tmp/absolute/<generated>.java
| Not Supported | Same

Note: When running JJTree with the Ant `taskdef jjtree` the option `-OUTPUT_DIRECTORY` must always be set, because the project's basedir and the Ant working directory might differ. So even if you don't specify the outputdirectory for `taskdef jjtree`, JJTree will be called with the `-OUTPUT_DIRECTORY` set to the project's basedir. But when the `-OUTPUT_DIRECTORY` is set, the `-OUTPUT_FILE` setting is handled as if relative to this `-OUTPUT_DIRECTORY`. Thus when the `-OUTPUT_FILE` is absolute or contains a drive letter we have a problem. Therefore absolute outputfiles (when the outputdirectory isn't specified) are made relative to the default directory. And for this reason outputfiles that contain a drive letter can't be supported.

By the way: specifying a drive letter in the `-OUTPUT_FILE` when the `-OUTPUT_DIRECTORY` is set, also results in strange behavior when running JJTree from the command line.