From d7646a97e1cd25c2e315bdde9a900ef1932b1e04 Mon Sep 17 00:00:00 2001 From: Federico Tomassetti Date: Mon, 5 Feb 2024 16:46:22 +0100 Subject: [PATCH] Updating documentations for ANTLR 5 (#23) * Reword CHANGES.txt as it was not updated for over 10 years Signed-off-by: Federico Tomassetti * Removing information about obsolete targets Signed-off-by: Federico Tomassetti * Update information con contributing Signed-off-by: Federico Tomassetti * Removing information on dropped targets Signed-off-by: Federico Tomassetti --------- Signed-off-by: Federico Tomassetti --- CHANGES.txt | 582 -------------------------- CONTRIBUTING.md | 2 +- doc/ace-javascript-target.md | 255 ----------- doc/cpp-target.md | 171 -------- doc/csharp-target.md | 94 ----- doc/dart-target.md | 129 ------ doc/go-target.md | 285 ------------- doc/php-target.md | 110 ----- doc/python-target.md | 262 ------------ doc/releasing-antlr.md | 305 ++++---------- doc/swift-target.md | 175 -------- historical-contributors-agreement.txt | 330 --------------- 12 files changed, 72 insertions(+), 2628 deletions(-) delete mode 100644 CHANGES.txt delete mode 100644 doc/ace-javascript-target.md delete mode 100644 doc/cpp-target.md delete mode 100644 doc/csharp-target.md delete mode 100644 doc/dart-target.md delete mode 100644 doc/go-target.md delete mode 100644 doc/php-target.md delete mode 100644 doc/python-target.md delete mode 100644 doc/swift-target.md delete mode 100644 historical-contributors-agreement.txt diff --git a/CHANGES.txt b/CHANGES.txt deleted file mode 100644 index b2eef10540..0000000000 --- a/CHANGES.txt +++ /dev/null @@ -1,582 +0,0 @@ -**************************************************************************** -As of ANTLR 4.2.1, March 25 2014, we are no longer updating this file. Instead, -we are using the github release mechanism. For example, here is -4.2.1 release notes: - -https://github.com/antlr/antlr4/releases/tag/4.2.1 -**************************************************************************** - -ANTLR v4 Honey Badger - -January 15, 2014 - -* Unit tests for lexer actions from yesterday. -* Refactored TreeView so we can refresh tree externally w/o creating new one. - Needed for intellij plugin. - -January 14, 2014 - -* Updated serialized ATN representation of lexer actions, allowing the lexer - interpreter to execute the majority of lexer commands (#408) - -January 12, 2014 - -* Support executing precedence predicates during the SLL phase of - adaptivePredict (#401). The result is a massive performance boost for grammars - containing direct left-recursion (improvements of 5% to 1000+% have been - observed, depending on the grammar and input). - -December 29, 2013 - -* Internal change: Tool.loadGrammar() -> parseGrammar(). Tool.load()->parse() - -* Added Tool.loadGrammar(fileName) that completely parses, extracts implicit lexer, - and processes into Grammar object. Does not geneate code. Use - Grammar.getImplicitLexer() to get the lexer created during processing of - combined grammar. - -* Added Grammar.load(fileName) that creates Tool object for you. loadGrammar() - lets you create your own Tool for setting error handlers etc... - - final Grammar g = Grammar.load("/tmp/MyGrammar.g4"); - -December 19, 2013 - -* Sam: - Improved documentation for tree patterns classes - Refactored parts of the tree patterns API to simplify classes and improve encapsulation - Move ATN serializer to runtime - Use ATNDeserializer methods instead of ATNSimulator methods which are now deprecated - -* parrt: fix null pointer bug with rule "a : a;" - -November 24, 2013 - -* Ter adds tree pattern matching. Preferred interface: - - ParseTree t = parser.expr(); - ParseTreePattern p = parser.compileParseTreePattern("+0", MyParser.RULE_expr); - ParseTreeMatch m = p.match(t); - String id = m.get("ID"); - - or - - String xpath = "//blockStatement/*"; - String treePattern = "int = ;"; - ParseTreePattern p = - parser.compileParseTreePattern(treePattern, - JavaParser.RULE_localVariableDeclarationStatement); - List matches = p.findAll(tree, xpath); - -November 20, 2013 - -* Sam added method stuff like expr() that calls expr(0). Makes it possible - to call expr rule from TestRig (grun). - -November 14, 2013 - -* Added Sam's ParserInterpreter implementation that uses ATN after - deserialization. - - LexerGrammar lg = new LexerGrammar( - "lexer grammar L;\n" + - "A : 'a' ;\n" + - "B : 'b' ;\n" + - "C : 'c' ;\n"); - Grammar g = new Grammar( - "parser grammar T;\n" + - "s : (A{;}|B)* C ;\n", - lg); - - LexerInterpreter lexEngine = lg.createLexerInterpreter(new ANTLRInputStream(input)); - CommonTokenStream tokens = new CommonTokenStream(lexEngine); - ParserInterpreter parser = g.createParserInterpreter(tokens); - ParseTree t = parser.parse(g.rules.get(startRule).index); - -November 13, 2013 - -* move getChildren() from Tree into Trees (to avoid breaking change) -* Notation: - /prog/func, -> all funcs under prog at root - /prog/*, -> all children of prog at root - /*/func, -> all func kids of any root node - prog, -> prog must be root node - /prog, -> prog must be root node - /*, -> any root - *, -> any root - //ID, -> any ID in tree - //expr/primary/ID, -> any ID child of a primary under any expr - //body//ID, -> any ID under a body - //'return', -> any 'return' literal in tree - //primary/*, -> all kids of any primary - //func/*/stat, -> all stat nodes grandkids of any func node - /prog/func/'def', -> all def literal kids of func kid of prog - //stat/';', -> all ';' under any stat node - //expr/primary/!ID, -> anything but ID under primary under any expr node - //expr/!primary, -> anything but primary under any expr node - //!*, -> nothing anywhere - /!*, -> nothing at root - -September 16, 2013 - -* Updated build.xml to support v4 grammars in v4 itself; compiles XPathLexer.g4 -* Add to XPath: - Collection findAll(String xpath); - -September 11, 2013 - -* Add ! operator to XPath -* Use ANTLR v4 XPathLexer.g4 not regex -* Copy lots of find node stuff from v3 GrammarAST to Trees class in runtime. - -September 10, 2013 - -* Adding in XPath stuff. - -August 31, 2013 - -* Lots of little fixes thanks to Coverity Scan - -August 7, 2013 - -* [BREAKING CHANGE] Altered left-recursion elimination to be simpler. Now, - we use the following patterns: - - * Binary expressions are expressions which contain a recursive invocation of - the rule as the first and last element of the alternative. - - * Suffix expressions contain a recursive invocation of the rule as the first - element of the alternative, but not as the last element. - - * Prefix expressions contain a recursive invocation of the rule as the last - element of the alternative, but not as the first element. - -There is no such thing as a "ternary" expression--they are just binary -expressions in disguise. - -The right associativity specifiers no longer on the individual tokens because -it's done on alternative basis anyway. The option is now on the individual -alternative; e.g., - - e : e '*' e - | e '+' e - | e '?' e ':' e - | e '=' e - | INT - ; - -If your language uses a right-associative ternary operator, you will need -to update your grammar to include on the alternative operator. - -This also fixes #245 and fixes #268: - -https://github.com/antlr/antlr4/issues/245 -https://github.com/antlr/antlr4/issues/268 - -To smooth the transition, is still allowed on token references -but it is ignored. - -June 30, 2013 -- 4.1 release - -June 24, 2013 - -* Resize ANTLRInputStream.data after reading a file with fewer characters than - bytes -* Fix ATN created for non-greedy optional block with multiple alternatives -* Support Unicode escape sequences with indirection in JavaUnicodeInputStream - (fixes #287) -* Remove the ParserRuleContext.altNum field (fixes #288) -* PredictionContext no longer implements Iterable -* PredictionContext no longer implements Comparable -* Add the EPSILON_CLOSURE error and EPSILON_OPTIONAL warning -* Optimized usage of closureBusy set (fixes #282) - -June 9, 2013 - -* Add regression test for #239 (already passes) - -June 8, 2013 - -* Support list labels on a set of tokens (fixes #270) -* Fix associativity of XOR in Java LR grammar (fixes #280) - -June 1, 2013 - -* DiagnosticErrorListener includes rule names for each decision in its reports -* Document ANTLRErrorListener and DiagnosticErrorListener (fixes #265) -* Support '\uFFFF' (fixes #267) -* Optimize serialized ATN - -May 26, 2013 - -* Report errors that occur while lexing a grammar (fixes #262) -* Improved error message for unterminated string literals (fixes #243) - -May 24, 2013 - -* Significantly improve performance of JavaUnicodeInputStream.LA(1) - -May 20, 2013 - -* Generate Javadoc for generated visitor and listener interfaces and classes -* Fix unit tests - -May 18, 2013 - -* Group terminals in Java grammars so ATN can collapse sets -* Improved Java 7 support in Java grammars (numeric literals) -* Updated error listener interfaces -* Support detailed statistics in TestPerformance - -May 17, 2013 - -* Add JavaUnicodeInputStream to handle Unicode escapes in Java code -* Proper Unicode identifier handling in Java grammars -* Report file names with lexer errors in TestPerformance - -May 14, 2013 - -* Use a called rule stack to prevent stack overflow in LL1Analyzer -* Use 0-based indexing for several arrays in the tool -* Code simplification, assertions, documentation - -May 13, 2013 - -* Unit test updates to ensure exceptions are not hidden - -May 12, 2013 - -* Updates to TestPerformance - -May 5, 2013 - -* Updated several classes to use MurmurHash 3 hashing - -May 1, 2013 - -* Added parse tree JTree to TreeViewer (Bart Kiers) - -April 30, 2013 - -* Updated TestPerformance to support parallelization across passes - -April 24, 2013 - -* Remove unused stub class ParserATNPathFinder -* Remove ParserInterpreter.predictATN -* Remove DFA.getATNStatesAlongPath -* Encapsulate implementation methods in LexerATNSimulator and ParserATNSimulator -* Updated documentation -* Simplify creation of new DFA edges -* Fix handling of previously cached error edges -* Fix DFA created during forced-SLL parsing (PredictionMode.SLL) -* Extract methods ParserATNSimulator.getExistingTargetState and - ParserATNSimulator.computeTargetState. - -April 22, 2013 - -* Lazy initialization of ParserATNSimulator.mergeCache -* Improved hash code for DFAState -* Improved hash code with caching for ATNConfigSet -* Add new configuration parameters to TestPerformance -* Update Java LR and Java Std to support Java 7 syntax - -April 21, 2013 - -* Add new configuration parameters to TestPerformance - -April 18, 2013 - -* Must check rule transition follow states before eliminating states in - the ATN (fixes #224) -* Simplify ParserATNSimulator and improve performance by combining execDFA and - execATN and using DFA edges even after edge computation is required - -April 15, 2013 - -* Fix code in TestPerformance that clears the DFA - -April 12, 2013 - -* Improved initialization and concurrency control in DFA updates -* Fix EOF handling in edge case (fixes #218) - -April 4, 2013 - -* Improved testing of error reporting -* Fix NPE revealed by updated testing method -* Strict handling of redefined rules - prevents code generation (fixes #210) -* Updated documentation in Tool - -March 27, 2013 - -* Avoid creating empty action methods in lexer (fixes #202) -* Split serialized ATN when it exceeds Java's 65535 byte limit (fixes #76) -* Fix incorrect reports of label type conflicts across separated labeled outer - alternatives (fixes #195) -* Update Maven plugin site documentation - -March 26, 2013 - -* Fix bugs with the closureBusy set in ParserATNSimulator.closure -* Fix handling of empty options{} block (fixes #194) -* Add error 149 INVALID_LEXER_COMMAND (fixes #190) -* Add error 150 MISSING_LEXER_COMMAND_ARGUMENT -* Add error 151 UNWANTED_LEXER_COMMAND_ARGUMENT -* Updated documentation in the Parser and RecognitionException classes -* Refactored and extensively documented the ANTLRErrorStrategy interface and - DefaultErrorStrategy default implementation -* Track the number of syntax errors in Parser.notifyErrorListeners instead of in - the error strategy -* Move primary implementation of getExpectedTokens to ATN, fixes #191 -* Updated ATN documentation -* Use UUID instead of incremented integer for serialized ATN versioning - -March 7, 2013 - -* Added export to PNG feature to the parse tree viewer - -March 6, 2013 - -* Allow direct calls to left-recursive rules (fixes #161) -* Change error type 146 (EPSILON_TOKEN) to a warning (fixes #180) -* Specify locale for all format operations (fixes #158) -* Fix generation of invalid Unicode escape sequences in Java code (fixes #164) -* Do not require escape for $ in action when not followed by an ID start char - (fixes #176) - -February 23, 2013 - -* Refactoring Target-related classes to improve support for additional language - targets - -February 22, 2013 - -* Do not allow raw newline characters in literals -* Pair and Triple are immutable; Triple is not a Pair - -February 5, 2013 - -* Fix IntervalSet.add when multiple merges are required (fixes #153) - -January 29, 2013 - -* don't call process() if args aren't specified (Dave Parfitt) - -January 21, 2013 -- Release 4.0 - -* Updated PredictionContext Javadocs -* Updated Maven site documentation -* Minor tweaks in Java.stg - -January 15, 2013 - -* Tweak error messages -* (Tool) Make TokenVocabParser fields `protected final` -* Fix generated escape sequences for literals containing backslashes - -January 14, 2013 - -* Relax parser in favor of errors during semantic analysis -* Add error 145: lexer mode must contain at least one non-fragment rule -* Add error 146: non-fragment lexer rule can match the empty string - -January 11, 2013 - -* Updated error 72, 76; added 73-74 and 136-143: detailed errors about name - conflicts -* Report exact location for parameter/retval/local name conflicts -* Add error 144: multi-character literals are not allowed in lexer sets -* Error 134 now only applies to rule references in lexer sets -* Updated error messages (cleanup) -* Reduce size of _serializedATN by adding 2 to each element: new representation - avoids embedded values 0 and 0xFFFF which are common and have multi-byte - representations in Java's modified UTF-8 - -January 10, 2013 - -* Add error 135: cannot assign a value to list label: $label - (fixes antlr/antlr4#128) - -January 2, 2013 - -* Fix EOF handling (antlr/antlr4#110) -* Remove TREE_PARSER reference -* Additional validation checks in ATN deserialization -* Fix potential NPE in parser predicate evaluation -* Fix termination condition detection in full-context parsing - -January 1, 2013 - -* Updated documentation -* Minor code cleanup -* Added the `-XdbgSTWait` command line option for the Tool -* Removed method override since bug was fixed in V3 runtime - -December 31, 2012 - -* I altered Target.getTargetStringLiteralFromANTLRStringLiteral() so that - it converts \uXXXX in an ANTLR string to \\uXXXX, thus, avoiding Java's - conversion to a single character before compilation. - -December 16, 2012 - -* Encapsulate some fields in ANTLRMessage -* Remove ErrorType.INVALID -* Update error/warning messages, show all v3 compatibility messages - -December 12, 2012 - -* Use arrays instead of HashSet to save memory in SemanticContext.AND/OR -* Use arrays instead of HashSet to save memory in cached DFA -* Reduce single-operand SemanticContext.and/or operations - -December 11, 2012 - -* Add -long-messages option; only show exceptions with errors when set -* "warning treated as error" is a one-off error -* Listen for issues reported by StringTemplate, report them as warnings -* Fix template issues -* GrammarASTWithOptions.getOptions never returns null -* Use EnumSet instead of HashSet -* Use new STGroup.GROUP_FILE_EXTENSION value - -December 2, 2012 - -* Remove -Xverbose-dfa option -* Create the ParseTreeVisitor interface for all visitors, rename previous base - visitor class to AbstractParseTreeVisitor - -December 1, 2012 - -* escape [\n\r\t] in lexical error messages; e.g,: - line 2:3 token recognition error at: '\t' - line 2:4 token recognition error at: '\n' - -* added error for bad sets in lexer; e.g.: - lexer set element A is invalid (either rule ref or literal with > 1 char) - some tests in TestSets appeared to allow ~('a'|B) but it was randomly working. - ('a'|B) works, though doesn't collapse to a set. - -* label+='foo' wasn't generating good code. It was generating token type as - variable name. Now, I gen "s" for implicit labels on string literals. - -* tokens now have token and char source to draw from. - -* remove -Xsave-lexer option; log file as implicit lexer AST. - -November 30, 2012 - -* Maven updates (cleanup, unification, and specify Java 6 bootstrap classpath) - -November 28, 2012 - -* Maven updates (uber-jar, manifest details) - -November 27, 2012 - -* Maven updates (prepare for deploying to Sonatype OSS) -* Use efficient bitset tests instead of long chains of operator == - -November 26, 2012 - -* Maven updates (include sources and javadocs, fix warnings) -* Don't generate action methods for lexer rules not containing an action -* Generated action and sempred methods are private -* Remove unused / problematic methods: -** (unused) TerminalNodeImpl.isErrorNode -** (unused) RuleContext.conflictsWith, RuleContext.suffix. -** (problematic) RuleContext.hashCode, RuleContext.equals. - -November 23, 2012 - -* Updated Maven build (added master POM, cleaned up module POMs) - -November 22, 2012 - -* make sure left-recur rule translation uses token stream from correct imported file. -* actions like @after in imported rules caused inf loop. -* This misidentified scope lexer/parser: @lexer::members { } @parser::members { } - -November 18, 2012 - -* fixed: undefined rule refs caused exception -* cleanup, rm dead etypes, add check for ids that cause code gen issues -* added notion of one-off error -* added check for v3 backward incompatibilities: -** tree grammars -** labels in lexer rules -** tokens {A;B;} syntax -** tokens {A='C';} syntax -** {...}?=> gate semantic predicates -** (...)=> syntactic predicates -* Detect EOF in lexer rule - -November 17, 2012 - -* .tokens files goes in output dir like parser file. -* added check: action in lexer rules must be last element of outermost alt -* properly check for grammar/filename difference -* if labels, don't allow set collapse for - a : A # X | B ; -* wasn't checking soon enough for rule redef; now it sets a dead flag in - AST so no more walking dup. - error(51): T.g:7:0: rule s redefinition (ignoring); previous at line 3 - -November 11, 2012 - -* Change version to 4.0b4 (btw, forgot to push 4.0b3 in build.properties when - I made git tag 4.0b3...ooops). - -November 4, 2012 - -* Kill box in tree dialog box makes dialog dispose of itself - -October 29, 2012 - -* Sam fixes nongreedy more. -* -Werror added. -* Sam made speed improvement re preds in lexer. - -October 20, 2012 - -* Merged Sam's fix for nongreedy lexer/parser. lots of unit tests. A fix in - prediction ctx merge. https://github.com/parrt/antlr4/pull/99 - -October 14, 2012 - -* Rebuild how ANTLR detects SLL conflict and failover to full LL. LL is - a bit slower but correct now. Added ability to ask for exact ambiguity - detection. - -October 8, 2012 - -* Fixed a bug where labeling the alternatives of the start rule caused - a null pointer exception. - -October 1, 2012 -- 4.0b2 release - -September 30, 2012 - -* Fixed the unbuffered streams, which actually buffered everything - up by mistake. tweaked a few comments. - -* Added a getter to IntStream for the token factory - -* Added -depend cmd-line option. - -September 29, 2012 - -* no nongreedy or wildcard in parser. - -September 28, 2012 - -* empty "tokens {}" is ok now. - -September 22, 2012 - -* Rule exception handlers weren't passed to the generated code -* $ruleattribute.foo weren't handled properly -* Added -package option - -September 18, 2012 -- 4.0b1 release diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9984dc8baf..e35ce838c4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,7 @@ 4. Install and configure [EditorConfig](http://editorconfig.org/) so your text editor or IDE uses the ANTLR 5 coding style 5. [Build ANTLR 5](doc/building-antlr.md) 6. [Run the ANTLR project unit tests](doc/antlr-project-testing.md) -7. Create a [pull request](https://help.github.com/articles/using-pull-requests/) with your changes and make sure you're comparing your `dev`-derived branch in your fork to the `dev` branch from the `antlr/antlr4` repo: +7. Create a [pull request](https://help.github.com/articles/using-pull-requests/) with your changes and make sure you're comparing your `dev`-derived branch in your fork to the `dev` branch from the `antlr/antlr5` repo: diff --git a/doc/ace-javascript-target.md b/doc/ace-javascript-target.md deleted file mode 100644 index e3f33bad43..0000000000 --- a/doc/ace-javascript-target.md +++ /dev/null @@ -1,255 +0,0 @@ -# Integrating ANTLR JavaScript parsers with ACE editor - -Having the ability to parse code other than JavaScript is great, but nowadays users expect to be able to edit code with nice edit features such as keyword highlighting, indentation and brace matching, and advanced ones such as syntax checking. - -I have been through the process of integrating an ANTLR parser with ACE, the dominant code editor for web based code editing. Information about ACE can be found on their web site. - -This page describes my experience, and humbly aims to help you get started. It is not however a reference guide, and no support is provided. - -## Architecture - -The ACE editor is organized as follows - -1. The editor itself is a
which once initialized comprises a number of elements. This UI element is responsible for the display, and the generation of edit events. -1. The editor relies on a Session, which manages events and configuration. -1. The code itself is stored in a Document. Any insertion or deletion of text is reflected in the Document. -1. Keyword highlighting, indentation and brace matching are delegated to a mode. There is no direct equivalent of an ACE mode in ANTLR. While keywords are the equivalent of ANTLR lexer tokens, indentation and brace matching are edit tasks, not parsing ones. A given ACE editor can only have one mode, which corresponds to the language being edited. There is no need for ANTLR integration to support keyword highlighting, indentation and brace matching. -1. Syntax checking is delegated to a worker. This is where ANTLR integration is needed. If syntax checking is enabled, ACE asks the mode to create a worker. In JavaScript, workers run in complete isolation i.e. they don't share code or variables with other workers, or with the HTML page itself. -1. The below diagram describes how the whole system works. In green are the components *you* need to provide. You'll notice that there is no need to load ANTLR in the HTML page itself. You'll also notice that ACE maintains a document in each thread. This is done through low level events sent by the ACE session to the worker which describe the delta. Once applied to the worker document, a high level event is triggered, which is easy to handle since at this point the worker document is a perfect copy of the UI document. - - - -## Step-by-step guide - -The first thing to do is to create an editor in your html page. This is thoroughly described in the ACE documentation, so we'll just sum it up here: - -```xml - - -``` - -This should give you a working editor. You may want to control its sizing using CSS. I personally load the editor in an iframe and set its style to position: absolute, top: 0, left: 0 etc... but I'm sure you know better than me how to achieve results. - -The second thing to do is to configure the ACE editor to use your mode i.e. language configuration. A good place to start is to inherit from the built-in TextMode. The following is a very simple example, which only caters for comments, literals, and a limited subset of separators and keywords : - -```javascript -ace.define('ace/mode/my-mode',["require","exports","module","ace/lib/oop","ace/mode/text","ace/mode/text_highlight_rules", "ace/worker/worker_client" ], function(require, exports, module) { - var oop = require("ace/lib/oop"); - var TextMode = require("ace/mode/text").Mode; - var TextHighlightRules = require("ace/mode/text_highlight_rules").TextHighlightRules; - - var MyHighlightRules = function() { - var keywordMapper = this.createKeywordMapper({ - "keyword.control": "if|then|else", - "keyword.operator": "and|or|not", - "keyword.other": "class", - "storage.type": "int|float|text", - "storage.modifier": "private|public", - "support.function": "print|sort", - "constant.language": "true|false" - }, "identifier"); - this.$rules = { - "start": [ - { token : "comment", regex : "//" }, - { token : "string", regex : '["](?:(?:\\\\.)|(?:[^"\\\\]))*?["]' }, - { token : "constant.numeric", regex : "0[xX][0-9a-fA-F]+\\b" }, - { token : "constant.numeric", regex: "[+-]?\\d+(?:(?:\\.\\d*)?(?:[eE][+-]?\\d+)?)?\\b" }, - { token : "keyword.operator", regex : "!|%|\\\\|/|\\*|\\-|\\+|~=|==|<>|!=|<=|>=|=|<|>|&&|\\|\\|" }, - { token : "punctuation.operator", regex : "\\?|\\:|\\,|\\;|\\." }, - { token : "paren.lparen", regex : "[[({]" }, - { token : "paren.rparen", regex : "[\\])}]" }, - { token : "text", regex : "\\s+" }, - { token: keywordMapper, regex: "[a-zA-Z_$][a-zA-Z0-9_$]*\\b" } - ] - }; - }; - oop.inherits(MyHighlightRules, TextHighlightRules); - - var MyMode = function() { - this.HighlightRules = MyHighlightRules; - }; - oop.inherits(MyMode, TextMode); - - (function() { - - this.$id = "ace/mode/my-mode"; - - }).call(MyMode.prototype); - - exports.Mode = MyMode; -}); -``` - -Now if you store the above in a file called "my-mode.js", setting the ACE Editor becomes straightforward: - -```xml - - - -``` - -At this point you should have a working editor, able to highlight keywords. You may wonder why you need to set the tokens when you have already done so in your ANTLR lexer grammar. First, ACE expects a classification (control, operator, type...) which does not exist in ANTLR. Second, there is no need for ANTLR to achieve this, since ACE comes with its own lexer. - -Ok, now that we have a working editor comes the time where we need syntax validation. This is where the worker comes in the picture. - -Creating the worker is the responsibility of the mode you provide. So you need to enhance it with something like the following: - -```javascript -var WorkerClient = require("ace/worker/worker_client").WorkerClient; -this.createWorker = function(session) { - this.$worker = new WorkerClient(["ace"], "ace/worker/my-worker", "MyWorker", "../js/my-worker.js"); - this.$worker.attachToDocument(session.getDocument()); - - this.$worker.on("errors", function(e) { - session.setAnnotations(e.data); - }); - - this.$worker.on("annotate", function(e) { - session.setAnnotations(e.data); - }); - - this.$worker.on("terminate", function() { - session.clearAnnotations(); - }); - - return this.$worker; - -}; -``` - -The above code needs to be placed in the existing worker, after: - -```javascript -this.$id = "ace/mode/my-mode"; -``` - -Please note that the mode code runs on the UI side, not the worker side. The event handlers here are for events sent by the worker, not to the worker. - -Obviously the above won't work out of the box, because you need to provide the "my-worker.js" file. - -Creating a worker from scratch is not something I've tried. Simply put, your worker needs to handle all messages sent by ACE using the WorkerClient created by the mode. This is not a simple task, and is better delegated to existing ACE code, so we can focus on tasks specific to our language. - -What I did is I started from "mode-json.js", a rather simple worker which comes with ACE, stripped out all JSON validation related stuff out of it, and saved the remaining code in a file name "worker-base.js" which you can find [here](resources/worker-base.js). Once this done, I was able to create a simple worker, as follows: - -```javascript -importScripts("worker-base.js"); -ace.define('ace/worker/my-worker',["require","exports","module","ace/lib/oop","ace/worker/mirror"], function(require, exports, module) { - "use strict"; - - var oop = require("ace/lib/oop"); - var Mirror = require("ace/worker/mirror").Mirror; - - var MyWorker = function(sender) { - Mirror.call(this, sender); - this.setTimeout(200); - this.$dialect = null; - }; - - oop.inherits(MyWorker, Mirror); - - (function() { - - this.onUpdate = function() { - var value = this.doc.getValue(); - var annotations = validate(value); - this.sender.emit("annotate", annotations); - }; - - }).call(MyWorker.prototype); - - exports.MyWorker = MyWorker; -}); - -var validate = function(input) { - return [ { row: 0, column: 0, text: "MyMode says Hello!", type: "error" } ]; -}; -``` - -At this point, you should have an editor which displays an error icon next to the first line. When you hover over the error icon, it should display: MyMode says Hello!. Is that not a friendly worker? Yum. - -What remains to be done is have our validate function actually validate the input. Finally ANTLR comes in the picture! - -To start with, let's load ANTLR and your parser, listener etc.. - -The preferred approach for loading parser code is to bundle your parser, [as described here](javascript-target.md). -You can then load it as part of the importScripts instruction at the start of your worker code. - -Another approach is to load it using 'require'. Easy, since you could write: - -```js -var antlr4 = require('antlr4/index'); -``` - -This may work, but it's actually unreliable. The reason is that the 'require' function that comes with ACE uses a different syntax than the 'require' function used by ANTLR, which follows the NodeJS 'require' convention. -So we need to bring in a NodeJS compatible 'require' function that conforms to the NodeJS syntax. I personally use one that comes from Torben Haase's Honey project, which you can find in li/require.js. -But hey, now we're going to have 2 'require' functions not compatible with each other! Indeed, this is why you need to take special care, as follows: - -```js -// load nodejs compatible require -var ace_require = require; -require = undefined; -var Honey = { 'requirePath': ['..'] }; // walk up to js folder, see Honey docs -importScripts("../lib/require.js"); -var antlr4_require = require; -require = ace_require; -``` -Now it's safe to load antlr and the parsers generated for your language. -Assuming that your language files (generated or hand-built) are in a folder with an index.js file that calls require for each file, your parser loading code can be as simple as follows: -```js -// load antlr4 and myLanguage -var antlr4, mylanguage; -try { - require = antlr4_require; - antlr4 = require('antlr4/index'); - mylanguage = require('mylanguage/index'); -} finally { - require = ace_require; -} -``` -Please note the try-finally construct. ANTLR uses 'require' synchronously so it's perfectly safe to ignore the ACE 'require' while running ANTLR code. ACE itself does not guarantee synchronous execution, so you are much safer always switching 'require' back to 'ace_require'. - -Now detecting deep syntax errors in your code is a task for your ANTLR listener or visitor or whatever piece of code you've delegated this to. We're not going to describe this here, since it would require some knowledge of your language. However, detecting grammar syntax errors is something ANTLR does beautifully (isn't that why you went for ANTLR in the first place?). So what we will illustrate here is how to report grammar syntax errors. I have no doubt that from there, you will be able to extend the validator to suit your specific needs. -Whenever ANTLR encounters an unexpected token, it fires an error. By default, the error is routed to an error listener which simply writes to the console. -What we need to do is replace this listener by our own listener, se we can route errors to the ACE editor. First, let's create such a listener: -```js -// class for gathering errors and posting them to ACE editor -var AnnotatingErrorListener = function(annotations) { - antlr4.error.ErrorListener.call(this); - this.annotations = annotations; - return this; -}; - -AnnotatingErrorListener.prototype = Object.create(antlr4.error.ErrorListener.prototype); -AnnotatingErrorListener.prototype.constructor = AnnotatingErrorListener; - -AnnotatingErrorListener.prototype.syntaxError = function(recognizer, offendingSymbol, line, column, msg, e) { - this.annotations.push({ - row: line - 1, - column: column, - text: msg, - type: "error" - }); -}; -``` -With this, all that remains to be done is plug the listener in when we parse the code. Here is how I do it: -```js -var validate = function(input) { - var stream = CharStreams.fromString(input); - var lexer = new mylanguage.MyLexer(stream); - var tokens = new antlr4.CommonTokenStream(lexer); - var parser = new mylanguage.MyParser(tokens); - var annotations = []; - var listener = new AnnotatingErrorListener(annotations) - parser.removeErrorListeners(); - parser.addErrorListener(listener); - parser.parseMyRule(); - return annotations; -}; -``` -You know what? That's it! You now have an ACE editor that does syntax validation using ANTLR! I hope you find this useful, and simple enough to get started. -Now wait, hey! How do you debug this? Well, as usual, using Chrome, since no other browser is able to debug worker code. What a shame... diff --git a/doc/cpp-target.md b/doc/cpp-target.md deleted file mode 100644 index d4cd872a4f..0000000000 --- a/doc/cpp-target.md +++ /dev/null @@ -1,171 +0,0 @@ -# C++ - -The C++ target supports all platforms that can either run MS Visual Studio 2013 (or newer), XCode 7 (or newer) or CMake (C++11 required). All build tools can either create static or dynamic libraries, both as 64bit or 32bit arch. Additionally, XCode can create an iOS library. Also see [Antlr4 for C++ with CMake: A practical example](http://blorente.me/beyond-the-loop/Antlr-cpp-cmake/). - -## How to create a C++ lexer or parser? -This is pretty much the same as creating a Java lexer or parser, except you need to specify the language target, for example: - -``` -$ antlr4 -Dlanguage=Cpp MyGrammar.g4 -``` - -You will see that there are a whole bunch of files generated by this call. If visitor or listener are not suppressed (which is the default) you'll get: - -* MyGrammarLexer.h + MyGrammarLexer.cpp -* MyGrammarParser.h + MyGrammarParser.cpp -* MyGrammarVisitor.h + MyGrammarVisitor.cpp -* MyGrammarBaseVisitor.h + MyGrammarBaseVisitor.cpp -* MyGrammarListener.h + MyGrammarListener.cpp -* MyGrammarBaseListener.h + MyGrammarBaseListener.cpp - -## Where can I get the runtime? - -Once you've generated the lexer and/or parser code, you need to download or build the runtime. Prebuilt C++ runtime binaries for Windows (Visual Studio 2013/2015), OSX/macOS and iOS are available on the ANTLR web site: - -* http://www.antlr.org - -Use CMake to build a Linux library (works also on OSX, however not for the iOS library). - -Instead of downloading a prebuilt binary you can also easily build your own library on OSX or Windows. Just use the provided projects for XCode or Visual Studio and build it. Should work out of the box without any additional dependency. - - -## How do I run the generated lexer and/or parser? - -Putting it all together to get a working parser is really easy. Look in the [runtime/Cpp/demo](../runtime/Cpp/demo) folder for a simple example. The [README](../runtime/Cpp/demo/README.md) there describes shortly how to build and run the demo on OSX, Windows or Linux. - -## How do I create and run a custom listener? - -The generation step above created a listener and base listener class for you. The listener class is an abstract interface, which declares enter and exit methods for each of your parser rules. The base listener implements all those abstract methods with an empty body, so you don't have to do it yourself if you just want to implement a single function. Hence use this base listener as the base class for your custom listener: - -```c++ -#include - -#include "antlr4-runtime.h" -#include "MyGrammarLexer.h" -#include "MyGrammarParser.h" -#include "MyGrammarBaseListener.h" - -using namespace antlr4; - -class TreeShapeListener : public MyGrammarBaseListener { -public: - void enterKey(ParserRuleContext *ctx) override { - // Do something when entering the key rule. - } -}; - - -int main(int argc, const char* argv[]) { - std::ifstream stream; - stream.open(argv[1]); - ANTLRInputStream input(stream); - MyGrammarLexer lexer(&input); - CommonTokenStream tokens(&lexer); - MyGrammarParser parser(&tokens); - - tree::ParseTree *tree = parser.key(); - TreeShapeListener listener; - tree::ParseTreeWalker::DEFAULT.walk(&listener, tree); - - return 0; -} - -``` - -This example assumes your grammar contains a parser rule named `key` for which the `enterKey` function was generated. - -## Special cases for this ANTLR target - -There are a couple of things that only the C++ ANTLR target has to deal with. They are described here. - -### Code Generation Aspects -The code generation (by running the ANTLR4 jar) allows to specify 2 values you might find useful for better integration of the generated files into your application (both are optional): - -* A **namespace**: use the **`-package`** parameter to specify the namespace you want. -* An **export macro**: especially in VC++ extra work is required to export your classes from a DLL. This is usually accomplished by a macro that has different values depending on whether you are creating the DLL or import it. The ANTLR4 runtime itself also uses one for its classes: - -```c++ - #ifdef ANTLR4CPP_EXPORTS - #define ANTLR4CPP_PUBLIC __declspec(dllexport) - #else - #ifdef ANTLR4CPP_STATIC - #define ANTLR4CPP_PUBLIC - #else - #define ANTLR4CPP_PUBLIC __declspec(dllimport) - #endif - #endif -``` -Just like the `ANTLR4CPP_PUBLIC` macro here you can specify your own one for the generated classes using the **`-DexportMacro=...`** command-line parameter or -grammar option `options {exportMacro='...';}` in your grammar file. - -In order to create a static lib in Visual Studio define the `ANTLR4CPP_STATIC` macro in addition to the project settings that must be set for a static library (if you compile the runtime yourself). - -For gcc and clang it is possible to use the `-fvisibility=hidden` setting to hide all symbols except those that are made default-visible (which has been defined for all public classes in the runtime). - -### Compile Aspects - -When compiling generated files, you can configure a compile option according to your needs (also optional): - -* A **thread local DFA macro**: Add `-DANTLR4_USE_THREAD_LOCAL_CACHE=1` to the compilation options -will enable using thread local DFA cache (disabled by default), after that, each thread uses its own DFA. -This will increase memory usage to store thread local DFAs and redundant computation to build thread local DFAs (not too much). -The benefit is that it can improve the concurrent performance running with multiple threads. -In other words, when you find your concurent throughput is not high enough, you should consider turning on this option. - -### Memory Management -Since C++ has no built-in memory management we need to take extra care. For that we rely mostly on smart pointers, which however might cause time penalties or memory side effects (like cyclic references) if not used with care. Currently however the memory household looks very stable. Generally, when you see a raw pointer in code consider this as being managed elsewhere. You should never try to manage such a pointer (delete, assign to smart pointer etc.). - -Accordingly a parse tree is only valid for the lifetime of its parser. The parser, in turn, is only valid for the lifetime of its token stream, and so on back to the original `ANTLRInputStream` (or equivalent). To retain a tree across function calls you'll need to create and store all of these and `delete` all but the tree when you no longer need it. - -### Unicode Support -Encoding is mostly an input issue, i.e. when the lexer converts text input into lexer tokens. The parser is completely encoding unaware. - -The C++ target always expects UTF-8 input (either in a string or stream) which is then converted to UTF-32 (a char32_t array) and fed to the lexer. - -### Named Actions -In order to help customizing the generated files there are a number of additional so-called **named actions**. These actions are tight to specific areas in the generated code and allow to add custom (target specific) code. All targets support these actions - -* @parser::header -* @parser::members -* @lexer::header -* @lexer::members - -(and their scopeless alternatives `@header` and `@members`) where header doesn't mean a C/C++ header file, but the top of a code file. The content of the header action appears in all generated files at the first line. So it's good for things like license/copyright information. - -The content of a *members* action is placed in the public section of lexer or parser class declarations. Hence it can be used for public variables or predicate functions used in a grammar predicate. Since all targets support *header* + *members* they are the best place for stuff that should be available also in generated files for other languages. - -In addition to that the C++ target supports many more such named actions. Unfortunately, it's not possible to define new scopes (e.g. *listener* in addition to *parser*) so they had to be defined as part of the existing scopes (*lexer* or *parser*). The grammar in the demo application contains all of the named actions as well for reference. Here's the list: - -* **@lexer::preinclude** - Placed right before the first #include (e.g. good for headers that must appear first, for system headers etc.). Appears in both lexer h and cpp file. -* **@lexer::postinclude** - Placed right after the last #include, but before any class code (e.g. for additional namespaces). Appears in both lexer h and cpp file. -* **@lexer::context** - Placed right before the lexer class declaration. Use for e.g. additional types, aliases, forward declarations and the like. Appears in the lexer h file. -* **@lexer::declarations** - Placed in the private section of the lexer declaration (generated sections in all classes strictly follow the pattern: public, protected, private, from top to bottom). Use this for private vars etc. -* **@lexer::definitions** - Placed before other implementations in the cpp file (but after *@postinclude*). Use this to implement e.g. private types. - -For the parser there are the same actions as shown above for the lexer. In addition to that there are even more actions for visitor and listener classes: - -* **@parser::listenerpreinclude** -* **@parser::listenerpostinclude** -* **@parser::listenerdeclarations** -* **@parser::listenermembers** -* **@parser::listenerdefinitions** -* -* **@parser::baselistenerpreinclude** -* **@parser::baselistenerpostinclude** -* **@parser::baselistenerdeclarations** -* **@parser::baselistenermembers** -* **@parser::baselistenerdefinitions** -* -* **@parser::visitorpreinclude** -* **@parser::visitorpostinclude** -* **@parser::visitordeclarations** -* **@parser::visitormembers** -* **@parser::visitordefinitions** -* -* **@parser::basevisitorpreinclude** -* **@parser::basevisitorpostinclude** -* **@parser::basevisitordeclarations** -* **@parser::basevisitormembers** -* **@parser::basevisitordefinitions** - -and should be self explanatory now. Note: there is no *context* action for listeners or visitors, simply because they would be even less used than the other actions and there are so many already. diff --git a/doc/csharp-target.md b/doc/csharp-target.md deleted file mode 100644 index 1fcce06de7..0000000000 --- a/doc/csharp-target.md +++ /dev/null @@ -1,94 +0,0 @@ -# C♯ - -## Which frameworks are supported? - -The C# runtime is CLS compliant, and only requires a corresponding 3.5 .Net framework. - -In practice, the runtime has been extensively tested against: - -* Microsoft .Net 3.5 framework -* Mono .Net 3.5 framework - -No issue was found, so you should find that the runtime works pretty much against any recent .Net framework. - -## How do I get started? - -You will find full instructions on the [Git repo page for ANTLR C# runtime](https://github.com/antlr/antlr4/tree/master/runtime/CSharp). - -## How do I use the runtime from my project? - -(i.e., How do I run the generated lexer and/or parser?) - -Let's suppose that your grammar is named `MyGrammar`. The tool will generate for you the following files: - -* MyGrammarLexer.cs -* MyGrammarParser.cs -* MyGrammarListener.cs (if you have not activated the -no-listener option) -* MyGrammarBaseListener.cs (if you have not activated the -no-listener option) -* MyGrammarVisitor.cs (if you have activated the -visitor option) -* MyGrammarBaseVisitor.cs (if you have activated the -visitor option) - -Now a fully functioning code might look like the following for start rule `StartRule`: - -```csharp -using Antlr4.Runtime; -using Antlr4.Runtime.Tree; - -public void MyParseMethod() { - String input = "your text to parse here"; - ICharStream stream = CharStreams.fromString(input); - ITokenSource lexer = new MyGrammarLexer(stream); - ITokenStream tokens = new CommonTokenStream(lexer); - MyGrammarParser parser = new MyGrammarParser(tokens); - IParseTree tree = parser.StartRule(); -} -``` - -This program will work. But it won't be useful unless you do one of the following: - -* you visit the parse tree using a custom listener -* you visit the parse tree using a custom visitor -* your grammar comprises production code (like AntLR3) - -(please note that production code is target specific, so you can't have multi target grammars that include production code) - -## How do I create and run a custom listener? - -Let's suppose your MyGrammar grammar comprises 2 rules: "key" and "value". - -The antlr4 tool will have generated the following listener (only partial code shown here): - -```csharp -interface IMyGrammarParserListener : IParseTreeListener { - void EnterKey (MyGrammarParser.KeyContext context); - void ExitKey (MyGrammarParser.KeyContext context); - void EnterValue (MyGrammarParser.ValueContext context); - void ExitValue (MyGrammarParser.ValueContext context); -} -``` - -In order to provide custom behavior, you might want to create the following class: - -```csharp -class KeyPrinter : MyGrammarBaseListener { - // override default listener behavior - void ExitKey (MyGrammarParser.KeyContext context) { - Console.WriteLine("Oh, a key!"); - } -} -``` - -In order to execute this listener, you would simply add the following lines to the above code: - - -```csharp -... -IParseTree tree = parser.StartRule() - only repeated here for reference -KeyPrinter printer = new KeyPrinter(); -ParseTreeWalker.Default.Walk(printer, tree); -``` - -Further information can be found from The Definitive ANTLR Reference book. - -The C# implementation of ANTLR is as close as possible to the Java one, so you shouldn't find it difficult to adapt the examples for C#. See also [Sam Harwell's alternative C# target](https://github.com/tunnelvisionlabs/antlr4cs) - diff --git a/doc/dart-target.md b/doc/dart-target.md deleted file mode 100644 index ee3668775a..0000000000 --- a/doc/dart-target.md +++ /dev/null @@ -1,129 +0,0 @@ -# ANTLR4 Runtime for Dart - -From version 4.9 onwards antlr's dart generated code is null sound safety compatible and sets the minimum dart sdk version to 2.12.0. - -### First steps - -#### 1. Install ANTLR4 - -[The getting started guide](https://github.com/antlr/antlr5/blob/main/doc/getting-started.md) -should get you started. - -#### 2. Install the Dart ANTLR runtime - -Each target language for ANTLR has a runtime package for running parser -generated by ANTLR4. The runtime provides a common set of tools for using your parser. - -Install the runtime with the same version as the main ANTLR tool: - -Add this to your package's pubspec.yaml file: -```yaml -... -dependencies: - antlr4: -... -``` - -#### 3. Generate your parser - -You use the ANTLR4 "tool" to generate a parser. These will reference the ANTLR -runtime, installed above. - -Suppose you're using a UNIX system and have set up an alias for the ANTLR4 tool -as described in [the getting started guide](https://github.com/antlr/antlr5/blob/main/doc/getting-started.md). -To generate your Dart parser, run the following command: - -```shell script -antlr4 -Dlanguage=Dart MyGrammar.g4 -``` - -For a full list of antlr4 tool options, please visit the -[tool documentation page](https://github.com/antlr/antlr5/blob/main/doc/tool-options.md). - -### Complete example - -Suppose you're using the JSON grammar from https://github.com/antlr/grammars-v4/tree/master/json. - -Then, invoke `antlr4 -Dlanguage=Dart JSON.g4`. The result of this is a -collection of `.dart` including: - -* JsonLexer.dart -* JsonParser.dart -* JsonBaseListener.dart -* JsonListener.dart (if you have not activated the -no-listener option) -* JsonVisitor.dart (if you have activated the -visitor option) - -We'll write a small main func to call the generated parser/lexer -(assuming they are separate). This one writes out the encountered -`ParseTreeContext`'s: - -```dart -import 'package:antlr4/antlr4.dart'; -import 'package:my_project/JSONParser.dart'; -import 'package:my_project/JSONLexer.dart'; - -class TreeShapeListener implements ParseTreeListener { - @override - void enterEveryRule(ParserRuleContext ctx) { - print(ctx.text); - } - - @override - void exitEveryRule(ParserRuleContext node) { - } - - @override - void visitErrorNode(ErrorNode node) { - } - - @override - void visitTerminal(TerminalNode node) { - } -} - -void main(List args) async { - JSONLexer.checkVersion(); - JSONParser.checkVersion(); - final input = await InputStream.fromPath(args[0]); - final lexer = JSONLexer(input); - final tokens = CommonTokenStream(lexer); - final parser = JSONParser(tokens); - parser.addErrorListener(DiagnosticErrorListener()); - final tree = parser.json(); - ParseTreeWalker.DEFAULT.walk(TreeShapeListener(), tree); -} -``` - -Create a `example.json` file: -```json -{"a":1} -``` - -Parse the input file: - -```shell script -dart bin/main.dart example.json -``` - -The expected output is: - -``` -{"a":1} -{"a":1} -{"a":1} -"a":1 -1 -``` - -### Debug - -We have some logs in place that can ease the debugging process, in order to turn these logs on you can enable the following environment declarations: - -- ANTLR_LEXER_DEBUG -- ANTLR_LEXER_DFA_DEBUG -- ANTLR_PARSER_DEBUG -- ANTLR_PARSER_LIST_ATN_DECISIONS_DEBUG -- ANTLR_PARSER_DFA_DEBUG -- ANTLR_PARSER_RETRY_DEBUG - -If you're using flutter, you can define these variables by adding an `--dart-define` arguments, eg. `flutter run --dart-define LEXER_DEBUG=false` diff --git a/doc/go-target.md b/doc/go-target.md deleted file mode 100644 index be5bab9661..0000000000 --- a/doc/go-target.md +++ /dev/null @@ -1,285 +0,0 @@ -# ANTLR4 Language Target, Runtime for Go - -### Changes from ANTLR 4.12.0 - -Please see [Changes in ANTLR Go runtimes](go-changes.md), but in summary: - - The Go runtime is now stored in the repo `antlr4-go/antlr` - change your import, remove the old location from - `go.mod` and use `go get github.com/antlr4-go/antlr` - - There are some new `@actions` for adding to the generated import statements and recognizer structure - - The recognizer rules are no longer called via an interface, for performance reasons - - Memory usage improvements - - Performance improvements - - Documentation in true Go format - - Git tags now work correctly with go tools - -### Removal of non v4 code - -Prior to the release of the v4 tagged runtime, the source code for the Go runtime module existed at -`runtime/Go/antlr`, which is the pre-v4 version of the code, and also under `runtime/Go/antlr/v4`. If your project -was not using modules, you could merely sync to the latest hash in the master branch and use the code. This has changed. - -As of the current release, the source code for the Go runtime module has been moved to its own repo in its own -GitHub organization. As of now, you can still use the code without modules, but you must use the code -in the repo at https://github.com/antlr4-go/antlr instead of the code in the main ANTLR repo. - -This is for historic reasons as the code was originally written before modules were a -thing, and the go runtime source was - and the maintainer's version still is - a part of the monorepo -that is `antlr/antlr4/...`. - -Note that I am unable to properly deprecate the go.mod in the non-V4 directory, for hte same reason that I -cannot use tag the v4 module at this depth in the source tree. - -We strongly advise you to use modules, though it is not required. See below for more information. - -ANTLR Go Maintainer: [Jim Idle](https://github.com/jimidle) - Email: [jimi@idle.ws](mailto:jimi@idle.ws) - -### First steps - -#### 1. Install ANTLR4 - -See: [The getting started guide](getting-started.md). - -#### 2. Get the Go ANTLR runtime - -Each target language for ANTLR has a runtime package for running a recognizer generated by ANTLR4. -The runtime provides a common set of tools for using your parser/lexer. Note that if you have existing projects and have -yet to replace the `v1.x.x` modules with the `v4` modules, then you can skip ahead to the section *Upgrading to v4 -from earlier versions* - -The Go runtime uses modules and has a version path of `/v4` to stay in sync with the runtime versions of all the other -runtimes and the tool itself. - -Setup is the same as any other module based project: - -```bash -$ cd mymodproject -$ go mod init mymodproject -``` - -After which, you can use go get, to get the latest release version of the ANTLR v4 runtime using: - -```bash -go get github.com/antlr4-go/antlr -``` - -If your project was already using the v4 runtime from the main ANTLR repo, then you can upgrade to the latest release -by removing the `github.com/antlr/antlr4/runtime/Go/antlr/v4` reference in your module, and changing the associated -import in your project code. The following script may be useful in changing your imports: - -```shell -find . -type f \ - -name '*.go' \ - -exec sed -i -e 's,github.com/antlr/antlr4/runtime/Go/antlr/v4,github.com/antlr4-go/antlr/v4,g' {} \; -``` -Note that the import package still imports with the final path as `antlr`, so only the import statement itself needs to -change. - -If you are already using the repo and import `github.com/antlr4-go/antlr/v4` then you can upgrade to the latest version -using the standard. - -```shell -go get -u github.com/antlr4-go/antlr -``` - -If you have not yet upgraded existing projects to the `/v4` module path, consult the section *Upgrading to v4 -from earlier versions* - -The ANTLR runtime has only one external transient dependency, and that is part of the go system itself: - -``` -golang.org/x/exp -``` - -A complete list of releases can be found on [the release page](https://github.com/antlr/antlr4/releases). The Go -runtime will be tagged using standard Go tags, so release 4.13.1 in the `antlr4-go/antlr` repo, will be tagged with -`v4.13.1` and go get will pick that up from the ANTLR repo. - -#### 3. Configuring `go generate` in your project - -In order to promote the use of repeatable builds, it is often useful to add the latest tool jar to your project's -repo and configure a `generate.sh` and `generate.go` file. You can of course globally alias the java command required to run the -tool. Your own CI and dev environment will guide you. - -Here is how you can configure `go generate` for your project, assuming that you follow the general recommendation to -place the ANTLR grammar files in their own package in your project structure. Here is a general template as a starting point: - -``` - . - ├── myproject - ├── parser - │ ├── mygrammar.g4 - │ ├── antlr-4.13.1-complete.jar - │ ├── generate.go - │ └── generate.sh - ├── parsing # Generated code goes here - │ └── error_listeners.go - ├── go.mod - ├── go.sum - ├── main.go - └── main_test.go -``` - -Make sure that the package statement in your grammar file(s) reflects the go package the go code will be generated in. -The `generate.go` file then looks like this: - -```golang - package parser - - //go:generate ./generate.sh -``` - -And the `generate.sh` file will look similar to this: - -```shell - #!/bin/sh - - alias antlr4='java -Xmx500M -cp "./antlr-4.13.1-complete.jar:$CLASSPATH" org.antlr.v5.Tool' - antlr4 -Dlanguage=Go -no-visitor -package parsing *.g4 -``` - -From the command line at the root of your package - the location of the `go.mod` file - you can then simply issue the command: - -```shell - go generate ./... -``` - -If you have not yet run a `go get`, you can now run `go mod tidy` and update your - -#### 4. Generate your parser manually - -You use the ANTLR4 "tool" to generate a parser. These will reference the ANTLR runtime, installed above. - -Suppose you're using a UNIX system and have set up an alias for the ANTLR4 tool as described in -[the getting started guide](getting-started.md). - -To generate your go parser, you'll need to invoke: - -```shell - antlr4 -Dlanguage=Go MyGrammar.g4 -``` - -For a full list of antlr4 tool options, please visit the [tool documentation page](tool-options.md). - -### Upgrading to `/v4` from the default path - -*NB: While switching to new module path would normally imply that the public interface for the runtime has changed, this is -not actually the case - you will not need to change your existing code to upgrade. The main point of the repo change is so -that git tagging works with the ANTLR Go runtime and the go tools.* - -Prior to release v4.11.0 the Go runtime shipped with a module but the module had no version path. This meant that -the tags in the ANTLR repo did not work, as any tag above `v1` must refer to a matching module path. -So the command `go get github.com/antlr/antlr4/runtime/Go/antlr` would just bring in -whatever was the `HEAD` of the master branch. While this *kind of* worked, it is obviously subject to problems and does -not fit properly with the idiomatic ways of Go. - -As of v4.13.0 the runtime code exists in its own repo, `github.com/antlr4-go/antlr`, and is correctly tagged. -However, this means you need to perform a few simple actions in order to upgrade to the `/v4` path. - - - Firstly, make sure that you are using an ANTLR tool jar with a version number of 4.13.0 or greater. - - Next you replace any mention of the old (default) path to ANTLR in your go source files. - - If using modules, remove any existing reference to the ANTLR Go runtime - - Now regenerate your grammar files either manually or using `go generate ./...` (see above) - - Consider whether you can move to using modules in your project - -A quick way to replace the original module path references is to use this script from your module's base directory: - -```shell -find . -type f \ - -name '*.go' \ - -exec sed -i -e 's,github.com/antlr/antlr4/runtime/Go/antlr,github.com/antlr4-go/antlr/v4,g' {} \; -``` - -After performing the steps above, and you are using modules issuing: - -```shell -go mod tidy -``` -Should fix up your `go.mod` file to reference only the `v4` version of the ANTLR Go runtime: - -```shell -require github.com/antlr/antlr4/runtime/Go/antlr/v4 v4.13.0 -``` - -From this point on, your go mod commands will work correctly with the ANTLR repo and upgrades and downgrades will work -as you expect. As will branch version such as @dev - -### Referencing the Go ANTLR runtime - -You can reference the go ANTLR runtime package like this: - -```golang -import "github.com/antlr4-go/antlr/v4" -``` - -### Complete example - -Suppose you're using the JSON grammar from https://github.com/antlr/grammars-v4/tree/master/json placed in the parser -directory and have initialized your `go mod` file. - -Then, invoke `antlr4 -Dlanguage=Go JSON.g4`. The result of this is a collection of .go files in the `parser` directory including: -``` -json_parser.go -json_base_listener.go -json_lexer.go -json_listener.go -``` - -Another common option to the ANTLR tool is `-visitor`, which generates a parse tree visitor, but we won't be doing that here. -For a full list of antlr4 tool options, please visit the [tool documentation page](tool-options.md). - -We'll write a small main func to call the generated parser/lexer (assuming they are separate). This one writes out the -encountered `ParseTreeContext`'s. Assuming the generated parser code is in the `parser` directory relative to this code: - -```golang -package main - -import ( - "github.com/antlr4-go/antlr/v4" - "./parser" // Note that with modules you may not be able to use a relative immport path - "os" - "fmt" -) - -type TreeShapeListener struct { - *parser.BaseJSONListener -} - -func NewTreeShapeListener() *TreeShapeListener { - return new(TreeShapeListener) -} - -func (this *TreeShapeListener) EnterEveryRule(ctx antlr.ParserRuleContext) { - fmt.Println(ctx.GetText()) -} - -func main() { - input, _ := antlr.NewFileStream(os.Args[1]) - lexer := parser.NewJSONLexer(input) - stream := antlr.NewCommonTokenStream(lexer,0) - p := parser.NewJSONParser(stream) - p.AddErrorListener(antlr.NewDiagnosticErrorListener(true)) - tree := p.Json() - antlr.ParseTreeWalkerDefault.Walk(NewTreeShapeListener(), tree) -} -``` - -Fix up your `go.mod` file: - -```shell -go mod tidy -``` - -This one expects the input to be passed on the command line: - -``` -go run test.go input -``` - -The output is: - -``` -{"a":1} -{"a":1} -"a":1 -1 -``` diff --git a/doc/php-target.md b/doc/php-target.md deleted file mode 100644 index 29860aa5b9..0000000000 --- a/doc/php-target.md +++ /dev/null @@ -1,110 +0,0 @@ -# ANTLR4 Runtime for PHP - -### First steps - -#### 1. Install ANTLR4 - -[The getting started guide](https://github.com/antlr/antlr5/blob/main/doc/getting-started.md) -should get you started. - -#### 2. Install the PHP ANTLR runtime - -Each target language for ANTLR has a runtime package for running parser -generated by ANTLR4. The runtime provides a common set of tools for using your parser. - -Install the runtime with Composer: - -```bash -composer require antlr/antlr4-php-runtime -``` - -#### 3. Generate your parser - -You use the ANTLR4 "tool" to generate a parser. These will reference the ANTLR -runtime, installed above. - -Suppose you're using a UNIX system and have set up an alias for the ANTLR4 tool -as described in [the getting started guide](https://github.com/antlr/antlr5/blob/main/doc/getting-started.md). -To generate your PHP parser, run the following command: - -```bash -antlr4 -Dlanguage=PHP MyGrammar.g4 -``` - -For a full list of antlr4 tool options, please visit the -[tool documentation page](https://github.com/antlr/antlr5/blob/main/doc/tool-options.md). - -### Complete example - -Suppose you're using the JSON grammar from https://github.com/antlr/grammars-v4/tree/master/json. - -Then, invoke `antlr4 -Dlanguage=PHP JSON.g4`. The result of this is a -collection of `.php` files in the `parser` directory including: -``` -JsonParser.php -JsonBaseListener.php -JsonLexer.php -JsonListener.php -``` - -Another common option to the ANTLR tool is `-visitor`, which generates a parse -tree visitor, but we won't be doing that here. For a full list of antlr4 tool -options, please visit the [tool documentation page](tool-options.md). - -We'll write a small main func to call the generated parser/lexer -(assuming they are separate). This one writes out the encountered -`ParseTreeContext`'s: - -```php -getText(); - } -} - -$input = InputStream::fromPath($argv[1]); -$lexer = new JSONLexer($input); -$tokens = new CommonTokenStream($lexer); -$parser = new JSONParser($tokens); -$parser->addErrorListener(new DiagnosticErrorListener()); -$tree = $parser->json(); - -ParseTreeWalker::default()->walk(new TreeShapeListener(), $tree); -``` - -Create a `example.json` file: -```json -{"a":1} -``` - -Parse the input file: - -``` -php json.php example.json -``` - -The expected output is: - -``` -{"a":1} -{"a":1} -"a":1 -1 -``` diff --git a/doc/python-target.md b/doc/python-target.md deleted file mode 100644 index d5ea08f233..0000000000 --- a/doc/python-target.md +++ /dev/null @@ -1,262 +0,0 @@ -# Python 3 - -## Requirements - -You will need to install Python and Pip, version 3.6 or better. -See https://www.python.org/downloads/ -and https://www.geeksforgeeks.org/how-to-install-pip-on-windows/. - -## A simple example targeting Python3 - -An example of a parser for the Python3 target consists of the following files. -* An Antlr4 grammar, e.g., Expr.g4: - ```antlr - grammar Expr; - start_ : expr (';' expr)* EOF; - expr : atom | ('+' | '-') expr | expr '**' expr | expr ('*' | '/') expr | expr ('+' | '-') expr | '(' expr ')' | atom ; - atom : INT ; - INT : [0-9]+ ; - WS : [ \t\n\r]+ -> skip ; - ``` -* Driver.py: -The driver code opens a file, creates a lexer, token stream, -and parser, then calls the parser. - ```python - import sys - from antlr4 import * - from ExprLexer import ExprLexer - from ExprParser import ExprParser - from VisitorInterp import VisitorInterp - - def main(argv): - input_stream = FileStream(argv[1]) - lexer = ExprLexer(input_stream) - stream = CommonTokenStream(lexer) - parser = ExprParser(stream) - tree = parser.start_() - - if __name__ == '__main__': - main(sys.argv) - ``` -* requirements.txt: -This file contains a list of the -required packages for the program. Required -packages are downloaded by `pip`. The file -must include a reference to the Antlr Python3 runtime. - ``` - antlr4-python3-runtime==4.13.0 - ``` -* A build script, e.g., build.sh: -You should provide a script that builds the program. - ``` - pip install -r requirements.txt - antlr4 -Dlanguage=Python3 Expr.g4 - ``` -_It is vital that the versions for the -Antlr tool used to generate the parser -and the Antlr Python3 runtime match. -E.g., 4.13.0. Using build files will help -eliminate common errors from happening._ - -_For a list of antlr4 tool options, please visit [ANTLR Tool Command Line Options](https://github.com/antlr/antlr5/blob/main/doc/tool-options.md)._ -* Input, e.g., input.txt: - ``` - -(1 + 2)/3; - 1; - 2+3; - 8*9 - ``` -* A run script, which runs your program. - ``` - python Driver.py input.txt - ``` - -## Parse tree traversal - -Tree traversal is used to implement -[static](https://en.wikipedia.org/wiki/Static_program_analysis) or [dynamic](https://en.wikipedia.org/wiki/Dynamic_program_analysis) -program analysis. -Antlr generates two types of tree traversals: visitors and listeners. - -Understanding when to choose a visitor versus a listener is a good idea. -For further information, see https://tomassetti.me/listeners-and-visitors/. - -A visitor is the best choice when computing only a single [synthesized attribute](https://en.wikipedia.org/wiki/Attribute_grammar#Synthesized_attributes) -or when you want to control the order of parse tree nodes visited. -Alternatively, a listener is the best choice when computing both synthesized -and [inherited attributes](https://en.wikipedia.org/wiki/Attribute_grammar#Inherited_attributes). - -In many situations, they are interchangeable. - -### Visitors - -Antlr visitors generally implement a post-order tree walk. If you write -`visit...` methods, the method must contain code to visit the children -in the order you want. For a post-order tree walk, visit the children first. - -To implement a visitor, add the `-visitor` option to the `antlr4` command. -Create a class that inherits from the generated visitor, -then add `visit` methods that implement the analysis. Your driver code -should call the `visit()` method for the root of the parse tree. - -For example, the following code implements an expression evaluator for the Expr.g4 grammar using a visitor. - -* Driver.py: - ```python - import sys - from antlr4 import * - from ExprLexer import ExprLexer - from ExprParser import ExprParser - from VisitorInterp import VisitorInterp - - def main(argv): - input_stream = FileStream(argv[1]) - lexer = ExprLexer(input_stream) - stream = CommonTokenStream(lexer) - parser = ExprParser(stream) - tree = parser.start_() - if parser.getNumberOfSyntaxErrors() > 0: - print("syntax errors") - else: - vinterp = VisitorInterp() - vinterp.visit(tree) - - if __name__ == '__main__': - main(sys.argv) - ``` -* VisitorInterp.py: - ```python - import sys - from antlr4 import * - from ExprParser import ExprParser - from ExprVisitor import ExprVisitor - - class VisitorInterp(ExprVisitor): - def visitAtom(self, ctx:ExprParser.AtomContext): - return int(ctx.getText()) - - def visitExpr(self, ctx:ExprParser.ExprContext): - if ctx.getChildCount() == 3: - if ctx.getChild(0).getText() == "(": - return self.visit(ctx.getChild(1)) - op = ctx.getChild(1).getText() - v1 = self.visit(ctx.getChild(0)) - v2 = self.visit(ctx.getChild(2)) - if op == "+": - return v1 + v2 - if op == "-": - return v1 - v2 - if op == "*": - return v1 * v2 - if op == "/": - return v1 / v2 - return 0 - if ctx.getChildCount() == 2: - opc = ctx.getChild(0).getText() - if opc == "+": - return self.visit(ctx.getChild(1)) - if opc == "-": - return - self.visit(ctx.getChild(1)) - return 0 - if ctx.getChildCount() == 1: - return self.visit(ctx.getChild(0)) - return 0 - - def visitStart_(self, ctx:ExprParser.Start_Context): - for i in range(0, ctx.getChildCount(), 2): - print(self.visit(ctx.getChild(i))) - return 0 - ``` - -### Listeners - -Antlr listeners perform an LR tree traversal. `enter` and `exit` methods are -called during the tranversal. A parse tree node is visited twice, first for -the `enter` method, then the `exit` method after all children have been walked. - -To implement a listener, add the `-listener` option to the `antlr4` command. -Add a class that inherits from the generated listener -with code that implements the analysis. - -The following example implements an expression evaluator using a listener. - -* Driver.py: - ```python - import sys - from antlr4 import * - from ExprLexer import ExprLexer - from ExprParser import ExprParser - from ListenerInterp import ListenerInterp - - def main(argv): - input_stream = FileStream(argv[1]) - lexer = ExprLexer(input_stream) - stream = CommonTokenStream(lexer) - parser = ExprParser(stream) - tree = parser.start_() - if parser.getNumberOfSyntaxErrors() > 0: - print("syntax errors") - else: - linterp = ListenerInterp() - walker = ParseTreeWalker() - walker.walk(linterp, tree) - - if __name__ == '__main__': - main(sys.argv) - ``` - * ListenerInterp.py: - ```python - import sys - from antlr4 import * - from ExprParser import ExprParser - from ExprListener import ExprListener - - class ListenerInterp(ExprListener): - def __init__(self): - self.result = {} - - def exitAtom(self, ctx:ExprParser.AtomContext): - self.result[ctx] = int(ctx.getText()) - - def exitExpr(self, ctx:ExprParser.ExprContext): - if ctx.getChildCount() == 3: - if ctx.getChild(0).getText() == "(": - self.result[ctx] = self.result[ctx.getChild(1)] - else: - opc = ctx.getChild(1).getText() - v1 = self.result[ctx.getChild(0)] - v2 = self.result[ctx.getChild(2)] - if opc == "+": - self.result[ctx] = v1 + v2 - elif opc == "-": - self.result[ctx] = v1 - v2 - elif opc == "*": - self.result[ctx] = v1 * v2 - elif opc == "/": - self.result[ctx] = v1 / v2 - else: - ctx.result[ctx] = 0 - elif ctx.getChildCount() == 2: - opc = ctx.getChild(0).getText() - if opc == "+": - v = self.result[ctx.getChild(1)] - self.result[ctx] = v - elif opc == "-": - v = self.result[ctx.getChild(1)] - self.result[ctx] = - v - elif ctx.getChildCount() == 1: - self.result[ctx] = self.result[ctx.getChild(0)] - - def exitStart_(self, ctx:ExprParser.Start_Context): - for i in range(0, ctx.getChildCount(), 2): - print(self.result[ctx.getChild(i)]) - ``` - -Further information can be found from the ANTLR 4 definitive guide. - -## Examples - -The examples from the ANTLR 4 book converted to Python are [here](https://github.com/jszheng/py3antlr4book). - -There are many examples of grammars that target the Python3 target in the -[grammars-v4 Github repository](https://github.com/antlr/grammars-v4). diff --git a/doc/releasing-antlr.md b/doc/releasing-antlr.md index 0decde0279..da5d9ce845 100644 --- a/doc/releasing-antlr.md +++ b/doc/releasing-antlr.md @@ -7,106 +7,76 @@ Do this or make a PR: ```bash -cd ~/antlr/code/antlr4 +cd ~/antlr/code/antlr5 git checkout master git merge dev ``` ### Turn on DCO Enforcement -As of 4.10.1, we will be using the Linux DCO not the previous contributors license agreement that required signing the file. Now, we use the DCO and contributors must use `-s` on each commit to the branch associated with a pull request. +For ANTLR5 we will be using the Linux DCO. Contributors must use `-s` on each commit to the branch associated with a pull request. See [GitHub App DCO](https://github.com/apps/dco). -Make sure this feature is turned on for the `antlr4` repo upon release. +Make sure this feature is turned on for the `antlr5` repo upon release. ### Delete existing release tag Wack any existing tag as mvn will create one and it fails if already there. ``` -$ git tag -d 4.13.1 -$ git push origin :refs/tags/4.13.1 -$ git push upstream :refs/tags/4.13.1 +$ git tag -d 1.0.0 +$ git push origin :refs/tags/1.0.0 +$ git push upstream :refs/tags/1.0.0 ``` -### Go release tags - -*I don't think this is necessary anymore as we have moved it release branch to https://github.com/antlr4-go/antlr* - -It seems that [Go needs a `v` in the release git tag](https://go.dev/ref/mod#glos-version) so make sure that we double up with 4.13.1 and v4.13.1. - -``` -$ git tag -a runtime/Go/antlr/v4/v4.13.1 -m "Go runtime module only" -$ git push upstream runtime/Go/antlr/v4/v4.13.1 -$ git push origin runtime/Go/antlr/v4/v4.13.1 -``` - - ## Bump version in code and other files There are a number of files that require inversion number be updated. -Here is a simple script to display any line from the critical files with, say, `4.11.1` in it. Here's an example run of the script: +Here is a simple script to display any line from the critical files with, say, `1.1.0` in it. Here's an example run of the script: ```bash -~/antlr/code/antlr4 $ python scripts/update_antlr_version.py 4.10 4.11.0 -Updating ANTLR version from 4.10 to 4.11.0 -Set ANTLR repo root (default ~/antlr/code/antlr4): -Perform antlr4 `mvn clean` and wipe build dirs Y/N? (default no): -Ok, not cleaning antlr4 dir -4.10 appears on 2 lines so _not_ updating /tmp/antlr4/runtime/JavaScript/package-lock.json -4.10 not in /tmp/antlr4/doc/releasing-antlr.md +~/antlr/code/antlr5 $ python scripts/update_antlr_version.py 1.0 1.1.0 +Updating ANTLR version from 1.0 to 1.1.0 +Set ANTLR repo root (default ~/antlr/code/antlr5): +Perform antlr5 `mvn clean` and wipe build dirs Y/N? (default no): +Ok, not cleaning antlr5 dir +1.0 appears on 2 lines so _not_ updating /tmp/antlr5/runtime/JavaScript/package-lock.json +1.0 not in /tmp/antlr5/doc/releasing-antlr.md ``` Make sure this file doesn't have `-SNAPSHOT` when releasing! ``` -runtime/Java/src/org/antlr/v4/runtime/RuntimeMetaData.java +runtime/Java/src/org/antlr/v5/runtime/RuntimeMetaData.java ``` It's also worth doing a quick check to see if you find any other references to a version: ```bash mvn clean -find . -type f -exec grep -l '4\.12.0' {} \; | grep -v -E '\.o|\.a|\.jar|\.dylib|node_modules/|\.class|tests/|CHANGELOG|\.zip|\.gz|.iml|.svg' +find . -type f -exec grep -l '1\.2.0' {} \; | grep -v -E '\.o|\.a|\.jar|\.dylib|node_modules/|\.class|tests/|CHANGELOG|\.zip|\.gz|.iml|.svg' ``` Commit to repository. -### PHP runtime - -We only have to copy the PHP runtime into the ANTLR repository to run the unittests. But, we still need to bump the version to 4.13.1 in `~/antlr/code/antlr-php-runtime/src/RuntimeMetaData.php` in the separate repository, commit, and push. - -``` -cd ~/antlr/code/antlr-php-runtime/src -git checkout dev # Should be the default -git pull origin dev -... vi RuntimeMetaData.php ... -git commit -a -m "Update PHP Runtime to latest version" -git push origin dev -git checkout master -git pull origin master -git merge dev -git push origin master -``` - ## Build XPath parsers This section addresses a [circular dependency regarding XPath](https://github.com/antlr/antlr4/issues/3600). In the java target I avoided a circular dependency (gen 4.13.1 parser for XPath using 4.13.1 which needs it to build) by hand building the parser: runtime/Java/src/org/antlr/v4/runtime/tree/xpath/XPath.java. Probably we won't have to rerun this for the patch releases, just major ones that alter the ATN serialization. ```bash -cd ~/antlr/code/antlr4/runtime/Cpp/runtime/src/tree/xpath -java -cp ":/Users/parrt/.m2/repository/org/antlr/antlr4/4.13.1-SNAPSHOT/antlr4-4.13.1-SNAPSHOT-complete.jar:$CLASSPATH" org.antlr.v5.Tool -Dlanguage=Cpp XPathLexer.g4 +cd ~/antlr/code/antlr5/runtime/Cpp/runtime/src/tree/xpath +java -cp ":/Users/parrt/.m2/repository/org/antlr/antlr5/4.13.1-SNAPSHOT/antlr5-4.13.1-SNAPSHOT-complete.jar:$CLASSPATH" org.antlr.v5.Tool -Dlanguage=Cpp XPathLexer.g4 -cd ~/antlr/code/antlr4/runtime/CSharp/src/Tree/Xpath -java -cp ":/Users/parrt/.m2/repository/org/antlr/antlr4/4.13.1-SNAPSHOT/antlr4-4.13.1-SNAPSHOT-complete.jar:$CLASSPATH" org.antlr.v5.Tool -Dlanguage=CSharp XPathLexer.g4 +cd ~/antlr/code/antlr5/runtime/CSharp/src/Tree/Xpath +java -cp ":/Users/parrt/.m2/repository/org/antlr/antlr5/4.13.1-SNAPSHOT/antlr5-4.13.1-SNAPSHOT-complete.jar:$CLASSPATH" org.antlr.v5.Tool -Dlanguage=CSharp XPathLexer.g4 -cd ~/antlr/code/antlr4/runtime/Python3/tests/expr -java -cp ":/Users/parrt/.m2/repository/org/antlr/antlr4/4.13.1-SNAPSHOT/antlr4-4.13.1-SNAPSHOT-complete.jar:$CLASSPATH" org.antlr.v5.Tool -Dlanguage=Python3 Expr.g4 -cd ~/antlr/code/antlr4/runtime/Python3/src/antlr4/xpath -java -cp ":/Users/parrt/.m2/repository/org/antlr/antlr4/4.13.1-SNAPSHOT/antlr4-4.13.1-SNAPSHOT-complete.jar:$CLASSPATH" org.antlr.v5.Tool -Dlanguage=Python3 XPathLexer.g4 +cd ~/antlr/code/antlr5/runtime/Python3/tests/expr +java -cp ":/Users/parrt/.m2/repository/org/antlr/antlr5/4.13.1-SNAPSHOT/antlr5-4.13.1-SNAPSHOT-complete.jar:$CLASSPATH" org.antlr.v5.Tool -Dlanguage=Python3 Expr.g4 +cd ~/antlr/code/antlr5/runtime/Python3/src/antlr5/xpath +java -cp ":/Users/parrt/.m2/repository/org/antlr/antlr5/4.13.1-SNAPSHOT/antlr5-4.13.1-SNAPSHOT-complete.jar:$CLASSPATH" org.antlr.v5.Tool -Dlanguage=Python3 XPathLexer.g4 ``` ## Maven Repository Settings @@ -156,7 +126,7 @@ Here is the file template ## Maven deploy snapshot -The goal is to get a snapshot, such as `4.13.1-SNAPSHOT`, to the staging server: [antlr4 tool](https://oss.sonatype.org/content/repositories/snapshots/org/antlr/antlr4/4.13.1-SNAPSHOT/) and [antlr4 java runtime](https://oss.sonatype.org/content/repositories/snapshots/org/antlr/antlr4-runtime/4.13.1-SNAPSHOT/). +The goal is to get a snapshot, such as `1.0.0-SNAPSHOT`, to the staging server: [antlr5 tool](https://oss.sonatype.org/content/repositories/snapshots/org/antlr/antlr5/4.13.1-SNAPSHOT/) and [antlr5 java runtime](https://oss.sonatype.org/content/repositories/snapshots/org/antlr/antlr5-runtime/4.13.1-SNAPSHOT/). Do this: @@ -164,19 +134,19 @@ Do this: $ mvn install -DskipTests # seems required to get the jar files visible to maven $ mvn deploy -DskipTests ... -Uploading: https://oss.sonatype.org/content/repositories/snapshots/org/antlr/antlr4-tool-testsuite/maven-metadata.xml -Uploaded: https://oss.sonatype.org/content/repositories/snapshots/org/antlr/antlr4-tool-testsuite/maven-metadata.xml (388 B at 0.9 KB/sec) +Uploading: https://oss.sonatype.org/content/repositories/snapshots/org/antlr/antlr5-tool-testsuite/maven-metadata.xml +Uploaded: https://oss.sonatype.org/content/repositories/snapshots/org/antlr/antlr5-tool-testsuite/maven-metadata.xml (388 B at 0.9 KB/sec) [INFO] ------------------------------------------------------------------------ [INFO] Reactor Summary: [INFO] -[INFO] ANTLR 4 ............................................ SUCCESS [ 4.073 s] -[INFO] ANTLR 4 Runtime .................................... SUCCESS [ 13.828 s] -[INFO] ANTLR 4 Tool ....................................... SUCCESS [ 14.032 s] -[INFO] ANTLR 4 Maven plugin ............................... SUCCESS [ 6.547 s] -[INFO] ANTLR 4 Runtime Test Annotations ................... SUCCESS [ 2.519 s] -[INFO] ANTLR 4 Runtime Test Processors .................... SUCCESS [ 2.385 s] -[INFO] ANTLR 4 Runtime Tests (4th generation) ............. SUCCESS [ 15.276 s] -[INFO] ANTLR 4 Tool Tests ................................. SUCCESS [ 2.233 s] +[INFO] ANTLR 5 ............................................ SUCCESS [ 4.073 s] +[INFO] ANTLR 5 Runtime .................................... SUCCESS [ 13.828 s] +[INFO] ANTLR 5 Tool ....................................... SUCCESS [ 14.032 s] +[INFO] ANTLR 5 Maven plugin ............................... SUCCESS [ 6.547 s] +[INFO] ANTLR 5 Runtime Test Annotations ................... SUCCESS [ 2.519 s] +[INFO] ANTLR 5 Runtime Test Processors .................... SUCCESS [ 2.385 s] +[INFO] ANTLR 5 Runtime Tests (4th generation) ............. SUCCESS [ 15.276 s] +[INFO] ANTLR 5 Tool Tests ................................. SUCCESS [ 2.233 s] [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ @@ -211,7 +181,7 @@ export GPG_TTY=$(tty) You should see 0x37 in generated .class files after 0xCAFEBABE; see [Java SE 11 = 55 (0x37 hex)](https://en.wikipedia.org/wiki/Java_class_file): ```bash -~/antlr/code/antlr4 $ od -h tool/target/classes/org/antlr/v4/Tool.class |head -1 +~/antlr/code/antlr5 $ od -h tool/target/classes/org/antlr/v5/Tool.class |head -1 0000000 feca beba 0000 3700 ed04 0207 0a9d 0100 ^^ ``` @@ -219,7 +189,7 @@ You should see 0x37 in generated .class files after 0xCAFEBABE; see [Java SE 11 Also verify run time is 1.8: ```bash -od -h runtime/Java/target/classes/org/antlr/v4/runtime/Token.class | head -1 +od -h runtime/Java/target/classes/org/antlr/v5/runtime/Token.class | head -1 0000000 feca beba 0000 3400 2500 0007 0722 2300 ``` @@ -227,18 +197,18 @@ It will start out by asking you the version number: ``` ... -What is the release version for "ANTLR 4"? (org.antlr:antlr4-master) 4.13.1: : 4.13.1 -What is the release version for "ANTLR 4 Runtime"? (org.antlr:antlr4-runtime) 4.13.1: : -What is the release version for "ANTLR 4 Tool"? (org.antlr:antlr4) 4.13.1: : -What is the release version for "ANTLR 4 Maven plugin"? (org.antlr:antlr4-maven-plugin) 4.13.1: : -What is the release version for "ANTLR 4 Runtime Test Generator"? (org.antlr:antlr4-runtime-testsuite) 4.13.1: : -What is the release version for "ANTLR 4 Tool Tests"? (org.antlr:antlr4-tool-testsuite) 4.13.1: : -What is SCM release tag or label for "ANTLR 4"? (org.antlr:antlr4-master) antlr4-master-4.13.1: : 4.13.1 -What is the new development version for "ANTLR 4"? (org.antlr:antlr4-master) 4.13.2-SNAPSHOT: +What is the release version for "ANTLR 5"? (org.antlr:antlr5-master) 1.1.1: : 1.1.1 +What is the release version for "ANTLR 5 Runtime"? (org.antlr:antlr5-runtime) 1.1.1: : +What is the release version for "ANTLR 5 Tool"? (org.antlr:antlr5) 1.1.1: : +What is the release version for "ANTLR 5 Maven plugin"? (org.antlr:antlr5-maven-plugin) 1.1.1: : +What is the release version for "ANTLR 5 Runtime Test Generator"? (org.antlr:antlr5-runtime-testsuite) 1.1.1: : +What is the release version for "ANTLR 5 Tool Tests"? (org.antlr:antlr5-tool-testsuite) 1.1.1: : +What is SCM release tag or label for "ANTLR 5"? (org.antlr:antlr5-master) antlr5-master-1.1.1: : 1.1.1 +What is the new development version for "ANTLR 5"? (org.antlr:antlr5-master) 1.1.2-SNAPSHOT: ... ``` -Maven will go through your pom.xml files to update versions from 4.13.1-SNAPSHOT to 4.13.1 for release and then to 4.13.2-SNAPSHOT after release, which is done with: +Maven will go through your pom.xml files to update versions from 1.1.1-SNAPSHOT to 1.1.1 for release and then to 1.1.2-SNAPSHOT after release, which is done with: ```bash mvn release:perform -Darguments="-DskipTests" @@ -252,9 +222,9 @@ Now, go here: and on the left click "Staging Repositories". You click the staging repo and close it, then you refresh, click it and release it. It's done when you see it here: -    [https://oss.sonatype.org/service/local/repositories/releases/content/org/antlr/antlr4-runtime/4.13.1/antlr4-runtime-4.13.1.jar](https://oss.sonatype.org/service/local/repositories/releases/content/org/antlr/antlr4-runtime/4.13.1/antlr4-runtime-4.13.1.jar) +    [https://oss.sonatype.org/service/local/repositories/releases/content/org/antlr/antlr5-runtime/1.1.1/antlr5-runtime-1.1.1.jar](https://oss.sonatype.org/service/local/repositories/releases/content/org/antlr/antlr5-runtime/4.13.1/antlr5-runtime-4.13.1.jar) -All releases should be here: [https://repo1.maven.org/maven2/org/antlr/antlr4-runtime](https://repo1.maven.org/maven2/org/antlr/antlr4-runtime). +All releases should be here: [https://repo1.maven.org/maven2/org/antlr/antlr5-runtime](https://repo1.maven.org/maven2/org/antlr/antlr5-runtime). ## Deploying Targets @@ -265,155 +235,22 @@ All releases should be here: [https://repo1.maven.org/maven2/org/antlr/antlr4-ru (I think this has to be run before the unit test can run locally as it installs the global lib) ```bash -cd ~/antlr/code/antlr4/runtime/JavaScript +cd ~/antlr/code/antlr5/runtime/JavaScript rm -rf node_modules # seems we might need this later but try it here npm update npm install npm run build npm login # asks for username/password/2FA (npmjs.com) -npm publish # don't put antlr4 on there or it will try to push the old version for some reason +npm publish # don't put antlr5 on there or it will try to push the old version for some reason ``` Move (and zip) target to website: ```bash cd src -zip -r ~/antlr/sites/website-antlr4/download/antlr-javascript-runtime-4.13.1.zip . -``` - -### CSharp - -As of writing, you can only release from a Windows box, because Visual Studio for Mac can only build the netstandard2.0 version - -**Install the pre-requisites** - -You need 'msbuild' and `nuget` to be installed. - -**Creating the signed assembly** - -cd ~/antlr/code/antlr4/runtime/CSharp/src -dotnet build -c Release Antlr4.csproj - -check that the bin/Release folder contains both the netstandard2.0 and the net45 builds -the binaries are already signed, but it's worth double checking - -sn -v bin/Release/netstandard2.0/Antlr4.Runtime.Standard.dll -sn -v bin/Release/net45/Antlr4.Runtime.Standard.dll - -both should say the dll is valid - -**Publishing to NuGet** - -You need to be a NuGet owner for "ANTLR 4 Standard Runtime" -As a registered NuGet user, you can then manually upload the package here: [https://www.nuget.org/packages/manage/upload](https://www.nuget.org/packages/manage/upload) - -Alternately, you can publish from the cmd line. You need to get your NuGet key from [https://www.nuget.org/account#](https://www.nuget.org/account#) and then from the cmd line, you can then type: - -```cmd -cd bin/Release -nuget push Antlr4.Runtime.Standard..nupkg -Source https://www.nuget.org/api/v2/package -``` - -### Python - -The Python target gets deployed with `twine` for Python 3. - -First, set up `~/.pypirc` with tight privileges: - -```bash -beast:~ $ ls -l ~/.pypirc --rw------- 1 parrt staff 267 Jul 15 17:02 /Users/parrt/.pypirc -``` - -``` -[distutils] # this tells distutils what package indexes you can push to -index-servers = - pypi - pypitest - -[pypi] -username: parrt -password: xxx - -[pypitest] -username: parrt -password: xxx -``` - -Then run the python build and upload: - -```bash -cd ~/antlr/code/antlr4/runtime/Python3 -python -m build -# assume you have ~/.pypirc set up -twine upload dist/antlr4-python3-runtime-.tar.gz dist/antlr4_python3_runtime--py3-none-any.whl -``` - -There are links to the artifacts in [download.html](http://www.antlr.org/download.html) already. - -### C++ - -The C++ target is the most complex one, because it addresses multiple platforms, which require individual handling. We have 4 scenarios to cover: - -* **Windows**: static and dynamic libraries for the VC++ runtime 2017 or 2019 (corresponding to Visual Studio 2017 or 2019) + header files. All that in 32 and 64bit, debug + release. -* **MacOS**: static and dynamic release libraries + header files. -* **iOS**: no prebuilt binaries, but just a zip of the source, including the XCode project to build everything from source. -* **Linux**: no prebuilt binaries, but just a zip of the source code, including the cmake file to build everything from source there. - -In theory we could also create a library for iOS, but that requires to sign it, which depends on an active iOS developer account. So we leave this up to the ANTLR user to build the iOS lib, like we do for Linux builds. - -For each platform there's a deployment script which generates zip archives and copies them to the target folder. The Windows deployment script must be run on a machine with VS 2013 + VS 2015 installed. The Mac script must be run on a machine with XCode 7+ installed. The source script can be executed on any Linux or Mac box. - -On a Mac (with XCode 7+ installed): - -```bash -cd ~/antlr/code/antlr4/runtime/Cpp -./deploy-macos.sh -cp antlr4-cpp-runtime-macos.zip ~/antlr/sites/website-antlr4/download/antlr4-cpp-runtime-4.13.1-macos.zip -``` - -On any Mac or Linux machine: - -```bash -cd ~/antlr/code/antlr4/runtime/Cpp -./deploy-source.sh -cp antlr4-cpp-runtime-source.zip ~/antlr/sites/website-antlr4/download/antlr4-cpp-runtime-4.13.1-source.zip -``` - -On a Windows machine the build scripts checks if VS 2017 and/or VS 2019 are installed and builds binaries for each, if found. This script requires 7z to be installed (http://7-zip.org then do `set PATH=%PATH%;C:\Program Files\7-Zip\` from DOS not powershell). - -```bash -cd ~/antlr/code/antlr4/runtime/Cpp -deploy-windows.cmd Community -cp antlr4-cpp-runtime-vs2019.zip ~/antlr/sites/website-antlr4/download/antlr4-cpp-runtime-4.13.1-vs2019.zip -``` - -Move target to website (**_rename to a specific ANTLR version first if needed_**): - -```bash -pushd ~/antlr/sites/website-antlr4/download -git add antlr4-cpp-runtime-4.13.1-macos.zip -git add antlr4-cpp-runtime-4.13.1-windows.zip -git add antlr4-cpp-runtime-4.13.1-source.zip -git commit -a -m 'update C++ runtime' -git push origin gh-pages -popd +zip -r ~/antlr/sites/website-antlr5/download/antlr-javascript-runtime-4.13.1.zip . ``` -### Dart - -Install Dart SDK from https://dart.dev/get-dart - -Push to pub.dev - -```bash -cd ~/antlr/code/antlr4/runtime/Dart -dart pub publish -``` - -It will warn that no change log found for the new version. -Otherwise enter `N` to ignore the warning. - ## Update website ### javadoc for runtime and tool @@ -421,7 +258,7 @@ Otherwise enter `N` to ignore the warning. Jars are in: ``` -~/.m2/repository/org/antlr/antlr4-runtime/4.13.1/antlr4-runtime-4.13.1 +~/.m2/repository/org/antlr/antlr5-runtime/1.1.1/antlr5-runtime-1.1.1 ``` ### Update version and copy jars / api @@ -429,45 +266,45 @@ Jars are in: Copy javadoc and java jars to website using this script: ```bash -cd ~/antlr/code/antlr4 -python scripts/deploy_to_website.py 4.13.0 4.13.1 +cd ~/antlr/code/antlr5 +python scripts/deploy_to_website.py 1.1.0 1.1.1 ``` Output: ```bash -Updating ANTLR version from 4.13.0 to 4.13.1 -Set ANTLR website root (default /Users/parrt/antlr/sites/website-antlr4): +Updating ANTLR version from 1.1.0 to 1.1.1 +Set ANTLR website root (default /Users/parrt/antlr/sites/website-antlr5): Version string updated. Please commit/push: Javadoc copied: - api/Java updated from antlr4-runtime-4.13.1-javadoc.jar - api/JavaTool updated from antlr4-4.13.1-javadoc.jar + api/Java updated from antlr5-runtime-1.1.1-javadoc.jar + api/JavaTool updated from antlr5-1.1.1-javadoc.jar Jars copied: - antlr-4.13.1-complete.jar - antlr-runtime-4.13.1.jar + antlr-1.1.1-complete.jar + antlr-runtime-1.1.1.jar Please look for and add new api files!! Then MANUALLY commit/push: -git commit -a -m 'Update website, javadoc, jars to 4.13.1' +git commit -a -m 'Update website, javadoc, jars to 1.1.1' git push origin gh-pages ``` Once it's done, you must do the following manually: ``` -cd ~/antlr/sites/website-antlr4 -git commit -a -m 'Update website, javadoc, jars to 4.13.1' +cd ~/antlr/sites/website-antlr5 +git commit -a -m 'Update website, javadoc, jars to 1.1.1' git push origin gh-pages ``` @@ -475,13 +312,13 @@ git push origin gh-pages Then copy to website: ```bash -cd ~/antlr/sites/website-antlr4/api +cd ~/antlr/sites/website-antlr5/api git checkout gh-pages git pull origin gh-pages cd Java -jar xvf ~/.m2/repository/org/antlr/antlr4-runtime/4.13.1/antlr4-runtime-4.13.1-javadoc.jar +jar xvf ~/.m2/repository/org/antlr/antlr5-runtime/1.1.1/antlr5-runtime-1.1.1-javadoc.jar cd ../JavaTool -jar xvf ~/.m2/repository/org/antlr/antlr4/4.13.1/antlr4-4.13.1-javadoc.jar +jar xvf ~/.m2/repository/org/antlr/antlr5/1.1.1/antlr5-1.1.1-javadoc.jar git commit -a -m 'freshen api doc' git push origin gh-pages ``` diff --git a/doc/swift-target.md b/doc/swift-target.md deleted file mode 100644 index 1a96f39d0b..0000000000 --- a/doc/swift-target.md +++ /dev/null @@ -1,175 +0,0 @@ -# ANTLR4 Language Target, Runtime for Swift - -## Performance Note - -To use ANTLR4 Swift target in production environment, make sure to turn on compiler optimizations by following [these instructions](https://github.com/apple/swift-package-manager/blob/main/Documentation/Usage.md#setting-the-build-configuration) if you use SwiftPM to build your project. - -If you are using Xcode to build your project, it's unlikely you will not use `release` build for production build. - -Conclusion is, you need to turn on `release` mode (which will have all the optimization pre configured for you) so the ANTLR4 Swift target can have reasonable parsing speed. - -## Install ANTLR4 - -Make sure you have the ANTLR -installed. [The getting started guide](getting-started.md) should get -you started. - -## Create a Swift lexer or parser -This is pretty much the same as creating a Java lexer or parser, -except you need to specify the language target, for example: - -``` -$ antlr4 -Dlanguage=Swift MyGrammar.g4 -``` - -If you integrate this as a build step inside Xcode, then you should use the -"gnu" message format to have any error messages parsed by Xcode. You may -also want to use the `-o` option to put the autogenerated files in a -separate subdirectory. - -``` -antlr4 -Dlanguage=Swift -message-format gnu -o Autogen MyGrammar.g4 -``` - -For a full list of antlr4 tool options, please visit the -[tool documentation page](tool-options.md). - -## Build your Swift project with ANTLR runtime - -### Note - -We use __boot.py__ script located at the root of the Swift runtime folder -`antlr4/runtime/Swift` to provide additional support for both Xcode-based -projects and SPM-based projects. Below sections are organized for both of -the flavors. If you want to quickly get started, try: - -``` -python boot.py --help -``` - -for information about this script. - -### Xcode Projects - -Note that even if you are otherwise using ANTLR from a binary distribution, -you should compile the ANTLR Swift runtime from source, because the Swift -language does not yet have a stable ABI. - -ANTLR uses Swift Package Manager to generate Xcode project files. - -#### Download source code for ANTLR - -``` -git clone https://github.com/antlr/antlr4 -``` - -#### Generate Xcode project for ANTLR runtime - -The `boot.py` script includes a wrapper around `swift package -generate-xcodeproj`. Use this to generate `Antlr4.xcodeproj` for the ANTLR -Swift runtime. (using _swift package generate-xcodeproj_ is not recommended) -since the project is dependent on some parser files generated by _boot.py_. - -``` -cd antlr4/runtime/Swift -python boot.py --gen-xcodeproj -``` - -#### Import ANTLR Swift runtime into your project - -Open your own project in Xcode. - -Open Finder in the `runtime/Swift` directory: - -``` -# From antlr4/runtime/Swift -open . -``` - -Drag `Antlr4.xcodeproj` into your project. - -After this is done, your Xcode project navigator will be something like the -screenshot below. In this example, your own project is "Smalltalk", and you -will be able to see `Antlr4.xcodeproj` shown as a contained project. - - - -#### Edit the build settings if necessary - -Swift Package Manager currently does not support iOS, watchOS, or tvOS. If -you wish to build for those platforms, you will need to alter the project -build settings manually. - -#### Add generated parser and lexer to project - -Make sure the parsers/lexers -generated in __step 2__ are added to the project. To do this, you can -drag the generated files from Finder to the Xcode IDE. Remember to -check __Copy items if needed__ to make sure the files are actually -moved into the project folder instead of symbolic links (see the -screenshot below). After moving you will be able to see your files in -the project navigator. Make sure that the Target Membership settings -are correct for your project. - - - -#### Add the ANTLR Swift runtime as a dependency - -Select your own project in Xcode and go to the Build Phases settings panel. -Add the ANTLR runtime under __Target Dependencies__ and __Link Binary With -Libraries__. - - - -#### Build your project - -The runtime and generated grammar should now build correctly. - -### Swift Package Manager Projects - -Add Antlr4 as a dependency to your `Package.swift` file. For more information, please see the [Swift Package Manager documentation](https://github.com/apple/swift-package-manager/tree/master/Documentation). - - -```swift -.package(url: "https://github.com/antlr/antlr4", from: "4.13.1") -``` - -## Swift access levels - -You may use the `accessLevel` option to control the access levels on generated -code. This option can either be specified with `-DaccessLevel=value` on -the `antlr4` command line, or inside your `.g4` file like this: - -``` -options { - accessLevel = 'value'; -} -``` - -By default (with the `accessLevel` option unspecified) the generated code -uses the following access levels: - -* `open` for anything that you can feasibly extend with subclassing: -the generated parser, lexer, and context classes, the the listener and -visitor base classes, and all their accessor and setter functions. -* `public` for anything that should not be subclassed, but otherwise is -useful to client code: protocols, initializers, and static definitions such -as the lexer tokens, symbol names, and so on. -* `internal` or `private` for anything that should not be accessed directly. - -If you specify `accessLevel = 'public'` then all items that are `open` by -default will use `public` instead. Otherwise, the behavior is the same as -the default. - -If you specify `accessLevel = ''` or `accessLevel='internal'` then all items -that are `open` or `public` by default will use Swift's default (internal) -access level instead. - -Those are the only supported values for `accessLevel` when using the Swift -code-generator. - -We recommend using `accessLevel = ''`. Even if you are creating a parser -as part of a library, you would usually want to wrap it in an API of your -own and keep the ANTLR-generated parser internal to your module. You -only need to use the less restrictive access levels if you need to expose -the parser directly as part of your own module's API. diff --git a/historical-contributors-agreement.txt b/historical-contributors-agreement.txt deleted file mode 100644 index 3ed11c57ca..0000000000 --- a/historical-contributors-agreement.txt +++ /dev/null @@ -1,330 +0,0 @@ -ANTLR Project Contributors Certification of Origin and Rights - -All contributors to ANTLR v4 must formally agree to abide by this -certificate of origin by signing on the bottom with their github -userid, full name, email address (you can obscure your e-mail, but it -must be computable by human), and date. - -By signing this agreement, you are warranting and representing that -you have the right to release code contributions or other content free -of any obligations to third parties and are granting Terence Parr and -ANTLR project contributors, henceforth referred to as The ANTLR -Project, a license to incorporate it into The ANTLR Project tools -(such as ANTLRWorks and StringTemplate) or related works under the BSD -license. You understand that The ANTLR Project may or may not -incorporate your contribution and you warrant and represent the -following: - -1. I am the creator of all my contributions. I am the author of all - contributed work submitted and further warrant and represent that - such work is my original creation and I have the right to license - it to The ANTLR Project for release under the 3-clause BSD - license. I hereby grant The ANTLR Project a nonexclusive, - irrevocable, royalty-free, worldwide license to reproduce, - distribute, prepare derivative works, and otherwise use this - contribution as part of the ANTLR project, associated - documentation, books, and tools at no cost to The ANTLR Project. - -2. I have the right to submit. This submission does not violate the - rights of any person or entity and that I have legal authority over - this submission and to make this certification. - -3. If I violate another's rights, liability lies with me. I agree to - defend, indemnify, and hold The ANTLR Project and ANTLR users - harmless from any claim or demand, including reasonable attorney - fees, made by any third party due to or arising out of my violation - of these terms and conditions or my violation of the rights of - another person or entity. - -4. I understand and agree that this project and the contribution are - public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license indicated in the file. - -I have read this agreement and do so certify by adding my signoff to -the end of the following contributors list. - -CONTRIBUTORS: - -YYYY/MM/DD, github id, Full name, email -2012/07/12, parrt, Terence Parr, parrt@antlr.org -2012/09/18, sharwell, Sam Harwell, sam@tunnelvisionlabs.com -2012/10/10, stephengaito, Stephen Gaito, stephen@percepitsys.co.uk -2012/11/23, maguro, Alan Cabrera, adc@toolazydogs.com -2013/01/29, metadave, Dave Parfitt, diparfitt@gmail.com -2013/03/06, bkiers, Bart Kiers, bkiers@gmail.com -2013/08/20, cayhorstmann, Cay Horstmann, cay@horstmann.com -2014/03/18, aphyr, Kyle Kingsbury, aphyr@aphyr.com -2014/06/07, ericvergnaud, Eric Vergnaud, eric.vergnaud@wanadoo.fr -2014/07/04, jimidle, Jim Idle, jimi@Idle.ws -2014/01/01, danmclaughlin, Dan McLaughlin, dan.mclaughlin@gmail.com -2014/09/04. jeduden, Jan-Eric Duden, jeduden@gmail.com -2014/09/27, petrbel, Petr Bělohlávek, antlr@petrbel.cz -2014/10/18, sergiusignacius, Sérgio Silva, serge.a.silva@gmail.com -2014/10/26, bdkearns, Brian Kearns, bdkearns@gmail.com -2014/10/27, michaelpj, Michael Peyton Jones, michaelpj@gmail.com -2015/01/29, TomLottermann, Thomas Lottermann, tomlottermann@gmail.com -2015/02/15, pavlo, Pavlo Lysov, pavlikus@gmail.com -2015/03/07, RedTailedHawk, Lawrence Parker, larry@answerrocket.com -2015/04/03, rljacobson, Robert Jacobson, rljacobson@gmail.com -2015/04/06, ojakubcik, Ondrej Jakubcik, ojakubcik@gmail.com -2015/04/29, jszheng, Jinshan Zheng, zheng_js@hotmail.com -2015/05/08, ViceIce, Michael Kriese, michael.kriese@gmx.de -2015/05/09, lkraz, Luke Krasnoff, luke.krasnoff@gmail.com -2015/05/12, Pursuit92, Josh Chase, jcjoshuachase@gmail.com -2015/05/20, peturingi, Pétur Ingi Egilsson, petur@petur.eu -2015/05/27, jcbrinfo, Jean-Christophe Beaupré, jcbrinfo@users.noreply.github.com -2015/06/29, jvanzyl, Jason van Zyl, jason@takari.io -2015/08/18, krzkaczor, Krzysztof Kaczor, krzysztof@kaczor.io -2015/09/18, worsht, Rajiv Subrahmanyam, rajiv.public@gmail.com -2015/09/24, HSorensen, Henrik Sorensen, henrik.b.sorensen@gmail.com -2015/10/06, brwml, Bryan Wilhelm, bryan.wilhelm@microsoft.com -2015/10/08, fedotovalex, Alex Fedotov, me@alexfedotov.com -2015/10/12, KvanTTT, Ivan Kochurkin, ivan.kochurkin@gmail.com -2015/10/21, martin-probst, Martin Probst, martin-probst@web.de -2015/10/21, hkff, Walid Benghabrit, walid.benghabrit@mines-nantes.fr -2015/11/12, cooperra, Robbie Cooper, cooperra@users.noreply.github.com -2015/11/25, abego, Udo Borkowski, ub@abego.org -2015/12/17, sebadur, Sebastian Badur, sebadur@users.noreply.github.com -2015/12/23, pboyer, Peter Boyer, peter.b.boyer@gmail.com -2015/12/24, dtymon, David Tymon, david.tymon@gmail.com -2016/02/18, reitzig, Raphael Reitzig, reitzig[at]cs.uni-kl.de -2016/03/10, mike-lischke, Mike Lischke, mike@lischke-online.de -2016/03/27, beardlybread, Bradley Steinbacher, bradley.j.steinbacher@gmail.com -2016/03/29, msteiger, Martin Steiger, antlr@martin-steiger.de -2016/03/28, gagern, Martin von Gagern, gagern@ma.tum.de -2016/07/10, twz123, Tom Wieczorek, tom.wieczorek@zalando.de -2016/07/20, chrisheller, Chris Heller, chris.heller.greyheller@gmail.com -2016/07/20, nburles, Nathan Burles, nburles@gmail.com -2016/07/20, kosl90, Li Liqiang, kos1990l@gmail.com -2016/07/27, timoc, Tim O'Callaghan, timo@linux.com -2016/07/26, nic30, Michal Orsák, michal.o.socials@gmail.com -2016/07/18, willfaught, Will Faught, will.faught@gmail.com -2016/08/08, wjkohnen, Wolfgang Johannes Kohnen, wjkohnen-go-antlr@ko-sys.com -2016/08/11, BurtHarris, Ralph "Burt" Harris, Burt_Harris_antlr4@azxs.33mail.com -2016/08/19, andjo403, Andreas Jonson, andjo403@hotmail.com -2016/09/27, harriman, Kurt Harriman, harriman@acm.org -2016/10/13, cgudrian, Christian Gudrian, christian.gudrian@gmx.de -2016/10/13, nielsbasjes, Niels Basjes, niels@basjes.nl -2016/10/21, FloorGoddijn, Floor Goddijn, floor.goddijn[at]aimms.com -2016/11/01, RYDB3RG, Kai Stammerjohann, RYDB3RG@users.noreply.github.com -2016/11/05, runner-mei, meifakun, runner.mei@gmail.com -2016/11/15, hanjoes, Hanzhou Shi, hanzhou87@gmail.com -2016/11/16, sridharxp, Sridharan S, aurosridhar@gmail.com -2016/11/06, NoodleOfDeath, Thom Morgan, github@bytemeapp.com -2016/11/01, sebkur, Sebastian Kürten, sebastian@topobyte.de -2016/04/13, renatahodovan, Renata Hodovan, reni@inf.u-szeged.hu -2016/11/05, ewanmellor, Ewan Mellor, github@ewanmellor.org -2016/11/06, janyou, Janyou, janyou.antlr@outlook.com -2016/11/20, marcohu, Marco Hunsicker, antlr@hunsicker.de -2016/09/02, lygav, Vladimir (Vladi) Lyga, lyvladi@gmail.com -2016/09/23, ghosthope, Dmitry Shakhtanov, sudstrike@gmail.com -2016/11/25, MrSampson, Oliver Sampson, olsam@quickaudio.com -2016/11/29, millergarym, Gary Miller, miller.garym@gmail.com -2016/11/29, wxio, Gary Miller, gm@wx.io -2016/11/29, Naios, Denis Blank, naios@users.noreply.github.com -2016/12/01, samtatasurya, Samuel Tatasurya, xemradiant@gmail.com -2016/12/03, redxdev, Samuel Bloomberg, sam@redxdev.com -2016/12/11, Gaulouis, Gaulouis, gaulouis.com@gmail.com -2016/12/22, akosthekiss, Akos Kiss, akiss@inf.u-szeged.hu -2016/12/24, adrpo, Adrian Pop, adrian.pop@liu.se -2017/01/11, robertbrignull, Robert Brignull, robertbrignull@gmail.com -2017/01/13, marcelo-rocha, Marcelo Rocha, mcrocha@gmail.com -2017/01/23, bhamiltoncx, Ben Hamilton, bhamiltoncx+antlr@gmail.com -2017/01/18, mshockwave, Bekket McClane, yihshyng223@gmail.com -2017/02/10, lionelplessis, Lionel Plessis, lionelplessis@users.noreply.github.com -2017/02/14, lecode-official, David Neumann, david.neumann@lecode.de -2017/02/14, xied75, Dong Xie, xied75@gmail.com -2017/02/20, Thomasb81, Thomas Burg, thomasb81@gmail.com -2017/02/26, jvasileff, John Vasileff, john@vasileff.com -2017/03/08, harry-tallbelt, Igor Vysokopoyasny, harry.tallbelt@gmail.com -2017/03/09, teverett, Tom Everett, tom@khubla.com -2017/03/03, chund, Christian Hund, christian.hund@gmail.com -2017/03/15, robertvanderhulst, Robert van der Hulst, robert@xsharp.eu -2017/03/28, cmd-johnson, Jonas Auer, jonas.auer.94@gmail.com -2017/04/12, lys0716, Yishuang Lu, luyscmu@gmail.com -2017/04/30, shravanrn, Shravan Narayan, shravanrn@gmail.com -2017/05/11, jimallman, Jim Allman, jim@ibang.com -2017/05/26, waf, Will Fuqua, wafuqua@gmail.com -2017/05/29, kosak, Corey Kosak, kosak@kosak.com -2017/06/11, erikbra, Erik A. Brandstadmoen, erik@brandstadmoen.net -2017/06/10, jm-mikkelsen, Jan Martin Mikkelsen, janm@transactionware.com -2017/06/25, alimg, Alim Gökkaya, alim.gokkaya@gmail.com -2017/06/28, jBugman, Sergey Parshukov, codedby@bugman.me -2017/07/09, neatnerd, Mike Arshinskiy, neatnerd@users.noreply.github.com -2017/07/11, dhalperi, Daniel Halperin, daniel@halper.in -2017/07/17, vaibhavaingankar09, Vaibhav Vaingankar, vbhvvaingankar9@gmail.com -2017/07/23, venkatperi, Venkat Peri, venkatperi@gmail.com -2017/07/27, shirou, WAKAYAMA Shirou, shirou.faw@gmail.com -2017/07/09, neatnerd, Mike Arshinskiy, neatnerd@users.noreply.github.com -2017/07/27, matthauck, Matt Hauck, matthauck@gmail.com -2017/07/27, shirou, WAKAYAMA Shirou, shirou.faw@gmail.com -2017/08/20, tiagomazzutti, Tiago Mazzutti, tiagomzt@gmail.com -2017/08/20, milanaleksic, Milan Aleksic, milanaleksic@gmail.com -2017/08/29, Eddy Reyes, eddy@mindsight.io -2017/09/09, brauliobz, Bráulio Bezerra, brauliobezerra@gmail.com -2017/09/11, sachinjain024, Sachin Jain, sachinjain024@gmail.com -2017/09/25, kaedvann, Rostislav Listerenko, r.listerenko@gmail.com -2017/10/06, bramp, Andrew Brampton, brampton@gmail.com -2017/10/15, simkimsia, Sim Kim Sia, kimcity@gmail.com -2017/10/27, Griffon26, Maurice van der Pot, griffon26@kfk4ever.com -2017/05/29, rlfnb, Ralf Neeb, rlfnb@rlfnb.de -2017/10/29, gendalph, Максим Прохоренко, Maxim\dotProhorenko@gm@il.com -2017/11/02, jasonmoo, Jason Mooberry, jason.mooberry@gmail.com -2017/11/05, ajaypanyala, Ajay Panyala, ajay.panyala@gmail.com -2017/11/24, zqlu.cn, Zhiqiang Lu, zqlu.cn@gmail.com -2017/11/28, niccroad, Nicolas Croad, nic.croad@gmail.com -2017/12/01, DavidMoraisFerreira, David Morais Ferreira, david.moraisferreira@gmail.com -2017/12/01, SebastianLng, Sebastian Lang, sebastian.lang@outlook.com -2017/12/03, oranoran, Oran Epelbaum, oran / epelbaum me -2017/12/12, janlinde, Jan Lindemann, jan@janware.com -2017/12/13, enessoylu, Enes Soylu, enessoylutr@gmail.com -2017/12/20, kbsletten, Kyle Sletten, kbsletten@gmail.com -2017/12/27, jkmar, Jakub Marciniszyn, marciniszyn.jk@gmail.com -2018/03/08, dannoc, Daniel Clifford, danno@google.com -2018/03/10, uvguy, kangjoni76@gmail.com -2018/01/06, kasbah, Kaspar Emanuel, kaspar@monostable.co.uk -2018/01/15, xgcssch, Sönke Schau, xgcssch@users.noreply.github.com -2018/02/08, razfriman, Raz Friman, raz@razfriman.com -2018/02/11, io7m, Mark Raynsford, code@io7m.com -2018/04/24, solussd, Joe Smith, joe@uwcreations.com -2018/15/05, johnvanderholt, jan dillingh johnvanderholte@gmail.com -2018/06/14, scadgek, Sergey Chupov, scadgek@live.com -2018/06/16, EternalPhane, Zongyuan Zuo, eternalphane@gmail.com -2018/06/27, wu-sheng, Wu Sheng, wu.sheng@foxmail.com -2018/02/25, chaseoxide, Marcus Ong, taccs97[at]gmail[dot]com -2018/05/15, johnvanderholt, jan dillingh johnvanderholte@gmail.com -2018/06/16, EternalPhane, Zongyuan Zuo, eternalphane@gmail.com -2018/05/15, johnvanderholt, jan dillingh johnvanderholte@gmail.com -2018/05/17, sinopsysHK, Eric Bardes, sinofwd@gmail.com -2018/05/23, srvance, Stephen Vance, steve@vance.com -2018/06/14, alecont, Alessandro Contenti, alecontenti@hotmail.com -2018/06/16, EternalPhane, Zongyuan Zuo, eternalphane@gmail.com -2018/07/03, jgoppert, James Goppert, james.goppert@gmail.com -2018/07/27, Maksim Novikov, mnovikov.work@gmail.com -2018/08/03, ENDOH takanao, djmchl@gmail.com -2018/10/08, xsIceman, Andreas Skaar, andreas.skaar@gmail.com -2018/10/18, edirgarcia, Edir García Lazo, edirgl@hotmail.com -2018/07/31, Lucas Henrqiue, lucashenrique580@gmail.com -2018/08/03, ENDOH takanao, djmchl@gmail.com -2018/10/29, chrisaycock, Christopher Aycock, chris[at]chrisaycock[dot]com -2018/11/12, vinoski, Steve Vinoski, vinoski@ieee.org -2018/11/14, nxtstep, Adriaan (Arjan) Duz, codewithadriaan[et]gmail[dot]com -2018/11/15, amykyta3, Alex Mykyta, amykyta3@users.noreply.github.com -2018/11/29, hannemann-tamas, Ralf Hannemann-Tamas, ralf.ht@gmail.com -2018/12/20, WalterCouto, Walter Couto, WalterCouto@users.noreply.github.com -2018/12/23, youkaichao, Kaichao You, youkaichao@gmail.com -2019/01/01, khoroshilov, Alexey Khoroshilov, khoroshilov@ispras.ru -2019/01/02, wkhemir, Wail Khemir, khemirwail@gmail.com -2019/01/16, kuegi, Markus Zancolo, markus.zancolo@roomle.com -2019/01/29, hc-codersatlas, Harry Chan, harry.chan@codersatlas.com -2019/02/06, ralucado, Cristina Raluca Vijulie, ralucris.v[at]gmail[dot]com -2019/02/23, gedimitr, Gerasimos Dimitriadis, gedimitr@gmail.com -2019/03/13, base698, Justin Thomas, justin.thomas1@gmail.com -2019/03/18, carlodri, Carlo Dri, carlo.dri@gmail.com -2019/05/02, askingalot, Andy Collins, askingalot@gmail.com -2019/05/13, mapio, Massimo Santini, massimo.santini@gmail.com -2019/07/11, olowo726, Olof Wolgast, olof@baah.se -2019/07/16, abhijithneilabraham, Abhijith Neil Abraham, abhijithneilabrahampk@gmail.com -2019/07/26, Braavos96, Eric Hettiaratchi, erichettiaratchi@gmail.com -2019/08/02, thron7, Thomas Herchenroeder, thron7[at]users[dot]sourceforge[dot]net -2019/08/12, easonlin404, Eason Lin, easonlin404@gmail.com -2019/08/23, akaJes, Oleksandr Mamchyts, akaJes@gmail.com -2019/08/27, wurzelpeter, Markus Franke, markus[hyphen]franke[at]web[dot]de -2019/09/10, ImanHosseini, Iman Hosseini, hosseini.iman@yahoo.com -2019/09/03, João Henrique, johnnyonflame@hotmail.com -2019/09/10, neko1235, Ihar Mokharau, igor.mohorev@gmail.com -2019/09/10, yar3333, Yaroslav Sivakov, yar3333@gmail.com -2019/09/10, marcospassos, Marcos Passos, marcospassos.com@gmail.com -2019/09/10, amorimjuliana, Juliana Amorim, juu.amorim@gmail.com -2019/09/15, sullis, Sean Sullivan, github@seansullivan.com -2019/09/17, kaz, Kazuki Sawada, kazuki@6715.jp -2019/09/28, lmy269, Mingyang Liu, lmy040758@gmail.com -2019/10/29, tehbone, Tabari Alexander, tehbone@gmail.com -2019/10/31, a-square, Alexei Averchenko, lex.aver@gmail.com -2019/11/05, listba, Ben List, ben.list89@gmail.com -2019/11/11, foxeverl, Liu Xinfeng, liuxf1986[at]gmail[dot]com -2019/11/17, felixn, Felix Nieuwenhuizhen, felix@tdlrali.com -2019/11/18, mlilback, Mark Lilback, mark@lilback.com -2020/01/19, lingyv-li, Lingyu Li, lingyv.li@gmail.com -2020/02/02, carocad, Camilo Roca, carocad@unal.edu.co -2020/02/10, julibert, Julián Bermúdez Ortega, julibert.dev@gmail.com -2020/02/17, quantumsheep, Nathanael Demacon, nathanael.dmc@outlook.fr -2020/02/21, StochasticTinkr, Daniel Pitts, github@coloraura.com -2020/03/17, XsongyangX, Song Yang, songyang1218@gmail.com -2020/04/07, deniskyashif, Denis Kyashif, denis.kyashif@gmail.com -2020/04/08, lwehmeier, Leon Wehmeier, wehmeier@st.ovgu.de -2020/04/10, agrabski, Adam Grabski, adam.gr@outlook.com -2020/04/23, martinvw, Martin van Wingerden, martin@martinvw.nl -2020/04/23, kaczmarj, Jakub Kaczmarzyk, jakub.kaczmarzyk@stonybrookmedicine.edu -2020/04/30, TristonianJones, Tristan Swadell, tswadell@google.com -2020/05/06, iammosespaulr, Moses Paul R, iammosespaulr@gmail.com -2020/05/10, gomerser, Erik Gomersbach, gomerser@gomersba.ch -2020/05/22, keywan-ghadami-oxid, Keywan Ghadami, keywan.ghadami@oxid-esales.com -2020/05/25, graknol, Sindre van der Linden, graknol@gmail.com -2020/05/31, d-markey, David Markey, dmarkey@free.fr -2020/06/02, cohomology, Kilian Kilger, kkilger AT gmail.com -2020/06/04, IohannRabeson, Iohann Rabeson, iotaka6@gmail.com -2020/06/04, sigmasoldi3r, Pablo Blanco, pablobc.1995@gmail.com -2020/06/15, mattpaletta, Matthew Paletta, mattpaletta@gmail.com -2020/07/01, sha-N, Shan M Mathews, admin@bluestarqatar.com -2020/08/22, stevenjohnstone, Steven Johnstone, steven.james.johnstone@gmail.com -2020/09/06, ArthurSonzogni, Sonzogni Arthur, arthursonzogni@gmail.com -2020/09/10, Khailian, Arunav Sanyal, arunav.sanyal91@gmail.com -2020/09/12, Clcanny, Charles Ruan, a837940593@gmail.com -2020/09/15, rmcgregor1990, Robert McGregor, rmcgregor1990@gmail.com -2020/09/16, trenki2, Markus Trenkwalder, trenki2[at]gmx[dot]net -2020/10/08, Marti2203, Martin Mirchev, mirchevmartin2203@gmail.com -2020/10/16, adarshbhat, Adarsh Bhat, adarshbhat@users.noreply.github.com -2020/10/20, adamwojs, Adam Wójs, adam[at]wojs.pl -2020/10/24, cliid, Jiwu Jang, jiwujang@naver.com -2020/11/05, MichelHartmann, Michel Hartmann, MichelHartmann@users.noreply.github.com -2020/11/26, mr-c, Michael R. Crusoe, 1330696+mr-c@users.noreply.github.com -2020/12/01, maxence-lefebvre, Maxence Lefebvre, maxence-lefebvre@users.noreply.github.com -2020/12/03, electrum, David Phillips, david@acz.org -2021/01/03, niw, Yoshimasa Niwa, niw@niw.at -2021/01/25, l215884529, Qiheng Liu, 13607681+l215884529@users.noreply.github.com -2021/02/02, tsotnikov, Taras Sotnikov, taras.sotnikov@gmail.com -2021/02/10, jirislaby, Jiri Slaby, jirislaby@gmail.com -2021/02/21, namasikanam, Xingyu Xie, namasikanam@gmail.com -2021/02/26, ahooper, Andrew Hooper, ahooper at kos dot net -2021/02/27, khmarbaise, Karl Heinz Marbaise, github@soebes.com -2021/02/28, Dante-Broggi, Dante Broggi, 34220985+Dante-Broggi@users.noreply.github.com -2021/03/02, hackeris -2021/03/03, xTachyon, Damian Andrei, xTachyon@users.noreply.github.com -2021/03/22, 100mango, Fangqiu Fang, 100mango@gmail.com -2021/04/07, b1f6c1c4, Jinzheng Tu, b1f6c1c4@gmail.com -2021/04/17, jaggerjo, Josua Jäger, mail@jaggerjo.com -2021/04/24, bigerl, Alexander Bigerl, alexander [äät] bigerl [pkt] eu -2021/05/02, michalharakal, Michal Harakal, michal.harakal@users.noreply.github.com -2021/05/03, redexp, Sergii Kliuchnyk, redexp@users.noreply.github.com -2021/05/03, mitar, Mi Tar, mitar.git@tnode.com -2021/05/04, joakker, Joaquín León, joaquinandresleon108@gmail.com -2021/05/06, renancaraujo, Renan C. Araújo, renancaraujo@users.noreply.github.com -2021/05/06, canastro, Ricardo Canastro, ricardocanastro@users.noreply.github.com -2021/06/19, abe149, Abe Skolnik, abe 149 at gmail . com -2021/07/01, appel1, Johan Appelgren, johan.appelgren@gmail.com -2021/07/01, marcauberer, Marc Auberer, marc.auberer@chillibits.com -2021/07/14, renzhentaxibaerde, Renzhentaxi Baerde, renzhentaxibaerde@gmail.com -2021/07/21, skittlepox, Benjamin Spiegel, bspiegel@cs.brown.edu -2021/07/29, ksyx, Qixing Xue, qixingxue@outlook.com -2021/07/29, rachidlamouri, Rachid Lamouri, rachidlamouri@gmail.com -2021/08/02, minjoosur, Minjoo Sur, msur@salesforce.com -2021/08/05, jjeffcaii, Jeff Tsai, caiweiwei.cww@alibaba-inc.com -2021/08/08, ansiemens, Yi-Hong Lin, ansiemens@gmail.com -2021/08/25, XenoAmess, Jin Xu, xenoamess@gmail.com -2021/09/08, jmcken8, Joel McKenzie, joel.b.mckenzie@gmail.com -2021/09/23, skalt, Steven Kalt, kalt.steven@gmail.com -2021/09/26, idraper, Isaac Draper, idraper@byu.edu -2021/10/10, tools4origins, Erwan Guyomarc'h, contact@erwan-guyomarch.fr -2021/10/19, jcking, Justin King, jcking@google.com -2021/10/31, skef, Skef Iterum, github@skef.org -2021/10/31, hlstwizard, h.l.s.t@163.com -2021/11/30, bollwyvl, Nick Bollweg, bollwyvl@users.noreply.github.com -2021/12/03, eneko, Eneko Alonso, eneko.alonso@gmail.com -2021/12/16, Ketler13, Oleksandr Martyshchenko, oleksandr.martyshchenko@gmail.com -2021/12/25, Tinker1024, Tinker1024, tinker@huawei.com -2021/12/31, Biswa96, Biswapriyo Nath, nathbappai@gmail.com -2022/03/07, chenquan, chenquan, chenquan.dev@gmail.com -2022/03/15, hzeller, Henner Zeller, h.zeller@acm.org