Debian Codegraph @

doc/csharp-target.md

raw
1 # C♯
2
3 ## Which frameworks are supported?
4
5 The C# runtime is CLS compliant, and only requires a corresponding 3.5 .Net framework.
6
7 In practice, the runtime has been extensively tested against:
8
9 * Microsoft .Net 3.5 framework
10 * Mono .Net 3.5 framework
11
12 No issue was found, so you should find that the runtime works pretty much against any recent .Net framework.
13
14 ## How do I get started?
15
16 You will find full instructions on the [Git repo page for ANTLR C# runtime](https://github.com/antlr/antlr4/tree/master/runtime/CSharp).
17
18 ## How do I use the runtime from my project?
19
20 (i.e., How do I run the generated lexer and/or parser?)
21
22 Let's suppose that your grammar is named `MyGrammar`. The tool will generate for you the following files:
23
24 * MyGrammarLexer.cs
25 * MyGrammarParser.cs
26 * MyGrammarListener.cs (if you have not activated the -no-listener option)
27 * MyGrammarBaseListener.cs (if you have not activated the -no-listener option)
28 * MyGrammarVisitor.cs (if you have activated the -visitor option)
29 * MyGrammarBaseVisitor.cs (if you have activated the -visitor option)
30
31 Now a fully functioning code might look like the following for start rule `StartRule`:
32
33 ```csharp
34 using Antlr4.Runtime;
35 using Antlr4.Runtime.Tree;
36
37 public void MyParseMethod() {
38 String input = "your text to parse here";
39 ICharStream stream = CharStreams.fromString(input);
40 ITokenSource lexer = new MyGrammarLexer(stream);
41 ITokenStream tokens = new CommonTokenStream(lexer);
42 MyGrammarParser parser = new MyGrammarParser(tokens);
43 parser.BuildParseTree = true;
44 IParseTree tree = parser.StartRule();
45 }
46 ```
47
48 This program will work. But it won't be useful unless you do one of the following:
49
50 * you visit the parse tree using a custom listener
51 * you visit the parse tree using a custom visitor
52 * your grammar comprises production code (like AntLR3)
53
54 (please note that production code is target specific, so you can't have multi target grammars that include production code)
55
56 ## How do I create and run a custom listener?
57
58 Let's suppose your MyGrammar grammar comprises 2 rules: "key" and "value".
59
60 The antlr4 tool will have generated the following listener (only partial code shown here):
61
62 ```csharp
63 interface IMyGrammarParserListener : IParseTreeListener {
64 void EnterKey (MyGrammarParser.KeyContext context);
65 void ExitKey (MyGrammarParser.KeyContext context);
66 void EnterValue (MyGrammarParser.ValueContext context);
67 void ExitValue (MyGrammarParser.ValueContext context);
68 }
69 ```
70
71 In order to provide custom behavior, you might want to create the following class:
72
73 ```csharp
74 class KeyPrinter : MyGrammarBaseListener {
75 // override default listener behavior
76 void ExitKey (MyGrammarParser.KeyContext context) {
77 Console.WriteLine("Oh, a key!");
78 }
79 }
80 ```
81
82 In order to execute this listener, you would simply add the following lines to the above code:
83
84
85 ```csharp
86 ...
87 IParseTree tree = parser.StartRule() - only repeated here for reference
88 KeyPrinter printer = new KeyPrinter();
89 ParseTreeWalker.Default.Walk(printer, tree);
90 ```
91
92 Further information can be found from The Definitive ANTLR Reference book.
93
94 The C# implementation of ANTLR is as close as possible to the Java one, so you shouldn't find it difficult to adapt the examples for C#. See also [Sam Harwell's alternative C# target](https://github.com/tunnelvisionlabs/antlr4cs)
95