C# Code Generator for ANTLR 2.x

Since the release of ANTLR 2.7.3, it has been possible to generate your Lexers, Parsers and TreeParsers in the ECMA-standard C# language developed by Microsoft. This feature extends the benefits of ANTLR's predicated-LL(k) parsing technology to applications and components running on the Microsoft .NET platform and, the Mono and dotGNU open-source C#/CLI platforms.

To be able to build and use the C# language Lexers, Parsers and TreeParsers, you will need to link to the ANTLR C# runtime library. The C# runtime model is based on the existing runtime models for Java and C++ and is thus immediately familiar. The C# runtime and the Java runtime in particular are very similar although there a number of subtle (and not so subtle) differences. Some of these result from differences in the respective runtime environments.

ANTLR C# support was contributed (and is maintained) by Kunle Odutola, Micheal Jordan and Anthony Oguntimehin.

Building the ANTLR C# Runtime

The ANTLR C# runtime source and build files are located in the lib/csharp subdirectory of the ANTLR distribution. This sub-directory is known as the ANTLR C# runtime directory. The first step in building the ANTLR C# runtime library is to ensure that ANTLR has been properly installed and built. This process is described in the ANTLR Installation Guide that comes with the distribution. Once ANTLR has been properly built, the ANTLR C# runtime can be built using any one of two distinct methods:

Using the Microsoft Visual Studio .NET development tool.
A Visual Studio.NET solution file named antlr.net-runtime-2.7.<X>.sln is provided in the ANTLR C# runtime directory. This allows you to build the ANTLR C# runtime library and test it with a semi-complex grammar. The solution file references three Visual Studio .NET project files:
- lib/csharp/src/antlr.runtime-2.7.<X>.csproj - for the ANTLR C# runtime library itself (where X is a version number),
- lib/csharp/ASTFrame/antlr.astframe.csproj - for the ANTLR C# ASTFrame library (used for displaying ASTs) and,
- examples/csharp/java/JavaParser.csproj - for the Java grammar project located within the ANTLR C# examples directory tree.
Using the freely available NAnt build tool.
A build file named antlr.runtime.build is located in the ANTLR C# runtime directory. To build the ANTLR C# runtime, run
nant build
from a command shell in the ANTLR C# runtime directory. You can also run
nant release
nant docs
to build a release version and documentation in lib/csharp/release.

All the example grammars located in the ANTLR C# examples directory - examples\csharp are also supplied with a NAnt build file. Once the ANTLR C# library has been built, you can test it by running

nant

from a command shell in any of the example directories.

Specifying Code Generation

You can instruct ANTLR to generate your Lexers, Parsers and TreeParsers using the C# code generator by adding the following entry to the global options section at the beginning of your grammar file.

{
    language  =  "CSharp";
}

After that things are pretty much the same as in the default java code generation mode. See the examples in examples/csharp for some illustrations.

TIP: If you are new to NAnt, ANTLR or the .NET platform, you might want to build your ANTLR projects with something similar to the NANT build files used for the C# examples. The build file for java example in particular also shows one way to automatically copy and reference both the antlr.runtime.dll and antlr.astframe.dll assemblies during your build.

C#-Specific ANTLR Options

header - specify additional using directives
You can instruct the ANTLR C# code generator to include additional using directives in your generated Lexer/Parser/TreeParser by listing the directives within the header section which must be the first section at the beginning of your ANTLR grammar file. Please note that using directives are the only source code elements that can currently be safely included in the header section for C# code generation.
```
header
{
   using SymbolTable =  kunle.parser.SymbolTable;
   using kunle.compiler;
}
```
namespace - specify an enclosing C# Namespace
You can instruct the ANTLR C# code generator to place your Lexer/Parser/TreeParser in a specific C# namespace by adding a namespace option to either the global options section at the beginiing of your ANTLR grammar file or, to the grammar options section for individual Lexers/Parsers/TreeParsers.
```
{
   namespace  =  "kunle.smalltalk.parser";
}
```

A Template C# ANTLR Grammar File

header 
{
    // gets inserted in the C# source file before any
    // generated namespace declarations
    // hence -- can only be using directives
}

options {
    language  = "CSharp";
    namespace = "something";          // encapsulate code in this namespace
    classHeaderPrefix = "protected"; // use to specify access level for generated class
}

{
   // global code stuff that will be included in the source file just before the 'MyParser' class below
   ...
}
class MyParser extends Parser;
options {
   exportVocab=My;
}
{
   // additional methods and members for the generated 'MyParser' class
   ...
}

... generated RULES go here ...

{
   // global code stuff that will be included in the source file just before the 'MyLexer' class below
   ...
}
class MyLexer extends Lexer;
options {
   exportVocab=My;
}
{
   // additional methods and members for the generated 'MyParser' class
   ...
}

... generated RULES go here ...

{
   // global code stuff that will be included in the source file just before the 'MyTreeParser' class below
   ...
}
class MyTreeParser extends TreeParser;
options {
   exportVocab=My;
}
{
   // additional methods and members for the generated 'MyParser' class
   ...
}

... generated RULES go here ...