ANTLeRinator is a Python utility package to help keeping components of ANTLR v4 in sync.
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 (if using setuptools with declarative config):
[options] install_requires = antlerinator antlr4-python3-runtime=<s>=4.9.2 # optional</s>
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 (if using PEP517 builds):
[build-system] requires = [ <s>"antlerinator"</s>, <s>"setuptools"</s>, ] build-backend = <s>"setuptools.build_meta"</s>
To install ANTLeRinator manually, e.g., into a virtual environment, use pip:
pip install antlerinator
The above approaches install the latest release of ANTLeRinator from PyPI. Alternatively, for the development version, clone the project and perform a local install:
pip install .
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:
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:
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:
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:
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:
[build_antlr] commands = antlerinator:4.9.2 path/to/Dummy.g4 -Dlanguage=<s>Python2 -o pkg/parser/py2 -Xexact-output-dir</s> antlerinator:4.9.2 path/to/Dummy.g4 -Dlanguage=<s>Python3 -o pkg/parser/py3 -Xexact-output-dir</s> 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.
Copyright and Licensing
Licensed under the BSD 3-Clause License.
Release history Release notifications | RSS feed
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Hashes for antlerinator-1!2.0.1-py3-none-any.whl