Last changed on 12.5.2005

C# CUP Manual

Samuel Imriska

based on CUP v0.10j by Scott E. Hudson

 Table of Contents

1. About C# CUP

2. Installation and Requirements
   

3. Running C# CUP
   

4. Changes against original CUP
   

5. JAVA-->C# Tutorial

6. Lexical Analyzer (lexer)
   

7. Examples
   

8. Download
   

9. References
   

    About C# CUP

C# CUP is a C# version of the popular Java based Parser Constructor CUP[1]. C# as a representant of the .NET Language Family is more often used in business and for educational purpose. It's clear that a tool for building automatic LR-Parser in such language will be useful in future. The difference between C# and Java lies more in the different System libraries as in the language specification. Therefore it was not very difficult to translate existing Java CUP to the .NET platform. This make possible to change developing platform with minimal effort on adaptation in existing cup specification files. For more information about compiler building and parsing i recommend you the YACC manual or book[3].

Parser cannot work without appropriate lexer (Tokenizer Tool). JLex is mostly used with JAVA CUP and I translated this tool too to the .NET platform(see the CS_Lex Homepage[2]).

This project was done during as by baccalaureus project at Distributed System Group on the Vienna Technical University. I would like to thank the department and especially Engin Kirda, my supervisor, for his support.

Installation and Requirements

.NET Platform made the redistribution and installation of application much easier. C# CUP is provided in two different forms.

You can get C# CUP as compiled application with DLL-library. The whole installation consist of unpacking this two files in a same directory. To run C# CUP you need .NET Framework 1.0.3705 or higher installed on your computer. The DLL Library contains Runtime classes definition. This classes are needed to use the generated files later in your own application. Therefore they are in separated in DLL. If you wish you can of course make your own compilation from the source codes, where all classes will be in a single application.

You can get C# Cup source codes files. There are many reasons why you would like to have them. At first you can put the Runtime Classes directly into your own application without the need of external DLL libraries. Otherwise you could find some bugs in CUP ;-) and you would like to fix them. However you can try it...

To compile the source files I recommend the usage of Visual Studio .NET but you can do that also with the command-line C#compiler (csc), which is in the .NET Framework SDK.

Running C# CUP 

On a computer with installed .NET Framework the command-line usage of C# Cup is:   C# CUP.exe [options] <cs_cup_definition.cup>

You can omit all options at all. For full specification of of command-line switches see the original Java CUP specification[1]. The most important of them are:

• -parser name :  you can specify different name for the parser class (default:parser)
• -symbols name: you can specify different name for the symbol class (default:sym)
• -nowarn : turns off all warning messages
• -nosummary : turns off the final report
• -debug : turns all debug messages on

Changes against original CUP

 The language specification is almost equal to the CUP Specification(0.10j version). You have to define terminal and nonterminal symbols. Afterwards you have to specify the grammar how non-terminals are build up. Finally you have to define user code, which is executed on operators and functions. For complete specification see the original Java CUP manual.

The only difference to the Java Specification, is that you have to use C# code in the user-code block. According to different keywords in C# you have to use namespace instead of package. And usage instead of import.

JAVA-->C# Tutorial

How to modify your older CUP Specification files 

Java and C# are very similar languages, but there remains some differences, which should be noticed in case of conversion to .NET platform. A Java Conversion Assistant from Microsoft exists, which should mostly automatically perform this conversion. As I don't have the proper .NET Version I couldn't use it, so I'm not able to comment this tool. However the transformation is not too difficult and for smaller projects it's maybe more effective to do it manually in order to learn and understand the differences in the languages. The following list should be a guide or checklist.

• Name of File and class name don't need to be identical
  
   
• Starting Function is now 'public static Main(string[] args);'
  
   
• Primitive types: Boolean(Java) ->bool(C#), String -> string, Object ->object , Integer -> Int32
  
   
• string(Java) is in contrast to String(C#) a primitive type and constructor of 'new string()' doesn't exist
  
   
• Int32 is only a struct. Like the JavaInteger it contains many useful static functions but a null value cannot be assigned. In that case I used basic object instead.
  
   
• most system functions in C# starts with capital letter and differs in this way from Java notation, this name difference is mostly the single one.
  
   
• Common Input/Output:  System.in/out were replaced by System.Console.In/Out. The basic printing function are called Write/WriteLine
  
   
• File and Text Streaming are very simplified and the use is much easier, TextWriter is thebasic output class, TextReader/StreamReader the input classes
  
   
• instanceof(Java) operator is not present. Conversion is done in following way: 'a instanceof b' -> 'a.GetType()==typeof(b)'
  
   
• StringBuffer class is replaced by very similar class System.Text.StringBuilder
  
   
• Most of container classes are in System.Collections namespace
  
   
• Most container classes have basic indexing so use   'a.get(index)' -> 'a[index]'(C#) instead
  
   
• Conversion of Primitive types to object types is not necessary it's done automatically
  
   
• Also 'primitive type'->string is done implicit in printing functions
  
   
• package instructions is replaced by namespaces. 'package <name>;' -> 'namespace name { class block } . There are some differences like classes defined in namespaces can have only public or internal acces.
  
   
• import clause is replaced by using, where only namespaces can be defined and not direct classes 'import java.util.*;' -> 'using System.Collections;' (C#)
  
   
• in switch/case statements  each case statement have to have and exit statement like break/continue/return....
  
   
• Exception handling is very simplified. Throwing clause in function definition is not possible and you can throw an exception on each place of a program. try/catch/finally have the same meaning like in Java
  
   
• system.exit(code) -> System.Envirnment.Exit(code);
  
   
• Inheritance and overloading are quite different. I suggest you to study some C# Tutorial or online help. The basic idea is that if you are overloading a abstract function you have to add 'override' clause. In case you are doing simple overloading in a child class a 'new' clause in function head is necessary.
  
   
• C# compiler is a little bit stricter and is doing some additional checks, like if all variable are used and values are assigned. protection levels of functions and variables are checked and have to be consistent
  
   
• final keyword is replaced by sealed with a little different meaning. Sealed can be used only for functions and only those which were abstract. There is no possibility for variables or properties.
  
   
• Constant definition is much easier 'public static final ... '-> 'public const ....'
  
   
• Additional keyword readonly can protect variables from changes
  
   
• C# have Properties ,what are variables with special Get/Set methods
  
   
• C# have some additional keywords which must's be used as variable names: out,get,set,in
  
   
• All primitive parameters are transferred by value all other by reference. You can change this with ref keyword in function definition and use
  
   
• Some special characters cannot be used in variable names in contrast to Java (like $,§ ...)
  
   
• Array parenthesis are always written behind the type 'int codes[];' -> ' int[] codes;'(C#)
  
   

This list is not complete and should be taken only like a starting help. As I already mentioned the system functions differ mostly only in the first letter or in the writing, but the are exceptions. Some Classes are left out or are total rewritten. Some functions can be missing. So you have to check this and possible make some of them by yourself.

There is one more difference in the Interfaces Enumaration -> IEnumerator. IEnumerator have a MoveNext() functions which advance to a new element and returns if this movement was successful. The current Element can be retrieved by .Current. This is a small example of equivalent codes in Java and C#

Lexical Analyzer (lexer)

A full- functional parser is not working without an lexical analyzer, which split the file input into tokens symbols. Each time the parser is ready to work a new symbol it calls scanner.next_token(). The scanner should return an object of the type Symbol. This contains the next analyzed symbol. The questions remains, how do we get such lexer. Of course it's possible to write one by himself. This way is not very comfortable if working with definition, which changing ofen or is really complex.

The JLex is really good tool to build automatic lexer from a simple rule definition. I have rewritten it also to C# and you can read more on the C#Lex Site [2]. This tool have a switch, which generates C#CUP conform lexer, which are mostly even quicklier as hand-written lexer.

  Examples

One example can mostly explain more than thousand words of description. I took the examples suplied with JCup and translated them to C# Cup.

The first one named minimal.cup defines a minimalistic calculator with plus and multiply on positive integers with paranthesis support. Each expression have to be ended with ';'. Afterwards its evalueted by the parser. To have a fully runnable application a C#Lex example file is included, which contains definition of simple lexer for this task. Together with C#Lex you lexer file( minimal.lex.cs). C#Cup produce in basic configuration parser.cs and sym.cs. These 3 files together makes already runnable application, which you can test and enlarge in order to get accustommed with C#CUP.

The second one names calc.cup contains definition of a simple calculator. With just basic instructions defined. As there is no lexer or lex file defined you have to build a simple wrapper-application arround or adapt lexer file from the another example.

The whole grammar definition of C#Cup is also defined in a cup file. This means you can build up a new parser class for the C#CUP definition. This new parser class is identical with the suplied parser file in the source code, only in different style and with less comments. I recommend to look on it to see more complex definitions too.

    Download

Following files are available for download:

C# CUP Executables: Contains an .NET Application and DLL with the Runtime Classes
Source Codes : Zipped package with c# source codes
Examples: Some example specification of CUP
JAVA CUP Specification (mirrored)

CUP was originally written by Scott Hudson, in August of 1995.

It was extended to support precedence by Frank Flannery, in July of 1996.

It was translated to C# and .NET Plattform by Samuel Imriska in September 2003 as part of my baccalareus work on Vienna Technical University.

I would like to thank to all that people, who send me mails, if some bug or missing file occurs. Without those people, who forward their knowledge and problems the Internet community wouldn't be the same.

References

CUP Specification: http://www.cs.princeton.edu/~appel/modern/java/CUP/

 
C# Lex : Translation of the popular JLex tool (tokenizer generator)

 
S. C. Johnson, "YACC &emdash; Yet Another Compiler Compiler", CS Technical Report #32, Bell Telephone Laboratories, Murray Hill, NJ, 1975
C#Cup Homepage