Debian Codegraph @

doc/dart-target.md

raw
1 # ANTLR4 Runtime for Dart
2
3 Notice: Dart target may generate code incompatible with Dart 2.9 sound null safety. Please set the minimum SDK constraint to 2.8.4 or lower if such violation is found. Contributions are welcomed.
4
5 ### First steps
6
7 #### 1. Install ANTLR4
8
9 [The getting started guide](https://github.com/antlr/antlr4/blob/master/doc/getting-started.md)
10 should get you started.
11
12 #### 2. Install the Dart ANTLR runtime
13
14 Each target language for ANTLR has a runtime package for running parser
15 generated by ANTLR4. The runtime provides a common set of tools for using your parser.
16
17 Install the runtime with the same version as the main ANTLR tool:
18
19 Add this to your package's pubspec.yaml file:
20 ```yaml
21 ...
22 dependencies:
23 antlr4: <ANTLR version>
24 ...
25 ```
26
27 #### 3. Generate your parser
28
29 You use the ANTLR4 "tool" to generate a parser. These will reference the ANTLR
30 runtime, installed above.
31
32 Suppose you're using a UNIX system and have set up an alias for the ANTLR4 tool
33 as described in [the getting started guide](https://github.com/antlr/antlr4/blob/master/doc/getting-started.md).
34 To generate your Dart parser, run the following command:
35
36 ```shell script
37 antlr4 -Dlanguage=Dart MyGrammar.g4
38 ```
39
40 For a full list of antlr4 tool options, please visit the
41 [tool documentation page](https://github.com/antlr/antlr4/blob/master/doc/tool-options.md).
42
43 ### Complete example
44
45 Suppose you're using the JSON grammar from https://github.com/antlr/grammars-v4/tree/master/json.
46
47 Then, invoke `antlr4 -Dlanguage=Dart JSON.g4`. The result of this is a
48 collection of `.dart` including:
49
50 * JsonLexer.dart
51 * JsonParser.dart
52 * JsonBaseListener.dart
53 * JsonListener.dart (if you have not activated the -no-listener option)
54 * JsonVisitor.dart (if you have activated the -visitor option)
55
56 We'll write a small main func to call the generated parser/lexer
57 (assuming they are separate). This one writes out the encountered
58 `ParseTreeContext`'s:
59
60 ```dart
61 import 'package:antlr4/antlr4.dart';
62 import 'package:my_project/JSONParser.dart';
63 import 'package:my_project/JSONLexer.dart';
64
65 class TreeShapeListener implements ParseTreeListener {
66 @override
67 void enterEveryRule(ParserRuleContext ctx) {
68 print(ctx.text);
69 }
70
71 @override
72 void exitEveryRule(ParserRuleContext node) {
73 }
74
75 @override
76 void visitErrorNode(ErrorNode node) {
77 }
78
79 @override
80 void visitTerminal(TerminalNode node) {
81 }
82 }
83
84 void main(List<String> args) async {
85 JSONLexer.checkVersion();
86 JSONParser.checkVersion();
87 final input = await InputStream.fromPath(args[0]);
88 final lexer = JSONLexer(input);
89 final tokens = CommonTokenStream(lexer);
90 final parser = JSONParser(tokens);
91 parser.addErrorListener(DiagnosticErrorListener());
92 parser.buildParseTree = true;
93 final tree = parser.json();
94 ParseTreeWalker.DEFAULT.walk(TreeShapeListener(), tree);
95 }
96 ```
97
98 Create a `example.json` file:
99 ```json
100 {"a":1}
101 ```
102
103 Parse the input file:
104
105 ```shell script
106 dart bin/main.dart example.json
107 ```
108
109 The expected output is:
110
111 ```
112 {"a":1}
113 {"a":1}
114 {"a":1}
115 "a":1
116 1
117 ```