Metadata-Version: 2.1
Name: antlerinator
Version: 1!1.1.0
Summary: ANTLeRinator
Home-page: https://github.com/renatahodovan/antlerinator
Author: Renata Hodovan, Akos Kiss
Author-email: hodovan@inf.u-szeged.hu, akiss@inf.u-szeged.hu
License: BSD
Platform: any
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: !=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,>=2.7
Description-Content-Type: text/x-rst
License-File: LICENSE.rst

============
ANTLeRinator
============

.. image:: https://img.shields.io/pypi/v/antlerinator?logo=python&logoColor=white
   :target: https://pypi.org/project/antlerinator/
.. image:: https://img.shields.io/pypi/l/antlerinator?logo=open-source-initiative&logoColor=white
   :target: https://pypi.org/project/antlerinator/
.. image:: https://img.shields.io/github/workflow/status/renatahodovan/antlerinator/main/master?logo=github&logoColor=white
   :target: https://github.com/renatahodovan/antlerinator/actions
.. image:: https://img.shields.io/coveralls/github/renatahodovan/antlerinator/master?logo=coveralls&logoColor=white
   :target: https://coveralls.io/github/renatahodovan/antlerinator

.. start included documentation

*ANTLeRinator* is a Python utility package to help keeping components of
ANTLR v4 in sync.


Requirements
============

* Python_ ~= 2.7 or >= 3.5
* pip_
* Java_ SE >= 7 JRE or JDK (the latter is optional)

.. _Python: https://www.python.org
.. _pip: https://pip.pypa.io
.. _Java: https://www.oracle.com/java/


Install
=======

*ANTLeRinator* has both run-time and build-time components, therefore it can be
used both as an install requirement and as a setup requirement.

To use *ANTLeRinator* at run-time, it can be added to ``setup.cfg`` as an
install requirement:

.. code-block:: ini

    [options]
    install_requires =
        antlerinator
        antlr4-python2-runtime==4.9.2; python_version~="2.7"  # optional
        antlr4-python3-runtime==4.9.2; python_version>="3.0"  # optional

Note that *ANTLeRinator* has no direct dependency on the *ANTLRv4* runtime.

To use *ANTLeRinator* at build-time, it can be added to ``pyproject.toml`` as a
build system/setup requirement:

.. code-block:: toml

    [build-system]
    requires = [
        "antlerinator",
        "setuptools",
    ]
    build-backend = "setuptools.build_meta"

To install *ANTLeRinator* manually, e.g., into a virtual environment, go the
quick way::

    pip install antlerinator

Alternatively, clone the project and perform a local install::

    pip install .


Usage
=====

Downloading the ANTLRv4 tool jar file at run-time
-------------------------------------------------

If the *ANTLRv4* runtime is installed, *ANTLeRinator* can be used to download
the corresponding version of the tool jar file:

.. code-block:: python

    import antlerinator

    assert antlerinator.__antlr_version__ is not None  # alternatively: import antlr4

    path = antlerinator.download(lazy=True)

If the *ANTLRv4* runtime is not installed or a different version of the tool jar
is needed, the required version must/can be specified:

.. code-block:: python

    import antlerinator

    path = antlerinator.download(version='4.9.2', lazy=True)

By default, these approaches download files to a ``~/.antlerinator`` directory,
and only if necessary (i.e., the jar file has not been downloaded yet).

Downloading the ANTLRv4 tool jar manually
-----------------------------------------

Should there be need for downloading the ANTLR v4 tool jar manually, a helper
script is available::

    antlerinator-download --help

Adding ANTLRv4 support to the command line interface
----------------------------------------------------

If an application has an ``ArgumentParser``-based command line interface,
*ANTLeRinator* can be used to add a CLI argument to specify which *ANTLRv4* tool
jar to use. The default processing of the argument, also provided by
*ANTLeRinator*, is to download the tool jar version corresponding to the
*ANTLRv4* runtime if necessary:

.. code-block:: python

    import antlerinator
    import argparse
    import subprocess

    assert antlerinator.__antlr_version__ is not None

    parser = argparse.ArgumentParser()
    antlerinator.add_antlr_argument(parser)
    args = parser.parse_args()

    antlerinator.process_antlr_argument(args)

    subprocess.call(['java', '-jar', args.antlr])

Building lexers/parsers at build-time with ANTLRv4
--------------------------------------------------

*ANTLeRinator* also extends *Setuptools* to allow building lexers/parsers at
build-time from ``.g4`` grammars. It adds two new *Setuptools* commands,
``build_antlr`` and ``clean_antlr``, to perform the building and the cleanup of
lexers/parsers, and also ensures that these new commands are invoked by the
standard ``build`` (``install``), ``develop``, ``clean``, and ``sdist`` commands
as appropriate. The building of lexers/parsers is performed using the *ANTLRv4*
tool and is controlled by the ``[build_antlr]`` section in ``setup.cfg``:

.. code-block:: ini

    [build_antlr]
    commands =
        antlerinator:4.9.2 path/to/Dummy.g4 -Dlanguage=Python2 -o pkg/parser/py2 -Xexact-output-dir
        antlerinator:4.9.2 path/to/Dummy.g4 -Dlanguage=Python3 -o pkg/parser/py3 -Xexact-output-dir
    output =
        pkg/parser/py?/Dummy*.py
    #java =

The ``commands`` option of ``build_antlr`` lists the invocations of the
*ANTLRv4* tool. The first element of each invocation is a so-called provider
specification that defines where to get the *ANTLRv4* tool jar from. Currently,
two providers are supported: ``antlerinator:N.M`` uses *ANTLeRinator* to
download the requested version of the tool jar (if necessary), while
``file:/path/to/antlr.jar`` uses the explicitly given tool jar. The rest of the
elements of each invocation are passed to the tool jar as command line
arguments.

The ``java`` option can be given to explicitly specify which Java VM to use to
run the *ANTLRv4* tool (``java`` is used by default).

The ``output`` option shall list the file names or glob patterns of the output
of the *ANTLRv4* tool invocations. The ``clean_antlr`` command removes these
files on cleanup.

.. end included documentation


Copyright and Licensing
=======================

Licensed under the BSD 3-Clause License_.

.. _License: LICENSE.rst


