ANTLR v3 C# Code generator and Runtime library

Kunle Odutola
kunle UNDERSCORE odutola AT hotmail.com

Micheal Jordan

Contents

• #Status
• #Architecture
• #Target Platforms
  • #Supported build tools
• #Performance
• #Usage
  • #Generating C# code from a grammar
  • #Specifying the namespace for your recognizer
  • #Syntactic differences from the Java target
  • #Debugging with ANTLRWorks

Status

As of July 2007, the C# code generator and runtime are in sync with the development of the ANTLR tool and Java language target. As before, development progress going forwards is likely to be sporadic.

The C# code generation templates and the CLR runtime library are feature complete. The C# (and Python) targets have a definite advantage due to the existence of native StringTemplate implementations. Unfortunately, automated tests are yet to be written for the target. Some basic sanity check are done however - primarily checking that the sample grammars in the examples-v3 archive works as designed.

UPDATE: Some of the other targets apparently have some automated unit tests already. Hopefully this can suggest an approach that is applicable to the C# target too.

Architecture

As with all other targets, the C# code generation and runtime are modelled on the Java version. This means the C# target supports features such as grammar development/prototyping and remote debugging with the AntlrWorks GUI which is very important for ANTLR users.

Target Platforms

Microsoft .NET v1.1 and v2.0
Mono

Supported build tools

Microsoft Visual Studio 2003 and 2005
Nant v0.85

Performance

The V3 target generates code that is easily faster than that generated by the V2 target (especially the lexers). We probably won't be able to match the bare-metal performance of the code generated by Jim Idle's C target or Ric Klaren's C++ target but, we expect to be very competitive with the other targets.

Usage

Generating C# code from a grammar

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 CSharp as shown below:

grammar MyGrammar;

options
{
    language=CSharp;
}

// rest of grammar follows
....

Specifying the namespace for your recognizer

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

@lexer::namespace {
	My.Custom.NameSpace.For.Lexers
}

@parser::namespace {
	My.Custom.NameSpace.For.ParsersInclTreeParsers
}

Syntactic differences from the Java target

The C# target uses language features like properties as the official coding guidelines which cause the general documentation to differ from what can be really used for the C# target. The rule of thumb is, that the attributes of rules are accessed with a capital letter at the beginning. Nonetheless there are exceptions so the goal is to have a comprehensive overview. If there are any errors, please fix them or send an email to the mailing list.

Debugging with ANTLRWorks

The ANTLRWorks tool is written in Java and is only able to debug Java recognizers directly. Nevertheless, you can debug your C# recognizers with ANTLRWorks by using the Remote Debugging feature of ANTLRWorks. In ANTLRWorks, Remote Debugging works by connectiong to a running instance of a debug-instrumented recognizer (generated with the -debug switch to ANTLR) over the network.

To debug your C# recognizer with ANTLRWorks:

1. Generate a debuggable version of your recognizer by specifying the -debug option to ANTLR
2. Create a driver program that creates your recognizer and runs some test input through it (see the examples-v3 archive for sample driver programs)
3. Compile your driver and recognizer to produce your executable file(s)
4. Execute your driver program (it will launch your recognizer and appear to hang - it's just waiting for ANTLRWorks to connect)
5. Start ANTLRWorks (or switch to it if it is already running) and click the menu Debugger|Debug Remote...
6. Click Connect to accept the default host and port values (localhost and 49153 respectively)
7. ANTLRWorks should now start debugging your recognizer!

   Warning

   ANTLRWorks remote debugging has only been tested for C# Parsers. TreeParsers and Lexers should work but...