<!--
  ~ 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.</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>
