manual.html

java cup constructor to compiler

terminal_id        ::= term_id
term_id            ::= symbol_id
new_term_id        ::= ID
new_non_term_id    ::= ID
nt_id              ::= ID
symbol_id          ::= ID
label_id           ::= ID
opt_semi	   ::= SEMI | empty

</tt></pre>
<hr><p><p>

<h3><a name = "appendixb">Appendix B. A Very Simple Example Scanner<a></h3>
<hr><br>
<pre>
<tt>// Simple Example Scanner Class

import java_cup.runtime.*;
import sym;

public class scanner {
  /* single lookahead character */
  protected static int next_char;

  /* advance input by one character */
  protected static void advance()
    throws java.io.IOException
    { next_char = System.in.read(); }

  /* initialize the scanner */
  public static void init()
    throws java.io.IOException
    { advance(); }

  /* recognize and return the next complete token */
  public static Symbol next_token()
    throws java.io.IOException
    {
      for (;;)
        switch (next_char)
	  {
	    case '0': case '1': case '2': case '3': case '4': 
	    case '5': case '6': case '7': case '8': case '9': 
	      /* parse a decimal integer */
	      int i_val = 0;
	      do {
	        i_val = i_val * 10 + (next_char - '0');
	        advance();
	      } while (next_char >= '0' && next_char <= '9');
	    return new Symbol(sym.NUMBER, new Integer(i_val));

	    case ';': advance(); return new Symbol(sym.SEMI);
	    case '+': advance(); return new Symbol(sym.PLUS);
	    case '-': advance(); return new Symbol(sym.MINUS);
	    case '*': advance(); return new Symbol(sym.TIMES);
	    case '/': advance(); return new Symbol(sym.DIVIDE);
	    case '%': advance(); return new Symbol(sym.MOD);
	    case '(': advance(); return new Symbol(sym.LPAREN);
	    case ')': advance(); return new Symbol(sym.RPAREN);

	    case -1: return new Symbol(sym.EOF);

	    default: 
	      /* in this simple scanner we just ignore everything else */
	      advance();
	    break;
	  }
    }
};
</tt></pre>


<a name=changes>
<h3>Appendix C:  Incompatibilites between CUP 0.9 and CUP 0.10</a></h3>

CUP version 0.10a is a major overhaul of CUP.  The changes are severe,
meaning no backwards compatibility to older versions.

The changes consist of:
<ul>
<li> <a href="#lex_inter">A different lexical interface</a>,
<li> <a href="#new_dec">New terminal/non-terminal declarations</a>,
<li> <a href="#label_ref">Different label references</a>,
<li> <a href="#RESULT_pass">A different way of passing RESULT</a>,
<li> <a href="#pos_prop">New position values and propagation</a>,
<li> <a href="#ret_val">Parser now returns a value</a>,
<li> <a href="#prec_add">Terminal precedence declarations</a> and
<li> <a href="#con_prec">Rule contextual precedence assignment</a>
</ul>

<h5><a name="lex_inter">Lexical Interface</a></h5>

CUP now interfaces with the lexer in a completely different
manner.  In the previous releases, a new class was used for every
distinct type of terminal.  This release, however, uses only one class:
The <tt>Symbol</tt> class.  The <tt>Symbol</tt> class has three instance
variables which 
are significant to the parser when passing information from the lexer.
The first is the <tt>value</tt> instance variable.  This variable 
contains the 
value of that terminal.  It is of the type declared as the terminal type
in the parser specification file.  The second two are the instance
variables <tt>left</tt> and <tt>right</tt>.  They should be filled with 
the <tt>int</tt> value of
where in the input file, character-wise, that terminal was found.<p>

For more information, refer to the manual on <a href="#lex_part">scanners</a>.

<h5><a name="new_dec">Terminal/Non-Terminal Declarations</a></h5>

Terminal and non-terminal declarations now can be declared in two
different ways to indicate the values of the terminals or
non-terminals.  The previous declarations of the form

<pre><tt>
terminal <i>classname terminal</i> [, <i>terminal ...</i>];
</tt></pre> 

still works.  The classname, however indicates the type of the value of
the terminal or non-terminal, and does not indicate the type of object
placed on the parse stack.

A declaration, such as:

<pre><tt>
terminal <i>terminal</i> [, <i>terminal ...</i>];
</tt></pre> 

indicates the terminals in the list hold no value.<p>

For more information, refer to the manual on <a
href="#symbol_list">declarations</a>.

<h5><a name="label_ref">Label References</a></h5>

Label references do not refer to the object on the parse stack, as in
the old CUP, but rather to the value of the <tt>value</tt> 
instance variable of
the <tt>Symbol</tt> that represents that terminal or non-terminal.  Hence,
references to terminal and non-terminal values is direct, as opposed to
the old CUP, where the labels referred to objects containing the value
of the terminal or non-terminal.<p>

For more information, refer to the manual on <a href="#label_part">labels</a>.

<h5><a name="RESULT_pass">RESULT Value</a></h5>

The <tt>RESULT</tt> variable refers directly to the value of the 
non-terminal
to which a rule reduces, rather than to the object on the parse stack.
Hence, <tt>RESULT</tt> is of the same type the non-terminal to which 
it reduces, 
as declared in the non-terminal declaration.  Again, the reference is
direct, rather than to something that will contain the data.<p>

For more information, refer to the manual on <a href="#RES_part">RESULT</a>.

<h5><a name="pos_prop">Position Propagation</a></h5>

For every label, two more variables are declared, which are the label
plus <tt>left</tt> or the label plus <tt>right</tt>.  These correspond 
to the left and
right locations in the input stream to which that terminal or
non-terminal came from.  These values are propagated from the input
terminals, so that the starting non-terminal should have a left value of
0 and a right value of the location of the last character read.<p>

For more information, refer to the manual on <a href="#label_part">positions</a>. 

<h5><a name="ret_val">Return Value</a></h5>

A call to <tt>parse()</tt> or <tt>debug_parse()</tt> returns a
Symbol.  This Symbol is the start non-terminal, so the <tt>value</tt> 
instance variable contains the final <tt>RESULT</tt> assignment. 

<h5><a name="prec_add">Precedence</a></h5>

CUP now has precedenced terminals.  a new declaration section,
occurring between the terminal and non-terminal declarations and the
grammar specifies the precedence and associativity of rules.  The
declarations are of the form:

<pre><tt>
precedence {left| right | nonassoc} <i>terminal</i>[, <i>terminal</i> ...];
...
</tt>
</pre>

The terminals are assigned a precedence, where terminals on the same
line have equal precedences, and the precedence declarations farther
down the list of precedence declarations have higher precedence.  
<tt>left, right</tt> and <tt>nonassoc</tt> specify the associativity 
of these terminals.  left
associativity corresponds to a reduce on conflict, right to a shift on
conflict, and nonassoc to an error on conflict.  Hence, ambiguous
grammars may now be used.<p>  

For more information, refer to the manual on <a
href="#precedence">precedence</a>.

<h5><a name="con_prec">Contextual Precedence</a></h5>

Finally the new CUP adds contextual precedence.  A production may be
declare as followed:

<pre><tt>
lhs ::= <i>{right hand side list of terminals, non-terminals and actions}</i>
        %prec <i>{terminal}</i>;
</tt></pre>

this production would then have a precedence equal to the terminal
specified after the <tt>%prec</tt>.  Hence, shift/reduce conflicts can be
contextually resolved.  Note that the <tt>%prec</tt> <i>terminal</i> 
part comes after all actions strings.  It does not come before the 
last action string.<p>

For more information, refer to the manual on <a href="#cpp">contextual
precedence</a>.

These changes implemented by:
<h3>
<a href="http://www.princeton.edu/~frankf">Frank Flannery</a><br>
<a href="http://www.cs.princeton.edu">Department of Computer Science</a><br>
<a href="http://www.princeton.edu">Princeton University</a><br>
</h3>
<a name=bugs>
<h3>Appendix D:  Bugs</a></h3>
In this version of CUP it's difficult for the semantic action phrases (Java code attached
to productions) to access the <tt>report_error</tt> method and other similar methods and
objects defined in the <tt>parser code</tt> directive.
<p>
This is because the parsing tables (and parsing engine) are in one object (belonging to
class <tt>parser</tt> or whatever name is specified by the <strong>-parser</strong> directive),
and the semantic actions are in another object (of class <tt>CUP$actions</tt>).
<p>
However, there is a way to do it, though it's a bit inelegant.
The action object has a <tt>private final</tt> field named
<tt>parser</tt> that points to the parsing object.  Thus,
methods and instance variables of the parser can be accessed within semantic actions as:
<pre>
    parser.report_error(message,info);
    x = parser.mydata;
</pre>
<p>
Perhaps this will not be necessary in a future release, and that
such methods and variables as <tt>report_error</tt> and
<tt>mydata</tt> will be available
directly from the semantic actions; we will achieve this by combining the 
"parser" object and the "actions" object together.
 
<p>
For a list of any other currently known bugs in CUP, see
<A HREF="http://www.cs.princeton.edu/~appel/modern/java/CUP/bugs.html">
http://www.cs.princeton.edu/~appel/modern/java/CUP/bugs.html</A>.

<a name=version>
<h3>Appendix E:  Change log</a></h3>

<dl>
<dt>0.9e<dd>March 1996, Scott Hudson's original version.
<dt>0.10a<dd>August 1996, <a href="#about">several major changes</a> to
the interface.
<dt>0.10b<dd>November 1996, fixes a few minor bugs.
<dt>0.10c<dd>July 1997, fixes a bug related to precedence declarations.
<dt>0.10e<dd>September 1997, fixes a bug introduced in 0.10c relating
to <tt>nonassoc</tt> precedence.  Thanks to 
<a href="http://www.cs.purdue.edu/homes/hosking">Tony Hosking</a> 
for reporting the bug and providing the fix.
Also recognizes carriage-return character as white space and fixes a
number of other small bugs.
<dt>0.10f<dd>December 1997, was a maintenance release.  The CUP source
was cleaned up for JDK 1.1.
<dt>0.10g<dd>March 1998, adds new features and fixes old bugs.
The behavior of RESULT assignments was normalized, and a problem
with implicit start productions was fixed.  The CUP grammar was
extended to allow array types for terminals and non-terminals, and
a command-line flag was added to allow the generation of a symbol
<i>interface</i>, rather than class.  Bugs associated with multiple
invocations of a single parser object and multiple CUP classes in one 
package have been stomped on.  Documentation was updated, as well.
<dt>0.10h-0.10i<dd>February 1999, are maintenance releases.
<dt>0.10j<dd>July 1999, broadened the CUP input grammar to allow more
flexibility and improved scanner integration via the
<code>java_cup.r