ayacc

AYACC(local)                                                        AYACC(local)



NAME
       ayacc - An Ada LALR(1) parser generator

SYNOPSIS
       ayacc {command line interface parameter associations}

DESCRIPTION
       Ayacc provides Ada programmers with a convenient tool for the automatic
       construction of parsers from a high level description of a context free
       grammar.  The input to Ayacc consists of a BNF-like specification of a
       grammar accompanied by a set of Ada program statements to be executed as
       each production is recognized.  Ayacc outputs a set of Ada program units
       that act as a parser for the specified grammar; these program units may
       be interfaced to additional user-supplied routines to produce a
       functional program.

       Ayacc will produce a procedure called yyparse and three packages: Tokens,
       Goto_Table, and Shift_Reduce_Table.  All of these packages must be
       visible to yyparse.  Package Tokens contains the enumeration type that is
       returned by the lexical analyzer.  Packages Goto_table and
       Shift_Reduce_Table contain the parsing tables used by yyparse.

       The user must supply yyparse with a lexical analyzer and an error
       reporting routine.  The declarations of these routines should look like
       the following:

              function YYLEX return TOKENS.TOKEN;

              procedure YYERROR(MESSAGE: in STRING);


       The format of the ayacc input file must be as follows,

                    declarations section
                    %%
                    rules section
                    %%
                    user declarations section


       The declarations section is used to specify the generated tokens package.
       A token declaration consists of the keyword %token followed by a list of
       token names that may optionally be separated by commas.  Token names must
       follow Ada enumeration type naming conventions.  Ayacc provides a means
       to associate an Ada data type with a grammar symbol.  This type must be
       called YYSType and must be declared in the tokens declarations section
       and be surrounded by '{' '}'s . e.g.

                 {
                   subtype YYSType is Integer;
                 }

       Since types declared in this section may require visibility to additional
       packages, context clauses for the tokens package may be defined by using
       the keywords %with and %use.  These keywords must be located before the
       YYStype declaration.


       The rules section defines the grammar to be parsed.  Each rules consists
       of a nonterminal symbol followed by a colon and a list of grammar symbols
       terminated by a semicolon.  For example, a rule corresponding to a street
       address might be written as,

                    Address: Street City ',' State Zip;

       A vertical bar may be used to combine rules with identical left hand
       sides.  Nonterminal names may be made up of alphanumeric characters as
       well as periods and underscores.  Ada reserved words are allowed.
       Unlike, yacc all tokens and nonterminal names are case insensitive.  The
       start symbol of the grammar may be specified using the keyword %start
       followed by the symbol.  If the start symbol is not specified, ayacc will
       use the left hand side of the first grammar rule.


       Ayacc allows each grammar rule to have associated actions which are
       executed whenever the rule is recognized by the parser.  An action
       consists of Ada statements enclosed in braces and placed after the body
       of a rule.  Ayacc uses a pseudo-variable notation to denote the values
       associate values with nonterminal and token symbols.  The left hand side
       of a rule may be set to a value by an assignment to the variable, $$.
       For example, if YYSType is an integer, the action:

                    A : B C D {$$ := 1;}

       sets the value of A to 1.  Values of symbols on the right hand side of
       the rule, may be accessed through the variables $1..$n ,where n refers to
       the nth element of the right hand side.  For example.

                   A : B '+' C {$$ := $1 + $3;}

       sets A to the sum of the values of B and C.


       The user declarations section is optional. By default, ayacc generates a
       parameterless procedure, YYParse.  If the user desires, the procedure may
       be incorporated within a package provided in this section.  The user must
       use the key marker, ##, to indicate where the body of YYParse is to be
       inserted.  The user is responsible for providing with clauses for the
       tokens, parse table, and Text_IO packages.




COMMAND LINE INTERFACE
       Arguments are passed to ayacc via a command line interface.  This command
       line interface models the syntax and semantics of Ada procedure calls,
       supporting both named and positional notation as well as default
       initialization.

       When the ayacc command is entered without arguments, the following
       specification is displayed.


       -- Ayacc: An Ada Parser Generator.

       type Switch is (On, Off);

       procedure Ayacc (File      : in String;
                        C_Lex     : in Switch := Off;
                        Debug     : in Switch := Off;
                        Summary   : in Switch := On;
                        Verbose   : in Switch := Off;
                        Extension : in String := ".a");

       -- File          Specifies the Ayacc Input Source File.
       -- C_Lex         Specifies the Generation of a 'C' Lex
       --               Interface.
       -- Debug         Specifies the Production of Debugging Output
       --               By the Generated Parser.
       -- Summary       Specifies the Printing of Statistics About the
       --               Generated Parser.
       -- Verbose       Specifies the Production of a Human Readable
       --               Report of States in the Generated Parser.
       -- Extension     Specifies the File Extension to be Used for
       --               Generated Ada Files.


       The following examples are legal invocations of ayacc

             ayacc ("file.y");
             ayacc ("file.y, Verbose => On, Extension => ".ada");

       For friendlier usage, some Ada rules have been relaxed,

            1) Final semicolon on the procedure call is optional.
            2) Outermost parentheses are optional.
            3) Parentheses around aggregate parameters are optional
               when the aggregate consists of only one component.
            4) Quotes around string literals are optional.

       making the following examples legal invocations as well.

             ayacc file.y
             ayacc file.y Verbose => On Extenstion => .ada

       Note: Unix will interpret the => and parantheses prior to passing
       arguments to alex.  As a result, they must be escaped on the command line
       to prevent interpretation.  i.e. => must be typed in as =\>.


FILES
       file.y                   the input file to Ayacc
       file.ada                 the generated parser
       file.goto.ada            package Goto_Table
       file.shift_reduce.ada    package Shift_Reduce_Table
       file.tokens.ada          package Tokens
       file.verbose             the verbose output
       file.c_lex.ada           package c_lexforinterfacingwithlex
       file.h                   the C include file for interfacing with lex

BUGS
       send questions and comment to ayacc-info@ics.uci.edu
       send bug reports to ayacc-bugs@ics.uci.edu

SEE ALSO
       Ayacc User's Manual
       yacc(1), lex(1), alex(local)



                                   3 June 1988                      AYACC(local)