https://github.com/jessecoretta/go-antlraci
Package antlraci contains ANTLR4-generated parser code based upon the ACIv3 parser/lexer grammar
https://github.com/jessecoretta/go-antlraci
aciv3 antlr4-grammar antlr4-lexer antlr4-parser experimental go golang
Last synced: 3 months ago
JSON representation
Package antlraci contains ANTLR4-generated parser code based upon the ACIv3 parser/lexer grammar
- Host: GitHub
- URL: https://github.com/jessecoretta/go-antlraci
- Owner: JesseCoretta
- License: mit
- Archived: true
- Created: 2023-08-11T04:02:56.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2023-11-19T21:16:40.000Z (over 1 year ago)
- Last Synced: 2025-02-03T22:53:37.714Z (4 months ago)
- Topics: aciv3, antlr4-grammar, antlr4-lexer, antlr4-parser, experimental, go, golang
- Language: Go
- Homepage:
- Size: 151 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# go-antlraci
[](https://godoc.org/github.com/JesseCoretta/go-antlraci)  [](https://github.com/JesseCoretta/go-antlraci/issues) [](https://github.com/JesseCoretta/JesseCoretta/blob/main/EXPERIMENTAL.md) [](https://github.com/JesseCoretta/go-antlraci/actions/workflows/go.yml) [](https://github.com/JesseCoretta/go-antlraci/releases) [](https://github.com/JesseCoretta/JesseCoretta/blob/main/DONATIONS.md)
Package antlraci contains an ANTLR4-generated codebase meant to facilitate the parsing of ACIv3 definitions. The codebase is created through use of ANTLR4 parser/lexer grammar rules that honor the complete third (3rd) version of the Access Control Instruction syntax -- a form of permission expressions favored and supported by multiple X.500/LDAP server implementations on the market today.
## Advisory
Most of the Go codebase within this repository is **AUTO-GENERATED** through ANTLR4 routines. Only a small portion was actually written, and serves only to extend more convenient functions to an importing application. All extensions and enhancements to the codebase are kept in separate files.
At NO POINT is any portion of the **AUTO-GENERATED** ANTLR4 codebase edited for any reason whatsoever.
## Status of this repository
This package, though tested and actively in-use in the wild, is fairly new and was only generated during the summer of 2023. It may not yet be suitable for _unsupervised_ mission-critical use.
Users who choose to integrate this package -- in part or in whole -- into their application(s) are advised to keep this in mind if and when issues arise, and are strongly encouraged to write sufficient unit tests to assuage any stability concerns of their own.
## Purpose of this repository
As there are some negative views in the community regarding the quality and efficiency of the Go code that ANTLR4 generates at this time, this `antlraci` package was created to keep cyclomatic penalties wholly separate from its sister package [`go-aci`](https://github.com/JesseCoretta/go-aci).
## Contributions Welcome
Practical contributions are always welcome, both in terms of the added Go codebase "enhancements" as well as contributions pertaining to the ANTLR grammar itself.
Keep in mind, however, that a significant portion of the codebase is automatically generated by ANTLR4 and is not something we can "rewrite". If issues are perceived with the automatically generated codebase (that do not pertain to a strictly ANTLR4-related bug), changes to the ACIv3 ANTLR4 grammar shall likely be necessary, and would almost certainly necessitate a regeneration of said codebase.
## ANTLR4/ACI Codebase Generation Procedure
For those interested, the following command was used to generate this codebase (not counting the custom `.go` files **added** manually):
```
$ antlr4 -Dlanguage=Go -package antlraci ACI*.g4
```
Two (2) grammar files -- [`ACIParser.g4`](https://github.com/JesseCoretta/go-antlraci/blob/main/_grammar/ACIParser.g4) and [`ACILexer.g4`](https://github.com/JesseCoretta/go-antlraci/blob/main/_grammar/ACILexer.g4) -- must be present within the directory in which the above `bash` command is executed. They have been included in this repository for reference and, optionally, use elsewhere.
In addition to the above grammar `.g4` files, the associated `.tokens` and `.interp` incarnations are also available.
For information on setting up ANTLR4 on your system, see the following resources:
- [Official ANTLR Website](http://www.antlr.org)
- The Definitive ANTLR 4 Reference, 2nd Edition (Book)
## Added Parser Helpers
Some package-level functions have been added to simplify or streamline the parsing process for individual components of an ACIv3 instruction, as well as an instruction as a whole. This negates the need for a custom visitor or listener created within the importing application.
- `ParseTargetRule`
- `ParseTargetRules`
- `ParseBindRule`
- `ParseBindRules`
- `ParsePermissionBindRule`
- `ParsePermissionBindRules`
- `ParseInstruction`
These are defined in the separate `ext.go` file, and are not generated (nor overwritten) by the ANTLR4 codebase generation system. Their use is entirely optional. Users who wish to interact strictly with the ANTLR4-generated codebase need not call these functions.
## Stack Support
The `go-antlraci` package makes use of the [`go-stackage`](https://github.com/JesseCoretta/go-stackage) package for the creation and traversal of hierarchical stack structures in which ACIv3 contexts are stored. In particular, stacks are used for the creation of BindRules instances, which can involve some very complex nested and parenthetical expressions. See the [`go-stackage` Reference](https://pkg.go.dev/github.com/JesseCoretta/go-stackage) for more information on this package.
## Usage Information
Click the reference badge at the top of this file to learn more about this package.