Merge pull request #3957 from parrt/compare-ATN-sim-output

Generate identical atn simulation output across targets to compare parsing functionality

Author: parrt

doc/creating-a-language-target.md

@@ -45,3 +45,26 @@ $ mvn compile
 ```
 
 That should proceed with success. See [Building ANTLR](building-antlr.md) for more details.
+
+## Comparing your target's parsing decisionmaking with Java's
+
+ANTLR's power comes from it's dynamic parsing strategy, but that means each target
+must implement that complicated algorithm. You should compare your target's debug
+output for ParserATNSimulator with Java's.
+
+Run this so we get right jars before trying this script:
+
+```
+cd ANTLR-ROOT-DIR
+mvn install -DskipTests=true
+cd runtime-tests 
+mvn install -DskipTests=true # yes do it again
+```
+
+Run the script from `runtime-tests` dir with
+
+```
+../scripts/traceatn.sh /tmp/JSON.g4 json -target Go /tmp/foo.json
+```
+
+or whatever your test grammar, start rule, target, test input are.

runtime-testsuite/resources/org/antlr/v4/test/runtime/helpers/Test.cpp.stg

@@ -33,7 +33,7 @@ int main(int argc, const char* argv[]) {
   CommonTokenStream tokens(&lexer);
 <if(parserName)>
   <parserName> parser(&tokens);
-<if(debug)>
+<if(showDiagnosticErrors)>
   DiagnosticErrorListener errorListener;
   parser.addErrorListener(&errorListener);
 <endif>

runtime-testsuite/resources/org/antlr/v4/test/runtime/helpers/Test.cs.stg

@@ -1,5 +1,6 @@
 using System;
 using Antlr4.Runtime;
+using Antlr4.Runtime.Atn;
 using Antlr4.Runtime.Tree;
 using System.Text;
 
@@ -12,8 +13,11 @@ public class Test {
 		var tokens = new CommonTokenStream(lex);
 <if(parserName)>
 		var parser = new <parserName>(tokens);
-<if(debug)>
+<if(showDiagnosticErrors)>
 		parser.AddErrorListener(new DiagnosticErrorListener());
+<endif>
+<if(traceATN)>
+	    ParserATNSimulator.trace_atn_sim = true;
 <endif>
 		parser.BuildParseTree = true;
 		var tree = parser.<parserStartRuleName>();

runtime-testsuite/resources/org/antlr/v4/test/runtime/helpers/Test.dart.stg

@@ -12,7 +12,7 @@ void main(List\<String> args) async {
   final tokens = CommonTokenStream(lex);
 <if(parserName)>
   final parser = <parserName>(tokens);
-<if(debug)>
+<if(showDiagnosticErrors)>
   parser.addErrorListener(new DiagnosticErrorListener());
 <endif>
 <if(profile)>

runtime-testsuite/resources/org/antlr/v4/test/runtime/helpers/Test.go.stg

@@ -27,6 +27,9 @@ func (this *TreeShapeListener) EnterEveryRule(ctx antlr.ParserRuleContext) {
 <endif>
 
 func main() {
+<if(traceATN)>
+    antlr.ParserATNSimulatorTraceATNSim = true
+<endif>
 	input, err := antlr.NewFileStream(os.Args[1])
 		if err != nil {
 		fmt.Printf("Failed to find file: %v", err)
@@ -36,7 +39,7 @@ func main() {
 	stream := antlr.NewCommonTokenStream(lexer,0)
 <if(parserName)>
 	p := parser.New<parserName>(stream)
-<if(debug)>
+<if(showDiagnosticErrors)>
 	p.AddErrorListener(antlr.NewDiagnosticErrorListener(true))
 <endif>
 	p.BuildParseTrees = true

runtime-testsuite/resources/org/antlr/v4/test/runtime/helpers/Test.java.stg

@@ -29,8 +29,11 @@ public class Test {
 		parser.setOutStream(outStream);
 		parser.removeErrorListeners();
 		parser.addErrorListener(errorListener);
-<if(debug)>
+<if(showDiagnosticErrors)>
 		parser.addErrorListener(new DiagnosticErrorListener());
+<endif>
+<if(traceATN)>
+		ParserATNSimulator.trace_atn_sim = true;
 <endif>
 		parser.setBuildParseTree(true);
 <if(profile)>

runtime-testsuite/resources/org/antlr/v4/test/runtime/helpers/Test.js.stg

@@ -28,7 +28,7 @@ function main(argv) {
     var stream = new antlr4.CommonTokenStream(lexer);
 <if(parserName)>
     var parser = new <parserName>(stream);
-<if(debug)>
+<if(showDiagnosticErrors)>
     parser.addErrorListener(new antlr4.error.DiagnosticErrorListener());
 <endif>
     parser.buildParseTrees = true;
@@ -38,6 +38,10 @@ function main(argv) {
         return this;
     };
     parser.printer = new printer();
+<if(traceATN)>
+	parser._interp.trace_atn_sim = true;
+	antlr4.context.PredictionContext.trace_atn_sim = true;
+<endif>
     var tree = parser.<parserStartRuleName>();
     antlr4.tree.ParseTreeWalker.DEFAULT.walk(new TreeShapeListener(), tree);
 <else>

runtime-testsuite/resources/org/antlr/v4/test/runtime/helpers/Test.php.stg

@@ -48,7 +48,7 @@ $lexer->addErrorListener(new ConsoleErrorListener());
 $tokens = new CommonTokenStream($lexer);
 <if(parserName)>
 $parser = new <parserName>($tokens);
-<if(debug)>
+<if(showDiagnosticErrors)>
 $parser->addErrorListener(new DiagnosticErrorListener());
 <endif>
 $parser->addErrorListener(new ConsoleErrorListener());

runtime-testsuite/resources/org/antlr/v4/test/runtime/helpers/Test.py.stg

@@ -27,12 +27,16 @@ class TreeShapeListener(ParseTreeListener):
 <endif>
 
 def main(argv):
+<if(traceATN)>
+    ParserATNSimulator.trace_atn_sim = True
+    PredictionContext._trace_atn_sim = True
+<endif>
     input = FileStream(argv[1], encoding='utf-8', errors='replace')
     lexer = <lexerName>(input)
     stream = CommonTokenStream(lexer)
 <if(parserName)>
     parser = <parserName>(stream)
-<if(debug)>
+<if(showDiagnosticErrors)>
     parser.addErrorListener(DiagnosticErrorListener())
 <endif>
     parser.buildParseTrees = True

runtime-testsuite/resources/org/antlr/v4/test/runtime/helpers/main.swift.stg

@@ -23,7 +23,7 @@ let lex = <lexerName>(input)
 let tokens = CommonTokenStream(lex)
 <if(parserName)>
 let parser = try <parserName>(tokens)
-<if(debug)>
+<if(showDiagnosticErrors)>
 parser.addErrorListener(DiagnosticErrorListener())
 <endif>
 parser.setBuildParseTree(true)