Add docs for Dart target

README.md

@@ -23,6 +23,7 @@ ANTLR project lead and supreme dictator for life
 * [Ewan Mellor](https://github.com/ewanmellor), [Hanzhou Shi](https://github.com/hanjoes) (Swift target merging)
 * [Ben Hamilton](https://github.com/bhamiltoncx) (Full Unicode support in serialized ATN and all languages' runtimes for code points > U+FFFF)
 * [Marcos Passos](https://github.com/marcospassos) (PHP target)
+* [Lingyu Li](https://github.com/lingyv-li) (Dart target)
 
 ## Useful information
 

doc/dart-target.md

@@ -0,0 +1,115 @@
+# ANTLR4 Runtime for Dart
+
+### First steps
+
+#### 1. Install ANTLR4
+
+[The getting started guide](https://github.com/antlr/antlr4/blob/master/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: <ANTLR version>
+...
+```
+
+#### 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/antlr4/blob/master/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/antlr4/blob/master/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<String> 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());
+  parser.buildParseTree = true;
+  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
+```

doc/releasing-antlr.md

@@ -65,6 +65,8 @@ Edit the repository looking for 4.5 or whatever and update it. Bump version in t
  * runtime/Cpp/demo/generate.cmd
  * runtime/Go/antlr/recognizer.go
  * runtime/Swift/Antlr4/org/antlr/v4/runtime/RuntimeMetaData.swift
+ * runtime/Dart/lib/src/runtime_meta_data.dart
+ * runtime/Dart/pubspec.yaml
  * tool/src/org/antlr/v4/codegen/target/GoTarget.java
  * tool/src/org/antlr/v4/codegen/target/CppTarget.java
  * tool/src/org/antlr/v4/codegen/target/CSharpTarget.java
@@ -442,6 +444,19 @@ git push origin gh-pages
 popd
 ```
 
+### Dart
+
+Push to pub.dev
+
+```bash
+cd runtime/Dart
+pub publish
+```
+
+It will warn that no change log found for the new version.
+If there are changes relevant to dart in this release, edit [CHANGELOG.md](https://github.com/antlr/antlr4/blob/master/runtime/Dart/CHANGELOG.md) to describe the changes.
+Otherwise enter `N` to ignore the warning.
+
 ## Update javadoc for runtime and tool
 
 First, gen javadoc:

doc/targets.md

@@ -10,12 +10,13 @@ This page lists the available and upcoming ANTLR runtimes. Please note that you
 * [C++](cpp-target.md)
 * [Swift](swift-target.md)
 * [PHP](php-target.md)
+* [Dart](dart-target.md)
 
 ## Target feature parity
 
 New features generally appear in the Java target and then migrate to the other targets, but these other targets don't always get updated in the same overall tool release. This section tries to identify features added to Java that have not been added to the other targets.
 
-|Feature|Java|C♯|Python2|Python3|JavaScript|Go|C++|Swift|PHP
+|Feature|Java|C♯|Python2|Python3|JavaScript|Go|C++|Swift|PHP|Dart
-|---|---|---|---|---|---|---|---|---|---|
+|---|---|---|---|---|---|---|---|---|---|---|
-|Ambiguous tree construction|4.5.1|-|-|-|-|-|-|-|-|
+|Ambiguous tree construction|4.5.1|-|-|-|-|-|-|-|-|-|
 

runtime/Dart/CHANGELOG.md

@@ -0,0 +1,4 @@
+
+## 4.8.0-dev.2
+
+* Initial release

runtime/Dart/README.md

@@ -6,6 +6,6 @@ This runtime is available through [pub](https://pub.dev). The package name is 'a
 
 See www.antlr.org for more information on ANTLR.
 
-See https://github.com/antlr/antlr4/blob/master/doc/Dart-target.md for more information on using ANTLR in Dart.
+See https://github.com/antlr/antlr4/blob/master/doc/dart-target.md for more information on using ANTLR in Dart.
 
 

runtime/Dart/pubspec.yaml

@@ -1,5 +1,5 @@
 name: "antlr4"
-version: "4.8.0-dev.1"
+version: "4.8.0-dev.2"
 description: "New Dart runtime for ANTLR4."
 homepage: "https://github.com/antlr/antlr4"
 license: "BSD-3-Clause"

tool/resources/org/antlr/v4/tool/templates/codegen/Dart/Dart.stg

@@ -225,7 +225,7 @@ Parser_(parser, funcs, atn, sempredFuncs, ctor, superClass) ::= <<
 <if(namedActions.definitions)><namedActions.definitions><endif>
 const int <parser.rules:{r | RULE_<r.name> = <r.index>}; separator=", ", wrap, anchor>;
 class <parser.name> extends <superClass; null="Parser"> {
-  static final void versionCheck = () { RuntimeMetaData.checkVersion('<file.ANTLRVersion>', RuntimeMetaData.VERSION); }();
+  static final checkVersion = () => RuntimeMetaData.checkVersion('<file.ANTLRVersion>', RuntimeMetaData.VERSION);
   static const int TOKEN_EOF = IntStream.EOF;
 
   static final List\<DFA> _decisionToDFA = List.generate(
@@ -827,7 +827,7 @@ Lexer(lexer, atn, actionFuncs, sempredFuncs, superClass) ::= <<
 <if(namedActions.definitions)><namedActions.definitions><endif>
 
 class <lexer.name> extends <superClass; null="Lexer"> {
-  static final versionCheck = () { RuntimeMetaData.checkVersion('<lexerFile.ANTLRVersion>', RuntimeMetaData.VERSION); }();
+  static final checkVersion = () => RuntimeMetaData.checkVersion('<lexerFile.ANTLRVersion>', RuntimeMetaData.VERSION);
 
   static final List\<DFA> _decisionToDFA = List.generate(
         _ATN.numberOfDecisions, (i) => DFA(_ATN.getDecisionState(i), i));