<!--
  ~ 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 only supports ANTLR version 2.
        </para>
    </note>

    <section>
        <title>Usage</title>
        <para>To use the ANTLR plugin, include 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. You use this to declare the
            ANTLR dependency that you wish to use.</para>
        <sample id="declareAntlrVersion" dir="antlr" title="Declare ANTLR version">
            <sourcefile file="build.gradle" snippet="declare-dependency"/>
        </sample>
    </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> 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>

</chapter>
