Debian Codegraph @

doc/php-target.md

raw
1 # ANTLR4 Runtime for PHP
2
3 ### First steps
4
5 #### 1. Install ANTLR4
6
7 [The getting started guide](https://github.com/antlr/antlr4/blob/master/doc/getting-started.md)
8 should get you started.
9
10 #### 2. Install the PHP ANTLR runtime
11
12 Each target language for ANTLR has a runtime package for running parser
13 generated by ANTLR4. The runtime provides a common set of tools for using your parser.
14
15 Install the runtime with Composer:
16
17 ```bash
18 composer require antlr/antlr4-php-runtime
19 ```
20
21 #### 3. Generate your parser
22
23 You use the ANTLR4 "tool" to generate a parser. These will reference the ANTLR
24 runtime, installed above.
25
26 Suppose you're using a UNIX system and have set up an alias for the ANTLR4 tool
27 as described in [the getting started guide](https://github.com/antlr/antlr4/blob/master/doc/getting-started.md).
28 To generate your PHP parser, run the following command:
29
30 ```bash
31 antlr4 -Dlanguage=PHP MyGrammar.g4
32 ```
33
34 For a full list of antlr4 tool options, please visit the
35 [tool documentation page](https://github.com/antlr/antlr4/blob/master/doc/tool-options.md).
36
37 ### Complete example
38
39 Suppose you're using the JSON grammar from https://github.com/antlr/grammars-v4/tree/master/json.
40
41 Then, invoke `antlr4 -Dlanguage=PHP JSON.g4`. The result of this is a
42 collection of `.php` files in the `parser` directory including:
43 ```
44 JsonParser.php
45 JsonBaseListener.php
46 JsonLexer.php
47 JsonListener.php
48 ```
49
50 Another common option to the ANTLR tool is `-visitor`, which generates a parse
51 tree visitor, but we won't be doing that here. For a full list of antlr4 tool
52 options, please visit the [tool documentation page](tool-options.md).
53
54 We'll write a small main func to call the generated parser/lexer
55 (assuming they are separate). This one writes out the encountered
56 `ParseTreeContext`'s:
57
58 ```php
59 <?php
60
61 namespace JsonParser;
62
63 use Antlr\Antlr4\Runtime\CommonTokenStream;
64 use Antlr\Antlr4\Runtime\Error\Listeners\DiagnosticErrorListener;
65 use Antlr\Antlr4\Runtime\InputStream;
66 use Antlr\Antlr4\Runtime\ParserRuleContext;
67 use Antlr\Antlr4\Runtime\Tree\ErrorNode;
68 use Antlr\Antlr4\Runtime\Tree\ParseTreeListener;
69 use Antlr\Antlr4\Runtime\Tree\ParseTreeWalker;
70 use Antlr\Antlr4\Runtime\Tree\TerminalNode;
71
72 final class TreeShapeListener implements ParseTreeListener {
73 public function visitTerminal(TerminalNode $node) : void {}
74 public function visitErrorNode(ErrorNode $node) : void {}
75 public function exitEveryRule(ParserRuleContext $ctx) : void {}
76
77 public function enterEveryRule(ParserRuleContext $ctx) : void {
78 echo $ctx->getText();
79 }
80 }
81
82 $input = InputStream::fromPath($argv[1]);
83 $lexer = new JSONLexer($input);
84 $tokens = new CommonTokenStream($lexer);
85 $parser = new JSONParser($tokens);
86 $parser->addErrorListener(new DiagnosticErrorListener());
87 $parser->setBuildParseTree(true);
88 $tree = $parser->json();
89
90 ParseTreeWalker::default()->walk(new TreeShapeListener(), $tree);
91 ```
92
93 Create a `example.json` file:
94 ```json
95 {"a":1}
96 ```
97
98 Parse the input file:
99
100 ```
101 php json.php example.json
102 ```
103
104 The expected output is:
105
106 ```
107 {"a":1}
108 {"a":1}
109 "a":1
110 1
111 ```