From 150ecabfffbdc2b68b429349af64a8a3b66791fa Mon Sep 17 00:00:00 2001 From: Larry Li Date: Sun, 31 May 2020 00:35:07 +1000 Subject: [PATCH] Add docs for Dart target --- README.md | 1 + doc/dart-target.md | 115 ++++++++++++++++++ doc/releasing-antlr.md | 15 +++ doc/targets.md | 7 +- runtime/Dart/CHANGELOG.md | 4 + runtime/Dart/{LICENSE.txt => LICENSE} | 0 runtime/Dart/README.md | 2 +- runtime/Dart/pubspec.yaml | 2 +- .../v4/tool/templates/codegen/Dart/Dart.stg | 4 +- 9 files changed, 143 insertions(+), 7 deletions(-) create mode 100644 doc/dart-target.md create mode 100644 runtime/Dart/CHANGELOG.md rename runtime/Dart/{LICENSE.txt => LICENSE} (100%) diff --git a/README.md b/README.md index ec5c21c62..44cbf62a8 100644 --- a/README.md +++ b/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 diff --git a/doc/dart-target.md b/doc/dart-target.md new file mode 100644 index 000000000..2b85e81f6 --- /dev/null +++ b/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: +... +``` + +#### 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 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 +``` \ No newline at end of file diff --git a/doc/releasing-antlr.md b/doc/releasing-antlr.md index cd1d0b9b4..a09fd33eb 100644 --- a/doc/releasing-antlr.md +++ b/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: diff --git a/doc/targets.md b/doc/targets.md index c2341ec48..ad6e7dba9 100644 --- a/doc/targets.md +++ b/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 -|---|---|---|---|---|---|---|---|---|---| -|Ambiguous tree construction|4.5.1|-|-|-|-|-|-|-|-| +|Feature|Java|C♯|Python2|Python3|JavaScript|Go|C++|Swift|PHP|Dart +|---|---|---|---|---|---|---|---|---|---|---| +|Ambiguous tree construction|4.5.1|-|-|-|-|-|-|-|-|-| diff --git a/runtime/Dart/CHANGELOG.md b/runtime/Dart/CHANGELOG.md new file mode 100644 index 000000000..84522ce54 --- /dev/null +++ b/runtime/Dart/CHANGELOG.md @@ -0,0 +1,4 @@ + +## 4.8.0-dev.2 + +* Initial release \ No newline at end of file diff --git a/runtime/Dart/LICENSE.txt b/runtime/Dart/LICENSE similarity index 100% rename from runtime/Dart/LICENSE.txt rename to runtime/Dart/LICENSE diff --git a/runtime/Dart/README.md b/runtime/Dart/README.md index b386f0ba1..3b2b4a78b 100644 --- a/runtime/Dart/README.md +++ b/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. diff --git a/runtime/Dart/pubspec.yaml b/runtime/Dart/pubspec.yaml index 9662bd4ee..3a5c79645 100644 --- a/runtime/Dart/pubspec.yaml +++ b/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" diff --git a/tool/resources/org/antlr/v4/tool/templates/codegen/Dart/Dart.stg b/tool/resources/org/antlr/v4/tool/templates/codegen/Dart/Dart.stg index 66b2a0ef4..39f453bec 100644 --- a/tool/resources/org/antlr/v4/tool/templates/codegen/Dart/Dart.stg +++ b/tool/resources/org/antlr/v4/tool/templates/codegen/Dart/Dart.stg @@ -225,7 +225,7 @@ Parser_(parser, funcs, atn, sempredFuncs, ctor, superClass) ::= << const int = }; separator=", ", wrap, anchor>; class extends { - static final void versionCheck = () { RuntimeMetaData.checkVersion('', RuntimeMetaData.VERSION); }(); + static final checkVersion = () => RuntimeMetaData.checkVersion('', RuntimeMetaData.VERSION); static const int TOKEN_EOF = IntStream.EOF; static final List\ _decisionToDFA = List.generate( @@ -827,7 +827,7 @@ Lexer(lexer, atn, actionFuncs, sempredFuncs, superClass) ::= << class extends { - static final versionCheck = () { RuntimeMetaData.checkVersion('', RuntimeMetaData.VERSION); }(); + static final checkVersion = () => RuntimeMetaData.checkVersion('', RuntimeMetaData.VERSION); static final List\ _decisionToDFA = List.generate( _ATN.numberOfDecisions, (i) => DFA(_ATN.getDecisionState(i), i));