Debian Codegraph @

doc/go-target.md

raw
1 # ANTLR4 Language Target, Runtime for Go
2
3 ### First steps
4
5 #### 1. Install ANTLR4
6
7 [The getting started guide](getting-started.md) should get you started.
8
9 #### 2. Get the Go ANTLR runtime
10
11 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.
12
13 Get the runtime and install it on your GOPATH:
14
15 ```bash
16 go get github.com/antlr/antlr4/runtime/Go/antlr
17 ```
18
19 #### 3. Set the release tag (optional)
20
21 `go get` has no native way to specify a branch or commit. So, when you run it, you'll download the latest commits. This may or may not be your preference.
22
23 You'll need to use git to set the release. For example, to set the release tag for release 4.6.0:
24
25 ```bash
26 cd $GOPATH/src/github.com/antlr/antlr4 # enter the antlr4 source directory
27 git checkout tags/4.6.0 # the go runtime was added in release 4.6.0
28 ```
29
30 A complete list of releases can be found on [the release page](https://github.com/antlr/antlr4/releases).
31
32 #### 4. Generate your parser
33
34 You use the ANTLR4 "tool" to generate a parser. These will reference the ANTLR runtime, installed above.
35
36 Suppose you're using a UNIX system and have set up an alias for the ANTLR4 tool as described in [the getting started guide](getting-started.md). To generate your go parser, you'll need to invoke:
37
38 ```bash
39 antlr4 -Dlanguage=Go MyGrammar.g4
40 ```
41
42 For a full list of antlr4 tool options, please visit the [tool documentation page](tool-options.md).
43
44 ### Referencing the Go ANTLR runtime
45
46 You can reference the go ANTLR runtime package like this:
47
48 ```go
49 import "github.com/antlr/antlr4/runtime/Go/antlr"
50 ```
51
52 ### Complete example
53
54 Suppose you're using the JSON grammar from https://github.com/antlr/grammars-v4/tree/master/json.
55
56 Then, invoke `antlr4 -Dlanguage=Go JSON.g4`. The result of this is a collection of .go files in the `parser` directory including:
57 ```
58 json_parser.go
59 json_base_listener.go
60 json_lexer.go
61 json_listener.go
62 ```
63
64 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).
65
66 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. Suppose the gen'ed parser code is in the `parser` directory relative to this code:
67
68 ```golang
69 package main
70
71 import (
72 "github.com/antlr/antlr4/runtime/Go/antlr"
73 "./parser"
74 "os"
75 "fmt"
76 )
77
78 type TreeShapeListener struct {
79 *parser.BaseJSONListener
80 }
81
82 func NewTreeShapeListener() *TreeShapeListener {
83 return new(TreeShapeListener)
84 }
85
86 func (this *TreeShapeListener) EnterEveryRule(ctx antlr.ParserRuleContext) {
87 fmt.Println(ctx.GetText())
88 }
89
90 func main() {
91 input, _ := antlr.NewFileStream(os.Args[1])
92 lexer := parser.NewJSONLexer(input)
93 stream := antlr.NewCommonTokenStream(lexer,0)
94 p := parser.NewJSONParser(stream)
95 p.AddErrorListener(antlr.NewDiagnosticErrorListener(true))
96 p.BuildParseTrees = true
97 tree := p.Json()
98 antlr.ParseTreeWalkerDefault.Walk(NewTreeShapeListener(), tree)
99 }
100 ```
101
102 This one expects the input to be passed on the command line:
103
104 ```
105 go run test.go input
106 ```
107
108 The output is:
109
110 ```
111 {"a":1}
112 {"a":1}
113 "a":1
114 1
115 ```