Skip to main content

ANTLeRinator

Project description

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

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

Requirements

  • Python >= 3.5

  • Java SE >= 7 JRE or JDK (the latter is optional)

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 (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 .

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:

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:

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:

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

antlerinator-1!2.0.1.tar.gz (17.5 kB view hashes)

Uploaded source

Built Distribution

antlerinator-1!2.0.1-py3-none-any.whl (10.2 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page