## Using Jacc

These are instructions on how to use `Jacc`.

### Accessing the package

Copy the file `hlt.zip` to wherever you deem appropriate in your file system, unzip it, and enable your class path to access the unzipped jar files `hlt.jar` and `jdom.jar`.

Then, invoking `Jacc` on a grammar file from a terminal console is done by typing:

    java hlt.language.syntax.Jacc <grammar file>

Or, more conveniently by defining a command for invoking `Jacc`; e.g., in UNIX:

    alias jacc java hlt.language.syntax.Jacc

so that one need only type:

    jacc <grammar file>

to invoke it. Options available to `Jacc` are described by specifying no arguments. Thus:

    jacc

    Usage: jacc [options] grammar_file(s)

    Option   (Default)    Description
    ------   ---------    -----------
    -e       (System.err) redirect errors to the specified file
    -choices (10)         max size of choice history (for dynamic parsing)
    -amb     ()           allow ambiguous actions (for dynamic parsing)
    -n       ()           do not generate the parser
    -o       (System.out) redirect the log to the specified file
    -m       (1000)       max number of instructions in parser initialization method
    -rf      ()           copy doc resource files
    -i       ()           tolerate an incomplete grammar (no parser is generated)
    -v       (1)          information verbosity (number between 0 and 4)
    -dest    (.)          where Jacc will write the generated parser file
    -s       (/)          file separator character
    -p       (Parser)     parser name (default: grammar="Foo.grm" => parser="FooParser.java")
    -trail   (100)        max size of trail history (for dynamic parsing)
    -doc     ()           generate only the grammar documentation
    -base    (.)          Jacc's %include command's file base
    -rrp     ()           resolve R/R conflicts based on precedence (dangerous!)

### Using the package

We illustrate the process on an example: that of a simple arithmetic calculator. This example defines an interactive java program that reads input from the terminal. The calculator repeatedly prompts the user, reads an input, and prints the parse tree followed by the evaluation result. Inputs are either arithmetic expressions using the four operations (`+`, `-`, `*`, and `/`), numbers, and identifiers. A definition is of form `id = ex` where `id` is an identifier, and `ex` is an expression. Expressions and definitions are terminated with a semicolon (`;`). To exit, one types the command `exit;`.

A `Jacc` grammar for such a calculator is specified in the file Calculator.grm. To generate the parser corresponding to this grammar, one simply runs `Jacc` as indicated above on the grammar file. In our case:

    % jacc Calculator
    *** Reading grammar in file Calculator.grm ...
    *** Starting grammar analysis ...
    *** Grammar analysis completed in 70 ms.
    *** Building parsing tables ...
    *** Writing parser file CalculatorParser.java
    *** Parser generation completed in 90 ms.
    *** Total processing time: 240 ms.

This generates a parser for the specified grammar as a java program called CalculatorParser.java.

In order to have a complete system, we need a tokenizer and a driver.

Our calculator grammar uses a tokenizer class called `CalculatorTokenizer`. A possible implementation for it is shown in the file CalculatorTokenizer.java.

A simple driver for the complete calculator is shown in the file CalculatorMain.java.

Then, all one must do is compile the three files (parser, tokenizer, and driver) using `javac`, and the calculator is ready by executing its driver. To wit:

    % java CalculatorMain
    *** Welcome to the number calculator!
    *** Version of Sun Dec 19 18:27:13 PST 2004
    > 1+2;
    expression
       'NUMBER'(1.0)
       '+'
       'NUMBER'(2.0)
    3.0
    > a+1;
    *** Undefined identifier: a
    expression
       'IDENTIFIER'(a)
       '+'
       'NUMBER'(1.0)
    > a = 3.14159;
    definition
       'IDENTIFIER'(a)
       '='
       'NUMBER'(3.14159)
    *** Defined a (3.14159)
    > b = 2*a+(a-1.234);
    definition
       'IDENTIFIER'(b)
       '='
       expression
          'NUMBER'(2.0)
          '*'
          'IDENTIFIER'(a)
          '+'
          '('
          'IDENTIFIER'(a)
          '-'
          'NUMBER'(1.234)
          ')'
    *** Defined b (8.19077)
    > a-b+2/b;
    expression
       'IDENTIFIER'(a)
       '-'
       'IDENTIFIER'(b)
       '+'
       'NUMBER'(2.0)
       '/'
       'IDENTIFIER'(b)
    -4.805002712638739
    > 1 ++ 2;
    *** Syntax Error: unexpected '+' - see stdin (line 6, column 4)
    > exit;
    *** Bye bye!...
    %

Another similar example illustrating `Jacc`'s handling of dynamic operators is Term.grm. All concomitant files for it along with those done for the `Calculator` example are also provided to let you run the example.

Author:
  Hassan Aït-Kaci
Copyright:
  © all rights reserved by the author
Version:
  Last modified on Wed Jan 30 20:13:42 2013 by hak