Sophie: antlr-manual-0:2.7.7-6mdv2010.1 x86

antlr-manual-2.7.7-6mdv2010.1.x86_64.rpm

<html>

<head>
<title>Notes for using the ANTLR C# Code Generator</title>
</head>

<body bgcolor="#FFFFFF">

    <h1><strong>C# Code Generator for ANTLR 2.x</strong></h1>
    <p>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 <a href="http://www.microsoft.com/net/">Microsoft .NET platform</a> and, the <a href="http://www.go-mono.net">Mono</a> and <a href="http://www.dotGNU.org">dotGNU</a> open-source C#/CLI platforms.</p>
<p>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 <a  href="runtime.html">Java</a> and <a  href="cpp-runtime.html">C++</a> 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.</p>
<p>ANTLR C# support was contributed (and is maintained) by Kunle Odutola, Micheal Jordan and Anthony Oguntimehin.</p>

<h2><a name=t1>Building the ANTLR C# Runtime</a></h2>

<p>The ANTLR C# runtime source and build files are located in the <b><code>lib/csharp</code></b> subdirectory of the ANTLR distribution. This sub-directory is known as the <b>ANTLR C# runtime directory</b>. 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:</p>
<ul>
	<li>Using the <a href="http://msdn.microsoft.com/vstudio/">Microsoft Visual Studio .NET</a> development tool.
    <p>A Visual Studio.NET solution file named <code>antlr.net-runtime-2.7.&lt;X&gt;.sln</code> 
      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: 
    <ul>
	  <li><code>lib/csharp/src/antlr.runtime-2.7.&lt;X&gt;.csproj</code> - for 
        the ANTLR C# runtime library itself (where <code>X</code> is a version 
        number),</li>
      <li><code>lib/csharp/ASTFrame/antlr.astframe.csproj</code> - for the ANTLR 
        C# ASTFrame library (used for displaying ASTs) and,</li>
	  <li><code>examples/csharp/java/JavaParser.csproj</code> - for the Java grammar 
        project located within the ANTLR C# examples directory tree.</li>
</ul><p></p></li>
	<li>Using the freely available <a href="http://nant.sourceforge.net">NAnt</a> build tool.<p>A build file named <code>antlr.runtime.build</code> is located in the ANTLR C# runtime directory. To build the ANTLR C# runtime, run <blockquote><code>nant build</code></blockquote> from a command shell in the ANTLR C# runtime directory. You can also run <blockquote><code>nant release</code> <br/><code>nant docs</code></blockquote> to build a release version and documentation in <code>lib/csharp/release</code>.<p></p>
</ul>
<p>All the example grammars located in the ANTLR C# examples directory - <code>examples\csharp</code> are also supplied with a NAnt build file. Once the ANTLR C# library has been built, you can test it by running <blockquote><code>nant</code></blockquote> from a command shell in any of the example directories.<p></p>

<h2><a name=t2>Specifying Code Generation</a></h2>

<p>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.
<blockquote><pre>{
    <b>language  =  "CSharp";</b>
}
</pre></blockquote>
After that things are pretty much the same as in the default <b>java</b> code generation mode. See the examples in <code>examples/csharp</code> for some illustrations.
<ul>
	
  <li>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 <code>antlr.runtime.dll</code> 
    and <code>antlr.astframe.dll</code> assemblies during your build.</li>
</ul>
<p></p>

<h2><a name=t3>C#-Specific ANTLR Options</a></h2>

<ul>
	<li><b>header - specify additional <code>using</code> directives</b><p>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. <i>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</i>.
<blockquote><pre>
header
{
   using SymbolTable =  kunle.parser.SymbolTable;
   using kunle.compiler;
}
</pre></blockquote><p></p></li>

	<li><b>namespace - specify an enclosing C# Namespace</b><p>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.
<blockquote><pre>
{
   namespace  =  "kunle.smalltalk.parser";
}
</pre></blockquote><p></p></li>
</ul>

<h2><a name=t4>A Template C# ANTLR Grammar File</a></h2>

<p><blockquote><pre>
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 ...
</pre></blockquote><p></p>
</body>
</html>