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.
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.
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.
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.
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.
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 and 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
- The Definitive ANTLR 4 Reference, 2nd Edition (Book)
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.
ParseTargetRuleParseTargetRulesParseBindRuleParseBindRulesParsePermissionBindRuleParsePermissionBindRulesParseInstruction
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.
The go-antlraci package makes use of the 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 for more information on this package.
Click the reference badge at the top of this file to learn more about this package.