antlr/Readme.md

C# target for ANTLR 4

Introduction

This document gives a basic overview of using the C# target for ANTLR 4 with C# projects in Visual Studio.

Available Targets

Currently the only target provided by this package is the CSharp target, which is specified by passing the -Dlanguage=CSharp option to the ANTLR 4 tool when the parsers are generated. This target is build against the .NET Framework version 4.5, and due to its use of IReadOnlyList<T> is not currently compatible with earlier releases.

Visual Studio Support for ANTLR 4 Grammars

Currently there is no Visual Studio extension specifically designed for editing ANTLR 4 grammars. However, now that a C# target for ANTLR 4 is available an editor should be available in the "reasonably near" future. If this feature is particularly important to your team, Tunnel Vision Labs' Sponsored Development Program may be a cost effective option for reducing the release timeframe.

Base Project Layout

C:\dev\CoolTool\
  CoolProject\
    CoolProject.csproj
  CoolTool.sln

Adding ANTLR to the Project Structure

1. Download the current C# release from the following location: TODO
2. Extract the files to C:\dev\CoolTool\Reference\Antlr4

After these steps, your folder should resemble the following.

C:\dev\CoolTool\
  CoolProject\...
  Reference\
    Antlr4\
      Antlr4.targets
      Antlr4BuildTasks.dll
      antlr4-csharp-[version]-complete.jar
  CoolTool.sln

MSBuild Support for ANTLR

Since the steps include manual modification of the Visual Studio project files, I very strongly recommend you back up your project (or commit it to source control) before attempting these steps.

1. Open the CoolTool.sln solution in Visual Studio

2. Unload the CoolProject project by right-clicking the project in Solution Explorer and selecting Unload Project

3. Open CoolProject.csproj for editing by right-clicking the unloaded project in Solution Explorer and selecting Edit CoolProject.csproj

4. For reference, locate the following line

    <Import Project="$(MSBuildBinPath)\Microsoft.CSharp.targets"/>
   

   Note: the line appears as follows in some projects

    <Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets"/>
   

5. After the line in step 4, add the following code

    <PropertyGroup>
      <!-- Folder containing Antlr4BuildTasks.dll -->
      <AntlrBuildTaskPath>$(ProjectDir)..\Reference\Antlr4</AntlrBuildTaskPath>
      <!-- Path to the ANTLR Tool itself. -->
      <AntlrToolPath>$(ProjectDir)..\Reference\Antlr4\antlr4-csharp-4.0.1-SNAPSHOT-complete.jar</AntlrToolPath>
    </PropertyGroup>
    <Import Project="$(ProjectDir)..\Reference\Antlr4\Antlr4.targets" /> 
   

6. Save and close CoolProject.csproj

7. Reload the CoolProject project by right-clicking the project in Solution Explorer and selecting Reload Project

Adding a Reference to the C# Runtime

In the CoolProject project, add a reference to Antlr4.Runtime.dll, which is located at C:\dev\CoolTool\Reference\Antlr4\Antlr4.Runtime.dll.

Grammars

TODO

Custom Token Specifications (*.tokens)

TODO

Generated Code

TODO

Extra Features in the C# Target

TODO

Example Grammars

TODO