# McCode Grammar files
Excluding `__init__.py` and `builder.py`, the Python
contents of this folder are generated by `ANTLR`
from the grammar files, `C.g4`, `cpp.g4`, `McCommon.g4`,
`McComp.g4` and `McInstr.g4`.

As such, the generated files should not be edited by hand.
Instead, modify the grammar files, and possibly any
functions which make use of `Mc*Visitor` or `CListener`.


## Automatic generation

The (re)generation of the various language files can be performed by
calling `builder.py`, e.g.,
```console
python builder.py --verbose
```

Building the parser, visitor, and listener implementations requires
`antlr4-tools` to be installed. This can be done via
```console
pip install "antlr4-tools=0.2.1"
```
Other versions of `antlr4-tools` may work, but unannounced changes in its API
have been known to break the build process.

### ANTLR version
The version of ANTLR used in generating the required files can be
specified as a command line argument, `-v` or `--version`.
This version **must** match the version of `antlr4-python3-runtime`
used by Python, and which `mccode-antlr` depends on.

If no version is specified, the version of the installed `antlr4-python3-runtime`
is taken, such that the produced files will work with the used Python environment.

If no version is specified and `antlr4-python3-runtime` is not installed,
the value of the `${ANTLR4_TOOLS_ANTLR_VERSION}` environment variable, 
the result of querying the latest available `antlr` version on 
[maven](https://mvnrepository.com/artifact/org.antlr/antlr4),
or a version already present on the running system will be used,
in that order.

