Package: antlerinator
ANTLeRinatoris a Python utility package to help keeping components of
ANTLR v4 in sync.RequirementsPython>= 3.6JavaSE >= 7 JRE or JDK (the latter is optional)InstallANTLeRinatorhas both run-time and build-time components, therefore it can be
used both as an install requirement and as a setup requirement.To useANTLeRinatorat run-time, it can be added tosetup.cfgas an
install requirement (if usingsetuptoolswith declarative config):[options]install_requires=antlerinatorantlr4-python3-runtime==4.9.2# optionalNote thatANTLeRinatorhas no direct dependency on theANTLRv4runtime.To useANTLeRinatorat build-time, it can be added topyproject.tomlas a
build system/setup requirement (if usingPEP517builds):[build-system]requires=["antlerinator","setuptools",]build-backend="setuptools.build_meta"To installANTLeRinatormanually, e.g., into a virtual environment, usepip:pip install antlerinatorThe above approaches install the latest release ofANTLeRinatorfromPyPI.
Alternatively, for the development version, clone the project and perform a
local install:pip install .UsageDownloading the ANTLRv4 tool jar file at run-timeIf theANTLRv4runtime is installed,ANTLeRinatorcan be used to download
the corresponding version of the tool jar file:importantlerinatorassertantlerinator.__antlr_version__isnotNone# alternatively: import antlr4path=antlerinator.download(lazy=True)If theANTLRv4runtime is not installed or a different version of the tool jar
is needed, the required version must/can be specified:importantlerinatorpath=antlerinator.download(version='4.9.2',lazy=True)By default, these approaches download files to a~/.antlerinatordirectory,
and only if necessary (i.e., the jar file has not been downloaded yet).Downloading the ANTLRv4 tool jar manuallyShould there be need for downloading the ANTLR v4 tool jar manually, a helper
script is available:antlerinator-download --helpAdding ANTLRv4 support to the command line interfaceIf an application has anArgumentParser-based command line interface,ANTLeRinatorcan be used to add a CLI argument to specify whichANTLRv4tool
jar to use. The default processing of the argument, also provided byANTLeRinator, is to download the tool jar version corresponding to theANTLRv4runtime if necessary:importantlerinatorimportargparseimportsubprocessassertantlerinator.__antlr_version__isnotNoneparser=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 ANTLRv4ANTLeRinatoralso extendsSetuptoolsto allow building lexers/parsers at
build-time from.g4grammars. It adds two newSetuptoolscommands,build_antlrandclean_antlr, to perform the building and the cleanup of
lexers/parsers, and also ensures that these new commands are invoked by the
standardbuild(install),develop, andcleancommands as well as
by theSetuptools-internaleditable_wheelcommand as appropriate. The
building of lexers/parsers is performed using theANTLRv4tool and is
controlled by the[build_antlr]section insetup.cfg:[build_antlr]commands=antlerinator:4.9.2 path/to/Dummy.g4 -Dlanguage=Python2 -o pkg/parser/py2 -Xexact-output-dirantlerinator:4.9.2 path/to/Dummy.g4 -Dlanguage=Python3 -o pkg/parser/py3 -Xexact-output-diroutput=pkg/parser/py?/Dummy*.py#java =Thecommandsoption ofbuild_antlrlists the invocations of theANTLRv4tool. The first element of each invocation is a so-called provider
specification that defines where to get theANTLRv4tool jar from. Currently,
two providers are supported:antlerinator:N.MusesANTLeRinatorto
download the requested version of the tool jar (if necessary), whilefile:/path/to/antlr.jaruses the explicitly given tool jar. The rest of the
elements of each invocation are passed to the tool jar as command line
arguments.Thejavaoption can be given to explicitly specify which Java VM to use to
run theANTLRv4tool (javais used by default).Theoutputoption shall list the file names or glob patterns of the output
of theANTLRv4tool invocations. Theclean_antlrcommand removes these
files on cleanup.Copyright and LicensingLicensed under the BSD 3-ClauseLicense.