setuptools-antlr
================
|Build Status| |Coverage Status| |PyPI Version| |GitHub Version| |License|
.. |Build Status| image:: https://travis-ci.com/ferraith/setuptools-antlr.svg
:target: https://travis-ci.com/ferraith/setuptools-antlr
:alt: Build Status
.. |Coverage Status| image:: https://coveralls.io/repos/github/ferraith/setuptools-antlr/badge.svg?branch=master
:target: https://coveralls.io/github/ferraith/setuptools-antlr?branch=master
:alt: Coverage Status
.. |PyPI Version| image:: https://badge.fury.io/py/setuptools-antlr.svg
:target: https://pypi.org/project/setuptools-antlr
:alt: PyPI Version
.. |GitHub Version| image:: https://badge.fury.io/gh/ferraith%2Fsetuptools-antlr.svg
:target: https://github.com/ferraith/setuptools-antlr/releases
:alt: GitHub Version
.. |License| image:: https://img.shields.io/github/license/ferraith/setuptools-antlr.svg
:target: https://raw.githubusercontent.com/ferraith/setuptools-antlr/master/LICENSE
:alt: License
Overview
--------
A ``setuptools`` command for generating ANTLR based parsers.
This is an extension for `setuptools <https://pypi.org/project/setuptools/>`__ integrating the famous `ANTLR <http://www.antlr.org/>`__ parser generator into the Python packaging process. It encapsulates the Java based generator of ANTLR and provides the user a single command to control the generation process.
All command line options of ANTLR are also available through the setuptools command. The user has the choice to pass the options on the command line or configure ANTLR in a dedicated section in the ``setup.cfg`` file.
ANTLR grammars and its dependencies like imported grammars or token files are automatically detected. For each grammar a Python package will be generated during execution of the ``antlr`` command.
Installation
------------
``setuptools-antlr`` can be installed in various ways. To run it the following prerequisites have to be fulfilled:
- Python 3.5+
- setuptools
- Java JRE 1.7+
The source distribution is already shipped with ANTLR 4.7.1. It isn't necessary to download ANTLR additionally.
After installation, the used Python environment has a new setuptools command called ``antlr``.
From Source Code
****************
::
> git clone https://github.com/ferraith/setuptools-antlr.git
> cd setuptools-antlr
> pip install .
From PyPI
*********
::
> pip install setuptools-antlr
From GitHub Releases
********************
::
> pip install <setuptools-antlr_wheel>
Usage
-----
Integration
***********
For a smooth user experience it's recommended to pass ``setuptools-antlr`` using the ``setup_requires`` argument of setup function. Additionally each generated parser requires the ANTLR runtime library which should be added to ``install_requires`` argument:
.. code:: python
setup(
...
setup_requires=['setuptools-antlr'],
install_requires=['antlr4-python3-runtime']
...
)
Before generating a parser ``setuptools`` will automatically check the Python environment and download ``setuptools-antlr`` from `PyPI <https://pypi.org>`__ if it's missing. During the installation of the project package ``pip`` will install ``antlr4-python3-runtime`` into the Python environment.
Configuration
*************
``setuptools-antlr`` provides two possibilities to configure the ANTLR parser generator.
All options of ANTLR can be passed on the command line after the ``antlr`` command:
::
> python setup.py antlr --visitor
It's also possible to pass several options to ANTLR or execute multiple commands at once:
::
> python setup.py antlr --visitor --grammar-options "superClass=Abc tokenVocab=SomeLexer" bdist_wheel
See ``python setup.py antlr --help`` for available command line options:
::
> python setup.py antlr --help
...
Options for 'AntlrCommand' command:
--grammars (-g) specify grammars to generate parsers for
--output (-o) specify directories where output is generated
--atn generate rule augmented transition network diagrams
--encoding specify grammar file encoding e.g. euc-jp
--message-format specify output style for messages in antlr, gnu, vs2005
--long-messages show exception details when available for errors and
warnings
--listener generate parse tree listener (default)
--no-listener don't generate parse tree listener
--visitor generate parse tree visitor
--no-visitor don't generate parse tree visitor (default)
--depend generate file dependencies
--grammar-options set/override a grammar-level option
--w-error treat warnings as error
--x-dbg-st launch StringTemplate visualizer on generated code
--x-dbg-st-wait wait for STViz to close before continuing
--x-force-atn use the ATN simulator for all predictions
--x-exact-output-dir output goes into -o directories regardless of paths/package
--x-log dump lots of logging info to antlr-<timestamp>.log
...
The ANTLR documentation explains all `command line options <https://github.com/antlr/antlr4/blob/master/doc/tool-options.md>`__ and `grammar options <https://github.com/antlr/antlr4/blob/master/doc/options.md>`__ in detail.
Apart from passing options on the command line it's also possible to add a dedicated ``[antlr]`` section to ``setup.cfg``. The following example section contains all available options:
.. code:: ini
[antlr]
# Specify grammars to generate parsers for; default: None
#grammars = <grammar> [<grammar> ...]
# Specify directories where all output is generated; default: ./
output = default=gen
# Generate DOT graph files that represent the internal ATN data structures (yes|no); default: no
#atn = no
# Specify grammar file encoding; default: utf-8
#encoding = utf-8
# Specify output style for messages in antlr (antlr|gnu|vs2005); default: antlr
#message-format = antlr
# Show exception details when available for errors and warnings (yes|no); default: no
#long-messages = no
# Generate a parse tree listener (yes|no); default: yes
#listener = yes
# Generate parse tree visitor (yes|no); default: no
visitor = yes
# Generate file dependencies (yes|no); default: no
#depend = no
# Set/override grammar-level options (<option>=<value> [<option>=value ...]); default: language=Python3
grammar-options = superClass=Abc
tokenVocab=SomeLexer
# Treat warnings as errors (yes|no); default: no
#w-error = no
# Launch StringTemplate visualizer on generated code (yes|no); default: no
#x-dbg-st = no
# Wait for STViz to close before continuing
#x-dbg-st-wait = no
# All output goes into -o dir regardless of paths/package (yes|no); default: no
#x-exact-output-dir = no
# Use the ATN simulator for all predictions (yes|no); default: no
#x-force-atn = no
# Dump lots of logging info to antlr-<timestamp>.log (yes|no); default: no
#x-log = no
A reference configuration is provided in the ``resources`` directory.
Sample
******
Besides the ``setuptools-antlr`` source code a sample project called ``foobar`` is provided in the ``samples`` directory. This sample consists of the two ANTLR grammars ``Foo`` and ``Bar``. During the execution of ``setuptools-antlr`` two Python packages will be generated into the ``foobar`` package directory containing a parser for each grammar.
To generate parsers for both grammars and build a ``foobar`` wheel package execute the following command:
::
> python setup.py antlr bdist_wheel
Raw data
{
"_id": null,
"home_page": "https://github.com/ferraith/setuptools-antlr",
"name": "setuptools-antlr",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.5",
"maintainer_email": "",
"keywords": "antlr setuptools dsl",
"author": "Andreas Schmidl",
"author_email": "Andreas.Schmidl@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/eb/75/30e004ca974397d74119d96a50ab95e32f9bcf041a3fb5826d339a50c60d/setuptools-antlr-0.4.0.tar.gz",
"platform": "any",
"description": "setuptools-antlr\n================\n\n|Build Status| |Coverage Status| |PyPI Version| |GitHub Version| |License|\n\n.. |Build Status| image:: https://travis-ci.com/ferraith/setuptools-antlr.svg\n :target: https://travis-ci.com/ferraith/setuptools-antlr\n :alt: Build Status\n\n.. |Coverage Status| image:: https://coveralls.io/repos/github/ferraith/setuptools-antlr/badge.svg?branch=master\n :target: https://coveralls.io/github/ferraith/setuptools-antlr?branch=master\n :alt: Coverage Status\n\n.. |PyPI Version| image:: https://badge.fury.io/py/setuptools-antlr.svg\n :target: https://pypi.org/project/setuptools-antlr\n :alt: PyPI Version\n\n.. |GitHub Version| image:: https://badge.fury.io/gh/ferraith%2Fsetuptools-antlr.svg\n :target: https://github.com/ferraith/setuptools-antlr/releases\n :alt: GitHub Version\n\n.. |License| image:: https://img.shields.io/github/license/ferraith/setuptools-antlr.svg\n :target: https://raw.githubusercontent.com/ferraith/setuptools-antlr/master/LICENSE\n :alt: License\n\nOverview\n--------\n\nA ``setuptools`` command for generating ANTLR based parsers.\n\nThis is an extension for `setuptools <https://pypi.org/project/setuptools/>`__ integrating the famous `ANTLR <http://www.antlr.org/>`__ parser generator into the Python packaging process. It encapsulates the Java based generator of ANTLR and provides the user a single command to control the generation process.\n\nAll command line options of ANTLR are also available through the setuptools command. The user has the choice to pass the options on the command line or configure ANTLR in a dedicated section in the ``setup.cfg`` file.\n\nANTLR grammars and its dependencies like imported grammars or token files are automatically detected. For each grammar a Python package will be generated during execution of the ``antlr`` command.\n\nInstallation\n------------\n\n``setuptools-antlr`` can be installed in various ways. To run it the following prerequisites have to be fulfilled:\n\n- Python 3.5+\n- setuptools\n- Java JRE 1.7+\n\nThe source distribution is already shipped with ANTLR 4.7.1. It isn't necessary to download ANTLR additionally.\n\nAfter installation, the used Python environment has a new setuptools command called ``antlr``.\n\nFrom Source Code\n****************\n\n::\n\n > git clone https://github.com/ferraith/setuptools-antlr.git\n > cd setuptools-antlr\n > pip install .\n\nFrom PyPI\n*********\n\n::\n\n > pip install setuptools-antlr\n\nFrom GitHub Releases\n********************\n\n::\n\n > pip install <setuptools-antlr_wheel>\n\nUsage\n-----\n\nIntegration\n***********\n\nFor a smooth user experience it's recommended to pass ``setuptools-antlr`` using the ``setup_requires`` argument of setup function. Additionally each generated parser requires the ANTLR runtime library which should be added to ``install_requires`` argument:\n\n.. code:: python\n\n setup(\n ...\n setup_requires=['setuptools-antlr'],\n install_requires=['antlr4-python3-runtime']\n ...\n )\n\nBefore generating a parser ``setuptools`` will automatically check the Python environment and download ``setuptools-antlr`` from `PyPI <https://pypi.org>`__ if it's missing. During the installation of the project package ``pip`` will install ``antlr4-python3-runtime`` into the Python environment.\n\nConfiguration\n*************\n\n``setuptools-antlr`` provides two possibilities to configure the ANTLR parser generator.\n\nAll options of ANTLR can be passed on the command line after the ``antlr`` command:\n\n::\n\n > python setup.py antlr --visitor\n\nIt's also possible to pass several options to ANTLR or execute multiple commands at once:\n\n::\n\n > python setup.py antlr --visitor --grammar-options \"superClass=Abc tokenVocab=SomeLexer\" bdist_wheel\n\nSee ``python setup.py antlr --help`` for available command line options:\n\n::\n\n > python setup.py antlr --help\n ...\n Options for 'AntlrCommand' command:\n --grammars (-g) specify grammars to generate parsers for\n --output (-o) specify directories where output is generated\n --atn generate rule augmented transition network diagrams\n --encoding specify grammar file encoding e.g. euc-jp\n --message-format specify output style for messages in antlr, gnu, vs2005\n --long-messages show exception details when available for errors and\n warnings\n --listener generate parse tree listener (default)\n --no-listener don't generate parse tree listener\n --visitor generate parse tree visitor\n --no-visitor don't generate parse tree visitor (default)\n --depend generate file dependencies\n --grammar-options set/override a grammar-level option\n --w-error treat warnings as error\n --x-dbg-st launch StringTemplate visualizer on generated code\n --x-dbg-st-wait wait for STViz to close before continuing\n --x-force-atn use the ATN simulator for all predictions\n --x-exact-output-dir output goes into -o directories regardless of paths/package\n --x-log dump lots of logging info to antlr-<timestamp>.log\n ...\n\nThe ANTLR documentation explains all `command line options <https://github.com/antlr/antlr4/blob/master/doc/tool-options.md>`__ and `grammar options <https://github.com/antlr/antlr4/blob/master/doc/options.md>`__ in detail.\n\nApart from passing options on the command line it's also possible to add a dedicated ``[antlr]`` section to ``setup.cfg``. The following example section contains all available options:\n\n.. code:: ini\n\n [antlr]\n # Specify grammars to generate parsers for; default: None\n #grammars = <grammar> [<grammar> ...]\n # Specify directories where all output is generated; default: ./\n output = default=gen\n # Generate DOT graph files that represent the internal ATN data structures (yes|no); default: no\n #atn = no\n # Specify grammar file encoding; default: utf-8\n #encoding = utf-8\n # Specify output style for messages in antlr (antlr|gnu|vs2005); default: antlr\n #message-format = antlr\n # Show exception details when available for errors and warnings (yes|no); default: no\n #long-messages = no\n # Generate a parse tree listener (yes|no); default: yes\n #listener = yes\n # Generate parse tree visitor (yes|no); default: no\n visitor = yes\n # Generate file dependencies (yes|no); default: no\n #depend = no\n # Set/override grammar-level options (<option>=<value> [<option>=value ...]); default: language=Python3\n grammar-options = superClass=Abc\n tokenVocab=SomeLexer\n # Treat warnings as errors (yes|no); default: no\n #w-error = no\n # Launch StringTemplate visualizer on generated code (yes|no); default: no\n #x-dbg-st = no\n # Wait for STViz to close before continuing\n #x-dbg-st-wait = no\n # All output goes into -o dir regardless of paths/package (yes|no); default: no\n #x-exact-output-dir = no\n # Use the ATN simulator for all predictions (yes|no); default: no\n #x-force-atn = no\n # Dump lots of logging info to antlr-<timestamp>.log (yes|no); default: no\n #x-log = no\n\nA reference configuration is provided in the ``resources`` directory.\n\nSample\n******\n\nBesides the ``setuptools-antlr`` source code a sample project called ``foobar`` is provided in the ``samples`` directory. This sample consists of the two ANTLR grammars ``Foo`` and ``Bar``. During the execution of ``setuptools-antlr`` two Python packages will be generated into the ``foobar`` package directory containing a parser for each grammar.\n\nTo generate parsers for both grammars and build a ``foobar`` wheel package execute the following command:\n\n::\n\n > python setup.py antlr bdist_wheel\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Setuptools command for generating ANTLR based parsers.",
"version": "0.4.0",
"split_keywords": [
"antlr",
"setuptools",
"dsl"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "39257ef6594b634e8bd16f70c8cdcaf5",
"sha256": "d11e38c5631bbe03c76d9d35fa8c8dd0f524ca221be61fd14ca50ae1b0a4a2ca"
},
"downloads": -1,
"filename": "setuptools_antlr-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "39257ef6594b634e8bd16f70c8cdcaf5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.5",
"size": 2084678,
"upload_time": "2019-01-27T20:58:55",
"upload_time_iso_8601": "2019-01-27T20:58:55.658081Z",
"url": "https://files.pythonhosted.org/packages/24/26/40c3800730577665ad0ba0c70eec55eee8212ccf788f3866ca7880614640/setuptools_antlr-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "160ef036e25e8eff9bd19338d2255f8f",
"sha256": "7851e3e9ac7bebe35d44f6c6e020328cf0a88ccbdeb8048dbd00f829236eab97"
},
"downloads": -1,
"filename": "setuptools-antlr-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "160ef036e25e8eff9bd19338d2255f8f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5",
"size": 2088253,
"upload_time": "2019-01-27T20:59:50",
"upload_time_iso_8601": "2019-01-27T20:59:50.835531Z",
"url": "https://files.pythonhosted.org/packages/eb/75/30e004ca974397d74119d96a50ab95e32f9bcf041a3fb5826d339a50c60d/setuptools-antlr-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2019-01-27 20:59:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "ferraith",
"github_project": "setuptools-antlr",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "coveralls",
"specs": []
},
{
"name": "pytest",
"specs": [
[
">=",
"3.6"
]
]
},
{
"name": "pytest-cov",
"specs": []
},
{
"name": "twine",
"specs": []
},
{
"name": "wheel",
"specs": []
}
],
"lcname": "setuptools-antlr"
}
JSON
