...

Johannes Luber (Maintainer)
jaluber AT gmx.de

Kunle Odutola
kunle UNDERSCORE odutola AT hotmail.com

Micheal Jordan

Contents

• #Getting Started
• #Architecture
• #Status
  #Version 3.0.x
  • #Version 3.1.x
• #Target Platforms
  • #CSharp CSharp target (versions 3.0.x and 3.1.x)
  • #CSharp2 CSharp2 target (version 3.1.x and later)
  • #Runtime Location
  • #Supported build tools
• #Performance
• #Source Code and Binaries
• #Bug Reports
• #Usage
  • #Specify that C# code should be generated for a grammar
  • #List of generated C# source files
  • #Specify a C# namespace for your recognizer
  • Preprocessor symbols (since ANTLR 3.1.2)
  • #Members blocks vs C# v2 Partial Classes
  • #Syntactic differences from the Java target
  • #Known Issues
  • #Debugging with ANTLRWorks

Architecture

...

Getting Started

If you want to setup and start using ANTLR with C# as quickly as possible please see the FAQ page on using ANTLR, ANTLRWorks, and C#.

However this page (not the FAQ page) provides architectural and background information useful to understanding the workings and usage of ANTLR and C#.

Architecture

The C# target consists of a set of code generation templates and a runtime library (written in C#) for the .NET/CLR platform. The C# code generation templates and the .NET/CLR runtime library are modeled on the Java version. As a consequence, the C# target supports features such as grammar development/prototyping and remote debugging with the superb ANTLRWorks integrated grammar development editor. Given ANTLRWorks popularity, this is very a important feature for ANTLR users.

...

In general, development progress on the C# target proceeds sporadically.

...

  With versions of ANTLR prior to 3.

...

1.x

...

As of September 2007, the C# code generator and runtime are NOT cannot be guaranteed to be in sync with the latest release and development versions of the ANTLR tool tools and Java language target. The latest release of the v3.0.x C# code generator and .NET/CLR runtime was developed for the ANTLR v3.0 release from July 2007. Nevertheless, no major problems have been reported by those using the C# codegen and .NET/CLR runtime with ANTLR v3.0.1 since that version was released in August 2007target.  When practical to do so, the latest 3.1.x released version is recommended for the C# target.

Version 3.1.x

As of August 2008, the C# target is in sync with ANTLR 3.1. This new version of the C# target breaks source compatibility with previous versions (including previous beta-v3.1 builds). To a certain extent, regeneration of grammars does help, but certain fields have been renamed to follow .NET conventions, which means PascalCase (e.g. .tree is now .Tree). The exception is .st, which is now .ST. Additionally, a new target named CSharp2 has been introduced in addition to the existing CSharp target. The reason for this is three-fold:

1. Firstly, CSharp can retain it's compatibility with C# v1 and the .NET/CLR v1.1 platform. CSharp is restricted to C# v1 features and doesn't take advantage of any C# v2+ features in the code it generates. As a consequence the runtime sources will now require twice the number of files (one set each for C# v1 and v2+), effectively doubling the amount of maintenance.
2. Secondly, a certain bug fix requires a C# v2 feature or, a change to the templates for each occurrence of the bug (and this has to be done by the user). Further details of this issue can be found in the #Known Issues section below.
3. Thirdly, because maintaining the backwards compatibility sucks majorly, creating the new CSharp2 target allows the existing CSharp target to be deprecated without forcing the issue by simply abandoning C# v1 .NET/CLR v1.1 compatibility immediately.

Introducing the new target allowed changes to be made to its distinct code generation templates without fear of breaking anything else. FurtherFurthermore, as working on further enhancements to CSharp2 will at least break binary compatibility in the .NET/CLR runtime which is currently shared with CSharp, most of the changes will be done for a future ANTLR v3.2 release. During the life-time of ANTLR v3.1, the public API of the C# target(s) will be frozen (only necessary bugfixes may break this). If you wish to future-proof your grammar, you should change them to use the new CSharp2 target. The original CSharp target that uses only C# v1 and .NET/CLR v1.1 features is deprecated and the current plan is to remove it for the ANTLR v3.3 2 release.

The C# code generation templates and the .NET/CLR runtime library are feature complete for the CSharp and CSharp2 targets. Both C# targets leverage the existing C# StringTemplate implementations to support the broadest range of the features that ANTLR provides. The long open issue of unit tests has finally been tackled with the adoption of MbUnit and the inclusion (in the v3.1 version) of a wide range of tests for the runtime library. As before, basic sanity checks will done by ensuring that the sample grammars in the examples-v3 archive function correctly. This is currently a work-in-progess for the v3.1 release.

...

For ANTLR 3.0.x there is no C# target source code available. ANTLR 3.1.x has the files under the runtime/CSharp directory. Binaries are currently (especially for betas) currently included in the bin directorydistro subdirectory, but will be moved later to available on the ANTLR download page as an extra itemwell. Available are the files in the official releases, in daily builds and for the head of the repo on the FishEye site (not reliable) or ask Terence Parr for a Perforce account.

...

Bug reports have to include a minimal grammar exposing the bug as well the ANTLR version used. If it is a compile time or a runtime problem, then the driver program, possible required backend files and, if applicable, the used input as well the driver program are also required. Optionally the reporter can check, if the Java target is affected by the same bug. If yes then one should report the bug to Terence Parr (over the mailing list or over the support form), as the C# target mimics the Java target behavior. Doing so isn't necessary (as the maintainer will compare the behaviors anyway), but speeds up the process. It may be possible that there is already a JIRA bug report. In that case, please mention it, too.

...

To specify that the ANTLR tool should generate C# code (rather than the default of generating Java code) for a grammar, set the grammar-level option named language to the value CSharp2 as shown below:

grammar MyGrammar;

options
{
    language=CSharp2;
}

// rest of grammar follows
....

...

For an example grammar named MyGrammar, the following table list the files that would be generated by ANTLR 3.1+ using the CSharp2 (and CSharp) target.

grammar MyGrammar;

options
{
    language=CSharp2;
}
// rest of grammar follows
....

lexer grammar MyGrammar;

options
{
    language=CSharp2;
}
// rest of grammar follows
....

parser grammar MyGrammar;

options
{
    language=CSharp2;
}
// rest of grammar follows
....

tree grammar MyGrammar;

options
{
    language=CSharp2;
}
// rest of grammar follows
....

...

You can specify that your generated recognizer should be declared within a specific namespace as shown below. By default all recognizers are generated as top-level types with no enclosing namespace.

grammar MyGrammar;

options
{
    language=CSharp2;
}

@parser::namespace { My.Custom.NameSpace.For.Parser.In.Combined.Grammar } // Or just @namespace { ... }

@lexer::namespace { My.Custom.NameSpace.For.Lexer.In.Combined.Grammar }

// rest of grammar follows
....

lexer grammar MyGrammar;

options
{
    language=CSharp2;
}

@namespace { My.Custom.NameSpace.For.Lexer }

// rest of grammar follows
....

parser grammar MyGrammar;

options
{
    language=CSharp2;
}

@namespace { My.Custom.NameSpace.For.Parser }

// rest of grammar follows
....

tree grammar MyGrammar;

options
{
    language=CSharp2;
}

@namespace { My.Custom.NameSpace.For.TreeParser }

// rest of grammar follows
....

Preprocessor symbols (since ANTLR 3.1.2)

When generating grammars in debug mode the following preprocessor symbol is defined:

#define ANTLR_DEBUG

It can be use like any other preprocessor symbol.

Members blocks vs C# v2 Partial Classes

...

A problem, you may encounter while using the CSharp target, is that value types are initialized with null in the generated code (happens e.g. while using labels). The cause lies in the following definition of CSharp.stg:

csharpTypeInitMap ::= [
    "int":"0",
    "uint":"0",
    "long":"0",
    "ulong":"0",
    "float":"0.0",
    "double":"0.0",
    "bool":"false",
    "byte":"0",
    "sbyte":"0",
    "short":"0",
    "ushort":"0",
    "char":"char.MinValue",
    default:"null" // anything other than an atomic type
]

...

He was also missing the Debugger|Exceptions menu item, which has been fixed by adjusting the profile, which had this option disabled by default. This is shown here. Once this was sorted out, ANTLR works perfectly when parsing invalid parser/lexer input.

...