Versions Compared

Old Version 49

changes.mady.by.user Former user

Saved on

compared with

New Version 50

changes.mady.by.user Former user

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: More info on assembly references

...

Kunle Odutola
kunle UNDERSCORE odutola AT hotmail.com

Micheal Jordan

Contents

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.

The .NET/CLR runtime library currently consists of two assemblies named Antlr3.Runtime.dll and Antlr3.Utility.dll. All projects that include an ANTLR v3.x Lexer, Parser or TreeParser must include a reference to:

  1. Antlr3.Runtime.dll - the ANTLR v3.x .NET/CLR runtime library
  2. Antlr3.Utility.dll - OPTIONAL - only required if you use the DOTTreeGenerator class (correct as of May 2008)

No other references are required (except to the manadatory System assembly).

For projects that use the in-built integration with StringTemplate, the following assemblies must also be referenced:

  1. StringTemplate.dll - the C# StringTemplate v3.x library (a.k.a ST# v3.x)
  2. antlr.runtime.dll - the ANTLR v2.7.x .NET/CLR runtime library (ST# v3.x was developed with ANTLR v2.7.x)

Status

In general, development progress on the C# target is likely to be sporadicproceeds sporadically.

Version 3.0.x

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 .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 2007.

...

As of October 2007, the ANTLR source depot contains an early pre-beta release of the C# codegen and .NET/CLR 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 in addition to the existing CSharp target. The reason for this is three-fold:

  1. Firstly, the old target named CSharp can retain it's compatibility with C# v1 and the .NET/CLR v1.1 platform. As such, it can CSharp is restricted to C# v1 features and doesn't take advantage of any C# v2+ features in the code generation templates. The runtime will 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 occurence occurrence of the bug - (and this has to be done by the user). The Further details of doing so are 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 people the issue by simply abandoning C# v1 .NET/CLR v1.1 compatibility immediately.

Introducing the new target allows me to change even the allowed changes to be made to it's distinct code generation templates . As without fear of breaking anything else. Further, 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 realease. 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, you should change them to use the new CSharp2 target. The original CSharp target that used uses only C# v1 language features and .NET/CLR v1.1 features is deprecated and, the current plan is to remove it for the ANTLR v3.3 release.

The C# code generation templates and the .NET/CLR runtime library are feature complete for both the CSharp and CSharp2 targets. The 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 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.

Target Platforms

CSharp target (versions 3.0.x and 3.1.x only)

...

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 .NET/CLR runtime. Intermediary builds may not have the current version and can be compiled by using the build tools.

...

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:

Code Block
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 in-built value types are supported . As (or can be reasonably supported). Since 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.

...