<!--
  ~ Copyright 2010 the original author or authors.
  ~
  ~ Licensed under the Apache License, Version 2.0 (the "License");
  ~ you may not use this file except in compliance with the License.
  ~ You may obtain a copy of the License at
  ~
  ~      http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing, software
  ~ distributed under the License is distributed on an "AS IS" BASIS,
  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  ~ See the License for the specific language governing permissions and
  ~ limitations under the License.
  -->

<chapter id="antlr_plugin">
    <title>The ANTLR Plugin</title>

    <para>The ANTLR plugin extends the Java plugin to add support for generating parsers using <ulink url="http://www.antlr.org/">ANTLR</ulink>.</para>

    <note>
        <para>
            The ANTLR plugin supports ANTLR version 2, 3 and 4.
        </para>
    </note>

    <section>
        <title>Usage</title>
        <para>To use the ANTLR plugin, include the following in your build script:</para>
        <sample id="useAntlrPlugin" dir="antlr" title="Using the ANTLR plugin">
            <sourcefile file="build.gradle" snippet="use-plugin"/>
        </sample>
    </section>

    <section>
        <title>Tasks</title>
        <para>The ANTLR plugin adds a number of tasks to your project, as shown below.</para>

        <table>
            <title>ANTLR plugin - tasks</title>
            <thead>
                <tr>
                    <td>Task name</td>
                    <td>Depends on</td>
                    <td>Type</td>
                    <td>Description</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <literal>generateGrammarSource</literal>
                </td>
                <td>-</td>
                <td><apilink class="org.gradle.api.plugins.antlr.AntlrTask"/></td>
                <td>Generates the source files for all production ANTLR grammars.</td>
            </tr>
            <tr>
                <td>
                    <literal>generateTestGrammarSource</literal>
                </td>
                <td>-</td>
                <td><apilink class="org.gradle.api.plugins.antlr.AntlrTask"/></td>
                <td>Generates the source files for all test ANTLR grammars.</td>
            </tr>
            <tr>
                <td>
                    <literal>generate<replaceable>SourceSet</replaceable>GrammarSource</literal>
                </td>
                <td>-</td>
                <td><apilink class="org.gradle.api.plugins.antlr.AntlrTask"/></td>
                <td>Generates the source files for all ANTLR grammars for the given source set.</td>
            </tr>
        </table>
        <para>The ANTLR plugin adds the following dependencies to tasks added by the Java plugin.</para>
        <table>
            <title>ANTLR plugin - additional task dependencies</title>
            <thead>
                <td>Task name</td>
                <td>Depends on</td>
            </thead>
            <tr>
                <td>compileJava</td>
                <td>generateGrammarSource</td>
            </tr>
            <tr>
                <td>compileTestJava</td>
                <td>generateTestGrammarSource</td>
            </tr>
            <tr>
                <td>compile<replaceable>SourceSet</replaceable>Java</td>
                <td>generate<replaceable>SourceSet</replaceable>GrammarSource</td>
            </tr>
        </table>
    </section>

    <section>
        <title>Project layout</title>
        <table>
            <title>ANTLR plugin - project layout</title>
            <thead>
                <tr>
                    <td>Directory</td>
                    <td>Meaning</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <filename>src/main/antlr</filename>
                </td>
                <td>Production ANTLR grammar files. If the ANTLR grammar is organized in packages, the structure in the antlr folder should reflect
                the package structure. This ensures that the generated sources end up in the correct target subfolder.</td>
            </tr>
            <tr>
                <td>
                    <filename>src/test/antlr</filename>
                </td>
                <td>Test ANTLR grammar files.</td>
            </tr>
            <tr>
                <td>
                    <filename>src/<replaceable>sourceSet</replaceable>/antlr</filename>
                </td>
                <td>ANTLR grammar files for the given source set.</td>
            </tr>
        </table>
    </section>

    <section>
        <title>Dependency management</title>
        <para>
            The ANTLR plugin adds an <literal>antlr</literal> dependency configuration which provides the ANTLR implementation to use.
            The following example shows how to use ANTLR version 3.
        </para>
        <sample id="declareAntlrVersion" dir="antlr" title="Declare ANTLR version">
            <sourcefile file="build.gradle" snippet="declare-dependency"/>
        </sample>
        <para>
            If no dependency is declared, <literal>antlr:antlr:2.7.7</literal> will be used as the default.
            To use a different ANTLR version add the appropriate dependency to the <literal>antlr</literal> dependency configuration as above.
        </para>
    </section>

    <section>
        <title>Convention properties</title>
        <para>The ANTLR plugin does not add any convention properties.</para>
    </section>

    <section>
        <title>Source set properties</title>
        <para>The ANTLR plugin adds the following properties to each source set in the project.</para>
        <table>
            <title>ANTLR plugin - source set properties</title>
            <thead>
                <tr>
                    <td>Property name</td>
                    <td>Type</td>
                    <td>Default value</td>
                    <td>Description</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <literal>antlr</literal>
                </td>
                <td>
                    <apilink class="org.gradle.api.file.SourceDirectorySet"/> (read-only)
                </td>
                <td>
                    Not null
                </td>
                <td>
                    The ANTLR grammar files of this source set. Contains all <filename>.g</filename> or <filename>.g4</filename> files found in the ANTLR
                    source directories, and excludes all other types of files.
                </td>
            </tr>
            <tr>
                <td>
                    <literal>antlr.srcDirs</literal>
                </td>
                <td>
                    <classname>Set&lt;File></classname>. Can set using anything described in <xref linkend="sec:specifying_multiple_files"/>.
                </td>
                <td>
                    <literal>[<replaceable>projectDir</replaceable>/src/<replaceable>name</replaceable>/antlr]</literal>
                </td>
                <td>
                    The source directories containing the ANTLR grammar files of this source set.
                </td>
            </tr>
        </table>
    </section>
    <section>
        <title>Controlling the ANTLR generator process</title>
        <para>
            The ANTLR tool is executed in a forked process.
            This allows fine grained control over memory settings for the ANTLR process.
            To set the heap size of a ANTLR process, the <literal>maxHeapSize</literal> property
            of <apilink class="org.gradle.api.plugins.antlr.AntlrTask"/> can be used.
            To pass additional command-line arguments, append to the <literal>arguments</literal> property
            of <apilink class="org.gradle.api.plugins.antlr.AntlrTask"/>.
        </para>
        <sample id="advanced" dir="antlr" title="setting custom max heap size and extra arguments for ANTLR">
            <sourcefile file="build.gradle" snippet="generate-grammar-settings"/>
        </sample>
    </section>

</chapter>
