Johannes Luber (Maintainer)
jaluber AT gmx.de
Kunle Odutola
kunle UNDERSCORE odutola AT hotmail.com
Micheal Jordan
In general, development progress on the C# target is likely to be sporadic.
As of September 2007, the C# code generator and runtime are NOT in sync with the latest release and development versions of the ANTLR tool and Java language target. The latest release of the v3.0.x C# code generator and 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 runtime with ANTLR v3.0.1 since that version was released in August 2007.
As of October 2007, the ANTLR source depot contains an early pre-beta release of the C# codegen and runtime for the upcoming ANTLR v3.1 release. Starting from the end of October, ANTLR daily builds of v3.1 have been available for those wishing to test the C# support with the new features of ANTLR v3.1.
As of May 2008, the C# target is in sync with the Java target of the upcoming ANTLR v3.1 beta release. This new version of the C# target breaks source compatibility with previous versions (including previous 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. The reason for this is three-fold:
CSharp
can retain it's compatibility with the .NET v1.1 platform. As such, it can't take advantage of C# v2 features in the code generation templates. The runtime will require twice the number of files, effectively doubling the amount of maintenance.CSharp2
target allows the existing CSharp
target to be deprecated without forcing people by abandoning .NET v1.1 compatibility immediately.Introducing the new target allows me to change even the code generation templates. As working on further enhancements will at least break binary compatibility, most of the changes will be done for ANTLR v3.2. During the life-time of ANTLR v3.1, the public API of the C# target(s) will be frozen. If you wish to future-proof your grammar, change them to use the new CSharp2
target. The original CSharp
target that used only C# v1 language features and .NET v1.1 is deprecated and the current plan is to remove it for the ANTLR v3.3 release.
The C# code generation templates and the CLR runtime library are feature complete for both targets. The 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 work as designed. This is currently a work-in-progess for the full v3.1 release.
As with all other targets, the C# code generation and runtime are modeled 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.
Microsoft .NET v1.1 and later
Mono v1.0 and later
Microsoft .NET v2.0 and later
Mono v1.2 and later
The compiled libraries are found in the distribution under the directory "runtime/csharp
" (or "runtime/csharp/bin
" in source distributions). Both targets use the same runtime. Intermediary builds may not have the current version and can be compiled by using the build tools.
Microsoft Visual Studio 2003 and 2005
Nant v0.85
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.
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
(or CSharp
for ANTLR version v3.0.x) as shown below:
grammar MyGrammar; options { language=CSharp2; } // rest of grammar follows .... |
For ANTLR version v3.0.x, please use the |
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 .... |
In addition to the the use of the @members
block to define class members inline within the grammar file, the CSharp2
target also supports the use of the C# v2 partial classes feature. This has the additional advantage that you can use your favourite editor for C# to define class members since ANTLRworks doesn't support syntax highlighting for target languages.
ANTLR grammars refer often to attributes of the tokens and rules. These attributes do not change because their use in a grammar targeted for C#. But when accessing those attributes from driver programs and other support files, the names used in the ANTLR grammar won't work. The C# target uses the official coding guidelines which are different from the general documentation.The following table details the status quo for ANTLR v3.1.
ANTLR |
C# Syntax |
Notes |
---|---|---|
text |
Text |
|
start |
Start |
|
stop |
Stop |
|
tree |
Tree |
|
st |
ST |
|
type |
Type |
|
line |
Line |
|
pos |
CharPositionInLine |
|
channel |
Channel |
|
$x.size() |
$x.Count |
size() is no grammar attribute, but still regularly used |
A problem, you may encounter while using the CSharp
target, is that value types are initialized with null (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 ] |
As you can see, only the inbuilt value types are supported. As adding value types to this map is an open-ended task, the maintainer does not make any changes in that structure for all users. Any changes have to be done by the user locally (and repeatedly for each new version of ANTLR). It is recommend that users switch to the CSharp2
target (which requires C# v2+ and .NET v2.0 or higher) as the problem has been fixed there in an environment-independent manner.
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:
-debug
option to ANTLRlocalhost
and 49153
respectively)ANTLRWorks remote debugging has only been tested for C# Parsers. TreeParsers and Lexers should work but... |