diff --git a/doc/dart-target.md b/doc/dart-target.md new file mode 100644 index 000000000..77e729b42 --- /dev/null +++ b/doc/dart-target.md @@ -0,0 +1,103 @@ +# 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 Composer: + +```bash +composer install antlr/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: + +```bash +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` files in the `parser` directory including: +``` +JsonParser.Dart +JsonBaseListener.Dart +JsonLexer.Dart +JsonListener.Dart +``` + +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: + +```Dart +import 'packages:antlr4/antlr4.dart'; +import 'P'; + +class TreeShapeListener implements ParseTreeListener { + void visitTerminal(TerminalNode node) {} + void visitErrorNode(ErrorNode node) {} + void exitEveryRule(ParserRuleContext ctx) {} + + void enterEveryRule(ParserRuleContext ctx) { + print(ctx.text); + } +} +main () { +} + +$input = InputStream::fromPath($argv[1]); +$lexer = new JSONLexer($input); +$tokens = new CommonTokenStream($lexer); +$parser = new JSONParser($tokens); +$parser->addErrorListener(new DiagnosticErrorListener()); +$parser->setBuildParseTree(true); +$tree = $parser->json(); + +ParseTreeWalker::default()->walk(new TreeShapeListener(), $tree); +``` + +Create a `example.json` file: +```json +{"a":1} +``` + +Parse the input file: + +``` +dart json.Dart example.json +``` + +The expected output is: + +``` +{"a":1} +{"a":1} +"a":1 +1 +``` \ No newline at end of file