75 lines
3.6 KiB
Markdown
75 lines
3.6 KiB
Markdown
# C# target for ANTLR 4
|
|
|
|
### Note to historical users
|
|
|
|
Versions of ANTLR 4.4.x and before managed the C#
|
|
target as part of a [separate tool provided by Sam Harwell](https://github.com/tunnelvisionlabs/antlr4cs/releases/tag/v4.3.0).
|
|
As of 4.5, we our releasing a (mono-compatible) C# target together
|
|
with the main tool.
|
|
|
|
Mono compatibility makes it possible to use ANTLR 4 in any C# development
|
|
environment, including of course Microsoft Visual Studio, but also Xamarin Studio, which runs on MacOS X.
|
|
Given Microsoft's recent commitment to *cross-platform developer experiences*,
|
|
we believe this is a great opportunity for C# developers.
|
|
|
|
Releasing the runtime with the tool ensures that you can get the exact same behavior across many languages: Java, C#, Python, JavaScript, Go, Swift and C++.
|
|
|
|
## Getting Started
|
|
|
|
### Step 1: Install Java
|
|
|
|
The C# target for ANTLR 4 requires Java for *generating* C# code (but the applications compiled from this C# code will not require Java to be installed).
|
|
You can install *any* of the following versions of Java to use this target.
|
|
|
|
If you already have one of the following installed, you should check to make sure the installation is up-to-date.
|
|
|
|
* Java 8 runtime environment (x86 or x64)
|
|
* Java 8 development kit (x86 or x64, provided that the JRE option is also installed during the development kit installation)
|
|
* Java 7 runtime environment (x86 or x64)
|
|
* Java 7 development kit (x86 or x64, provided that the JRE option is also installed during the development kit installation)
|
|
|
|
### Step 2: Download the tool
|
|
|
|
You need to download the ANTLR tool from the ANTLR web site.
|
|
This is a Java archive (*.jar) used to generate the C# code from an ANTLR grammar.
|
|
|
|
|
|
### Step 3: Add or create a grammar file (*.g4) in your project
|
|
|
|
To avoid confusing your IDE, we suggest setting the build action to None for this file.
|
|
See the docs and the book to learn about writing lexer and parser grammars.
|
|
|
|
|
|
### Step 4: Generate the C# code
|
|
|
|
This can be done either from the cmd line, or by adding a custom pre-build command in your project.
|
|
At minimal, the cmd line should look as follows: ``java -jar antlr4-4.7.jar -Dlanguage=CSharp grammar.g4``
|
|
This will generate the files, which you can then integrate in your project.
|
|
This is just a quick start. The tool has many useful options to control generation, please refer to its documentation.
|
|
|
|
### Step 5: Add a reference to the ANTLR runtime in your project
|
|
|
|
The Antlr 4 standard runtime for C# is now available from NuGet.
|
|
We trust that you know how to do add NuGet references to your project :-).
|
|
The package id is Antlr4.Runtime.Standard. We do not support other packages.
|
|
|
|
|
|
### Step 6: You're done!
|
|
|
|
Of course, the generated code is not going to meet your requirement by magic.
|
|
There are 3 ways to use the generated code:
|
|
- by generating a parse tree, and traversing it using a listener. This is the most common method.
|
|
- by generating a parse tree, and traversing it using a visitor. This requires the -visitor option, and is a bit more work.
|
|
- by providing code within your grammar, which gets executed when your input files are parsed.
|
|
While the latter works, it is no longer the recommended approach, because it is not portable, and harder to maintain. More importantly, it breaks the parsing when your code breaks.
|
|
|
|
See the web site for examples of using the generated code.
|
|
|
|
To learn more about ANTLR 4, read [the book](http://a.co/2n4rJlb).
|
|
|
|
### Visual Studio integration
|
|
|
|
If you require tighter Visual Studio integration, you can use the tools from [Tunnel Vision Labs](http://tunnelvisionlabs.com/).
|
|
(please note however that they use a different tool and runtime)
|
|
|