kcsparse - a ECMA-334 C# Grammar Sample for ANTLR 2.7.7 1 December, 2005 Kunle Odutola : kunle UNDERSCORE odutola AT hotmail DOT com Micheal Jordan 1. INTRODUCTION Congratulations, you have found 'kcsparse' - a nice YAC#GFA[*]! We hope you find 'kcsparse' delightful and useful even but, as per the license under which you may use it, this software is not guaranteed to work. See LICENSE.TXT for the full text of the license. ---------------------------------------------------------------------- THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ---------------------------------------------------------------------- 2. WHAT'S A YAC#GFA? Yet Another C# Grammar For ANTLR. This particular example is called 'kcsparse' and we hope you like it. It is probably a more complete and usable YAC#GFA than others. It is deliberately packaged in the style of the samples that are included with ANTLR itself (and may become one of the standard samples). In any event, it should just work out-of-the box for many C# source files. 2.1 WHAT kcsparse CAN DO - Parse C# 1.x source code including some with C# preprocessing directives. - Build an AST from the C# source. - Display the AST it builts from C# source. - Unparse the AST (i.e. pretty prints the AST) back to source code. 2.2 WHAT kcsparse CAN'T DO? - Full parse and resolve of the input C# source code. (kcsparse is NOT a C# front-end but, you can build one based on it) - Parse all C# 1.x source code (esp. those with use of preprocessing directives). (kcsparse is NOT a full C# 1.0 parser - it particularly fails on C# source files where simply deleting (or commenting out) all preprocessing directives results in illegal C# source but, you extend it to be) - Parse C# source code with C# 2.0 or later features like generics. (kcsparse is NOT a C# 2.0 parser but, you extend it to be) - Compile C# source code to MSIL, bytecode or any other lanaguage (kcsparse is NOT a C# translator/compiler but, you can build one based on it) - Interpret C# source code (kcsparse is NOT a C# interpreter but, you can build one based on it) - Mow your lawns or fetch you a cold beer (But we would like it to be!) 3. WHAT'S IN THE PACK? Along with this with file, you should have received the following: README.TXT This file LICENSE.TXT Our license for this software csharp_v1.build NAnt build file CSharpLexer.g Main C# lexer grammar file CSharpPreprocessorLexer.g C# lexer grammar file (used for preprocessor directives) CSharpPreprocessorHooverLexer.g C# lexer grammar file (used for preprocessor directives) CSharpLexerBase.g Common base for all C# lexer grammars UnicodeLexerBase.g Common base for unicode-savvy lexer grammars CSharpParser.g C# parser grammar file CSharpPrettyPrinter.g C# pretty printer grammar file CustomHiddenStreamToken.cs Custom IToken class ASTNode.cs Custom AST node class ASTNodeFactory.cs Custom ASTFactory class CodeMaskEnums.cs Helper class Main.cs Contains sample parsing application csharp.flex Lexer grammar file for use with C# Flex testfiles Directory containing test files to test C# parsing AllCSharpConstructs.cs Empty.cs EmptyNamespace.cs Testing.cs Using.cs UsingGlobalAttributes.cs Tools csflex.exe C# Flex executable runtime.dll [supplied with C# Flex] 4. USING kscparse The easiest way to use kcsparse is to unpack the files into a directory below the %ANTLR_HOME%/examples/csharp/ directory. This would "install" it just like any of the other ANTLR C# examples. Be sure to maintain the directory structure of the archive as shown above. Then, just type 'nant' (without the single quotes) to build and try kcsparse. This assumes that the ANTLR C# runtimes files have been compiled and are in the expected location. Once it is built, you can also run kcsparse directly yourself: kcsparse -- parse the specified kcsparse -flex -- parse the specified (uses flex lexer) kcsparse -- parse all *.cs files in kcsparse -flex -- parse all *.cs files in (uses flex lexer) kcsparse -showtree -- parse all *.cs files in and display the AST kcsparse -prettyprint -- parse and unparse (pretty-print) the AST to the console kcsparse -flex -prettyprint -- parse and unparse (pretty-print) the AST to the console (uses flex lexer) 5. kscparse STATUS kcsparse still has some bugs. kcsparse is mostly complete but expect a few rough edges.