YACC(1)                    POSIX Programmer's Manual                   YACC(1)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.


NNAAMMEE
       yacc -- yet another compiler compiler (DDEEVVEELLOOPPMMEENNTT)

SSYYNNOOPPSSIISS
       yacc [[-dltv]] [[-b _f_i_l_e___p_r_e_f_i_x]] [[-p _s_y_m___p_r_e_f_i_x]] _g_r_a_m_m_a_r

DDEESSCCRRIIPPTTIIOONN
       The _y_a_c_c utility shall read a description of a context-free grammar in
       _g_r_a_m_m_a_r and write C source code, conforming to the ISO C standard, to a
       code file, and optionally header information into a header file, in the
       current directory. The generated source code shall not depend on any
       undefined, unspecified, or implementation-defined behavior, except in
       cases where it is copied directly from the supplied grammar, or in
       cases that are documented by the implementation. The C code shall
       define a function and related routines and macros for an automaton that
       executes a parsing algorithm meeting the requirements in _A_l_g_o_r_i_t_h_m_s.

       The form and meaning of the grammar are described in the EXTENDED
       DESCRIPTION section.

       The C source code and header file shall be produced in a form suitable
       as input for the C compiler (see _c_9_9).

OOPPTTIIOONNSS
       The _y_a_c_c utility shall conform to the Base Definitions volume of
       POSIX.1-2008, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s, except for
       Guideline 9.

       The following options shall be supported:

       --bb _f_i_l_e___p_r_e_f_i_x
                 Use _f_i_l_e___p_r_e_f_i_x instead of yy as the prefix for all output
                 filenames. The code file yy..ttaabb..cc, the header file yy..ttaabb..hh
                 (created when --dd is specified), and the description file
                 yy..oouuttppuutt (created when --vv is specified), shall be changed to
                 _f_i_l_e___p_r_e_f_i_x..ttaabb..cc, _f_i_l_e___p_r_e_f_i_x..ttaabb..hh, and _f_i_l_e___p_r_e_f_i_x..oouuttppuutt,
                 respectively.

       --dd        Write the header file; by default only the code file is
                 written. The ##ddeeffiinnee statements associate the token codes
                 assigned by _y_a_c_c with the user-declared token names. This
                 allows source files other than yy..ttaabb..cc to access the token
                 codes.

       --ll        Produce a code file that does not contain any ##lliinnee
                 constructs. If this option is not present, it is unspecified
                 whether the code file or header file contains ##lliinnee
                 directives. This should only be used after the grammar and
                 the associated actions are fully debugged.

       --pp _s_y_m___p_r_e_f_i_x
                 Use _s_y_m___p_r_e_f_i_x instead of yyyy as the prefix for all external
                 names produced by _y_a_c_c.  The names affected shall include the
                 functions _y_y_p_a_r_s_e(), _y_y_l_e_x(), and _y_y_e_r_r_o_r(), and the
                 variables _y_y_l_v_a_l, _y_y_c_h_a_r, and _y_y_d_e_b_u_g.  (In the remainder of
                 this section, the six symbols cited are referenced using
                 their default names only as a notational convenience.) Local
                 names may also be affected by the --pp option; however, the --pp
                 option shall not affect ##ddeeffiinnee symbols generated by _y_a_c_c.

       --tt        Modify conditional compilation directives to permit
                 compilation of debugging code in the code file. Runtime
                 debugging statements shall always be contained in the code
                 file, but by default conditional compilation directives
                 prevent their compilation.

       --vv        Write a file containing a description of the parser and a
                 report of conflicts generated by ambiguities in the grammar.

OOPPEERRAANNDDSS
       The following operand is required:

       _g_r_a_m_m_a_r   A pathname of a file containing instructions, hereafter
                 called _g_r_a_m_m_a_r, for which a parser is to be created. The
                 format for the grammar is described in the EXTENDED
                 DESCRIPTION section.

SSTTDDIINN
       Not used.

IINNPPUUTT FFIILLEESS
       The file _g_r_a_m_m_a_r shall be a text file formatted as specified in the
       EXTENDED DESCRIPTION section.

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
       The following environment variables shall affect the execution of _y_a_c_c:

       _L_A_N_G      Provide a default value for the internationalization
                 variables that are unset or null. (See the Base Definitions
                 volume of POSIX.1-2008, _S_e_c_t_i_o_n _8_._2, _I_n_t_e_r_n_a_t_i_o_n_a_l_i_z_a_t_i_o_n
                 _V_a_r_i_a_b_l_e_s for the precedence of internationalization
                 variables used to determine the values of locale categories.)

       _L_C___A_L_L    If set to a non-empty string value, override the values of
                 all the other internationalization variables.

       _L_C___C_T_Y_P_E  Determine the locale for the interpretation of sequences of
                 bytes of text data as characters (for example, single-byte as
                 opposed to multi-byte characters in arguments and input
                 files).

       _L_C___M_E_S_S_A_G_E_S
                 Determine the locale that should be used to affect the format
                 and contents of diagnostic messages written to standard
                 error.

       _N_L_S_P_A_T_H   Determine the location of message catalogs for the processing
                 of _L_C___M_E_S_S_A_G_E_S.

       The _L_A_N_G and _L_C___* variables affect the execution of the _y_a_c_c utility as
       stated. The _m_a_i_n() function defined in _Y_a_c_c _L_i_b_r_a_r_y shall call:

           sseettllooccaallee((LLCC__AALLLL,, """"))

       and thus the program generated by _y_a_c_c shall also be affected by the
       contents of these variables at runtime.

AASSYYNNCCHHRROONNOOUUSS EEVVEENNTTSS
       Default.

SSTTDDOOUUTT
       Not used.

SSTTDDEERRRR
       If shift/reduce or reduce/reduce conflicts are detected in _g_r_a_m_m_a_r,
       _y_a_c_c shall write a report of those conflicts to the standard error in
       an unspecified format.

       Standard error shall also be used for diagnostic messages.

OOUUTTPPUUTT FFIILLEESS
       The code file, the header file, and the description file shall be text
       files. All are described in the following sections.

   CCooddee FFiillee
       This file shall contain the C source code for the _y_y_p_a_r_s_e() function.
       It shall contain code for the various semantic actions with macro
       substitution performed on them as described in the EXTENDED DESCRIPTION
       section. It also shall contain a copy of the ##ddeeffiinnee statements in the
       header file. If a %%uunniioonn declaration is used, the declaration for
       YYSTYPE shall also be included in this file.

   HHeeaaddeerr FFiillee
       The header file shall contain ##ddeeffiinnee statements that associate the
       token numbers with the token names. This allows source files other than
       the code file to access the token codes. If a %%uunniioonn declaration is
       used, the declaration for YYSTYPE and an _e_x_t_e_r_n _Y_Y_S_T_Y_P_E _y_y_l_v_a_l
       declaration shall also be included in this file.

   DDeessccrriippttiioonn FFiillee
       The description file shall be a text file containing a description of
       the state machine corresponding to the parser, using an unspecified
       format. Limits for internal tables (see _L_i_m_i_t_s) shall also be reported,
       in an implementation-defined manner. (Some implementations may use
       dynamic allocation techniques and have no specific limit values to
       report.)

EEXXTTEENNDDEEDD DDEESSCCRRIIPPTTIIOONN
       The _y_a_c_c command accepts a language that is used to define a grammar
       for a target language to be parsed by the tables and code generated by
       _y_a_c_c.  The language accepted by _y_a_c_c as a grammar for the target
       language is described below using the _y_a_c_c input language itself.

       The input _g_r_a_m_m_a_r includes rules describing the input structure of the
       target language and code to be invoked when these rules are recognized
       to provide the associated semantic action. The code to be executed
       shall appear as bodies of text that are intended to be C-language code.
       These bodies of text shall not contain C-language trigraphs. The C-
       language inclusions are presumed to form a correct function when
       processed by _y_a_c_c into its output files. The code included in this way
       shall be executed during the recognition of the target language.

       Given a grammar, the _y_a_c_c utility generates the files described in the
       OUTPUT FILES section. The code file can be compiled and linked using
       _c_9_9.  If the declaration and programs sections of the grammar file did
       not include definitions of _m_a_i_n(), _y_y_l_e_x(), and _y_y_e_r_r_o_r(), the compiled
       output requires linking with externally supplied versions of those
       functions. Default versions of _m_a_i_n() and _y_y_e_r_r_o_r() are supplied in the
       _y_a_c_c library and can be linked in by using the --ll yy operand to _c_9_9.
       The _y_a_c_c library interfaces need not support interfaces with other than
       the default yyyy symbol prefix. The application provides the lexical
       analyzer function, _y_y_l_e_x(); the _l_e_x utility is specifically designed to
       generate such a routine.

   IInnppuutt LLaanngguuaaggee
       The application shall ensure that every specification file consists of
       three sections in order: _d_e_c_l_a_r_a_t_i_o_n_s, _g_r_a_m_m_a_r _r_u_l_e_s, and _p_r_o_g_r_a_m_s,
       separated by double <percent-sign> characters (""%%%%"").  The declarations
       and programs sections can be empty. If the latter is empty, the
       preceding ""%%%%"" mark separating it from the rules section can be
       omitted.

       The input is free form text following the structure of the grammar
       defined below.

   LLeexxiiccaall SSttrruuccttuurree ooff tthhee GGrraammmmaarr
       The <blank>, <newline>, and <form-feed> character shall be ignored,
       except that the application shall ensure that they do not appear in
       names or multi-character reserved symbols. Comments shall be enclosed
       in ""//** ...... **//"", and can appear wherever a name is valid.

       Names are of arbitrary length, made up of letters, periods (''..''),
       underscores (''__''), and non-initial digits. Uppercase and lowercase
       letters are distinct.  Conforming applications shall not use names
       beginning in yyyy or YYYY since the _y_a_c_c parser uses such names. Many of
       the names appear in the final output of _y_a_c_c, and thus they should be
       chosen to conform with any additional rules created by the C compiler
       to be used. In particular they appear in ##ddeeffiinnee statements.

       A literal shall consist of a single character enclosed in single-quote
       characters. All of the escape sequences supported for character
       constants by the ISO C standard shall be supported by _y_a_c_c.

       The relationship with the lexical analyzer is discussed in detail
       below.

       The application shall ensure that the NUL character is not used in
       grammar rules or literals.

   DDeeccllaarraattiioonnss SSeeccttiioonn
       The declarations section is used to define the symbols used to define
       the target language and their relationship with each other. In
       particular, much of the additional information required to resolve
       ambiguities in the context-free grammar for the target language is
       provided here.

       Usually _y_a_c_c assigns the relationship between the symbolic names it
       generates and their underlying numeric value. The declarations section
       makes it possible to control the assignment of these values.

       It is also possible to keep semantic information associated with the
       tokens currently on the parse stack in a user-defined C-language uunniioonn,
       if the members of the union are associated with the various names in
       the grammar. The declarations section provides for this as well.

       The first group of declarators below all take a list of names as
       arguments. That list can optionally be preceded by the name of a C
       union member (called a _t_a_g below) appearing within ''<<'' and ''>>''.  (As an
       exception to the typographical conventions of the rest of this volume
       of POSIX.1-2008, in this case <_t_a_g> does not represent a metavariable,
       but the literal angle bracket characters surrounding a symbol.) The use
       of _t_a_g specifies that the tokens named on this line shall be of the
       same C type as the union member referenced by _t_a_g.  This is discussed
       in more detail below.

       For lists used to define tokens, the first appearance of a given token
       can be followed by a positive integer (as a string of decimal digits).
       If this is done, the underlying value assigned to it for lexical
       purposes shall be taken to be that number.

       The following declares _n_a_m_e to be a token:

           %%ttookkeenn [[<_t_a_g>]] _n_a_m_e [[_n_u_m_b_e_r]] [[_n_a_m_e [[_n_u_m_b_e_r]]]]...

       If _t_a_g is present, the C type for all tokens on this line shall be
       declared to be the type referenced by _t_a_g.  If a positive integer,
       _n_u_m_b_e_r, follows a _n_a_m_e, that value shall be assigned to the token.

       The following declares _n_a_m_e to be a token, and assigns precedence to
       it:

           %%lleefftt [[<_t_a_g>]] _n_a_m_e [[_n_u_m_b_e_r]] [[_n_a_m_e [[_n_u_m_b_e_r]]]]...
           %right [[<_t_a_g>]] _n_a_m_e [[_n_u_m_b_e_r]] [[_n_a_m_e [[_n_u_m_b_e_r]]]]...

       One or more lines, each beginning with one of these symbols, can appear
       in this section. All tokens on the same line have the same precedence
       level and associativity; the lines are in order of increasing
       precedence or binding strength.  %%lleefftt denotes that the operators on
       that line are left associative, and %%rriigghhtt similarly denotes right
       associative operators. If _t_a_g is present, it shall declare a C type for
       _n_a_m_es as described for %%ttookkeenn.

       The following declares _n_a_m_e to be a token, and indicates that this
       cannot be used associatively:

           %%nnoonnaassssoocc [[<_t_a_g>]] _n_a_m_e [[_n_u_m_b_e_r]] [[_n_a_m_e [[_n_u_m_b_e_r]]]]...

       If the parser encounters associative use of this token it reports an
       error. If _t_a_g is present, it shall declare a C type for _n_a_m_es as
       described for %%ttookkeenn.

       The following declares that union member _n_a_m_es are non-terminals, and
       thus it is required to have a _t_a_g field at its beginning:

           %%ttyyppee <<_t_a_g> _n_a_m_e...

       Because it deals with non-terminals only, assigning a token number or
       using a literal is also prohibited. If this construct is present, _y_a_c_c
       shall perform type checking; if this construct is not present, the
       parse stack shall hold only the iinntt type.

       Every name used in _g_r_a_m_m_a_r not defined by a %%ttookkeenn, %%lleefftt, %%rriigghhtt, or
       %%nnoonnaassssoocc declaration is assumed to represent a non-terminal symbol.
       The _y_a_c_c utility shall report an error for any non-terminal symbol that
       does not appear on the left side of at least one grammar rule.

       Once the type, precedence, or token number of a name is specified, it
       shall not be changed. If the first declaration of a token does not
       assign a token number, _y_a_c_c shall assign a token number. Once this
       assignment is made, the token number shall not be changed by explicit
       assignment.

       The following declarators do not follow the previous pattern.

       The following declares the non-terminal _n_a_m_e to be the _s_t_a_r_t _s_y_m_b_o_l,
       which represents the largest, most general structure described by the
       grammar rules:

           %%ssttaarrtt _n_a_m_e

       By default, it is the left-hand side of the first grammar rule; this
       default can be overridden with this declaration.

       The following declares the _y_a_c_c value stack to be a union of the
       various types of values desired.

           %%uunniioonn {{ _b_o_d_y _o_f _u_n_i_o_n (_i_n _C) }

       The body of the union shall not contain unbalanced curly brace
       preprocessing tokens.

       By default, the values returned by actions (see below) and the lexical
       analyzer shall be of type iinntt.  The _y_a_c_c utility keeps track of types,
       and it shall insert corresponding union member names in order to
       perform strict type checking of the resulting parser.

       Alternatively, given that at least one <_t_a_g> construct is used, the
       union can be declared in a header file (which shall be included in the
       declarations section by using a ##iinncclluuddee construct within %%{{ and %%}}),
       and a ttyyppeeddeeff used to define the symbol YYSTYPE to represent this
       union. The effect of %%uunniioonn is to provide the declaration of YYSTYPE
       directly from the _y_a_c_c input.

       C-language declarations and definitions can appear in the declarations
       section, enclosed by the following marks:

           %%{{ ...... %%}}

       These statements shall be copied into the code file, and have global
       scope within it so that they can be used in the rules and program
       sections. The statements shall not contain ""%%}}"" outside a comment,
       string literal, or multi-character constant.

       The application shall ensure that the declarations section is
       terminated by the token %%%%.

   GGrraammmmaarr RRuulleess iinn yyaacccc
       The rules section defines the context-free grammar to be accepted by
       the function _y_a_c_c generates, and associates with those rules C-language
       actions and additional precedence information. The grammar is described
       below, and a formal definition follows.

       The rules section is comprised of one or more grammar rules. A grammar
       rule has the form:

           AA :: BBOODDYY ;;

       The symbol AA represents a non-terminal name, and BBOODDYY represents a
       sequence of zero or more _n_a_m_es, _l_i_t_e_r_a_ls, and _s_e_m_a_n_t_i_c _a_c_t_i_o_ns that can
       then be followed by optional _p_r_e_c_e_d_e_n_c_e _r_u_l_es.  Only the names and
       literals participate in the formation of the grammar; the semantic
       actions and precedence rules are used in other ways. The <colon> and
       the <semicolon> are _y_a_c_c punctuation. If there are several successive
       grammar rules with the same left-hand side, the <vertical-line> (''||'')
       can be used to avoid rewriting the left-hand side; in this case the
       <semicolon> appears only after the last rule. The BODY part can be
       empty (or empty of names and literals) to indicate that the non-
       terminal symbol matches the empty string.

       The _y_a_c_c utility assigns a unique number to each rule. Rules using the
       vertical bar notation are distinct rules. The number assigned to the
       rule appears in the description file.

       The elements comprising a BODY are:

       _n_a_m_e, _l_i_t_e_r_a_l
                 These form the rules of the grammar: _n_a_m_e is either a _t_o_k_e_n
                 or a _n_o_n_-_t_e_r_m_i_n_a_l; _l_i_t_e_r_a_l stands for itself (less the
                 lexically required quotation marks).

       _s_e_m_a_n_t_i_c _a_c_t_i_o_n
                 With each grammar rule, the user can associate actions to be
                 performed each time the rule is recognized in the input
                 process. (Note that the word ``action'' can also refer to the
                 actions of the parser--shift, reduce, and so on.)

                 These actions can return values and can obtain the values
                 returned by previous actions. These values are kept in
                 objects of type YYSTYPE (see %%uunniioonn).  The result value of
                 the action shall be kept on the parse stack with the left-
                 hand side of the rule, to be accessed by other reductions as
                 part of their right-hand side. By using the <_t_a_g> information
                 provided in the declarations section, the code generated by
                 _y_a_c_c can be strictly type checked and contain arbitrary
                 information. In addition, the lexical analyzer can provide
                 the same kinds of values for tokens, if desired.

                 An action is an arbitrary C statement and as such can do
                 input or output, call subprograms, and alter external
                 variables. An action is one or more C statements enclosed in
                 curly braces ''{{'' and ''}}''.  The statements shall not contain
                 unbalanced curly brace preprocessing tokens.

                 Certain pseudo-variables can be used in the action. These are
                 macros for access to data structures known internally to
                 _y_a_c_c.

                 $$        The value of the action can be set by assigning it
                           to $$. If type checking is enabled and the type of
                           the value to be assigned cannot be determined, a
                           diagnostic message may be generated.

                 $_n_u_m_b_e_r   This refers to the value returned by the component
                           specified by the token _n_u_m_b_e_r in the right side of
                           a rule, reading from left to right; _n_u_m_b_e_r can be
                           zero or negative. If _n_u_m_b_e_r is zero or negative, it
                           refers to the data associated with the name on the
                           parser's stack preceding the leftmost symbol of the
                           current rule.  (That is, ""$$00"" refers to the name
                           immediately preceding the leftmost name in the
                           current rule to be found on the parser's stack and
                           ""$$--11"" refers to the symbol to _i_t_s left.) If _n_u_m_b_e_r
                           refers to an element past the current point in the
                           rule, or beyond the bottom of the stack, the result
                           is undefined. If type checking is enabled and the
                           type of the value to be assigned cannot be
                           determined, a diagnostic message may be generated.

                 $<_t_a_g>_n_u_m_b_e_r
                           These correspond exactly to the corresponding
                           symbols without the _t_a_g inclusion, but allow for
                           strict type checking (and preclude unwanted type
                           conversions). The effect is that the macro is
                           expanded to use _t_a_g to select an element from the
                           YYSTYPE union (using _d_a_t_a_n_a_m_e_._t_a_g).  This is
                           particularly useful if _n_u_m_b_e_r is not positive.

                 $<_t_a_g>$   This imposes on the reference the type of the union
                           member referenced by _t_a_g.  This construction is
                           applicable when a reference to a left context value
                           occurs in the grammar, and provides _y_a_c_c with a
                           means for selecting a type.

                 Actions can occur anywhere in a rule (not just at the end);
                 an action can access values returned by actions to its left,
                 and in turn the value it returns can be accessed by actions
                 to its right. An action appearing in the middle of a rule
                 shall be equivalent to replacing the action with a new non-
                 terminal symbol and adding an empty rule with that non-
                 terminal symbol on the left-hand side. The semantic action
                 associated with the new rule shall be equivalent to the
                 original action. The use of actions within rules might
                 introduce conflicts that would not otherwise exist.

                 By default, the value of a rule shall be the value of the
                 first element in it. If the first element does not have a
                 type (particularly in the case of a literal) and type
                 checking is turned on by %%ttyyppee, an error message shall
                 result.

       _p_r_e_c_e_d_e_n_c_e
                 The keyword %%pprreecc can be used to change the precedence level
                 associated with a particular grammar rule. Examples of this
                 are in cases where a unary and binary operator have the same
                 symbolic representation, but need to be given different
                 precedences, or where the handling of an ambiguous if-else
                 construction is necessary. The reserved symbol %%pprreecc can
                 appear immediately after the body of the grammar rule and can
                 be followed by a token name or a literal. It shall cause the
                 precedence of the grammar rule to become that of the
                 following token name or literal. The action for the rule as a
                 whole can follow %%pprreecc.

       If a program section follows, the application shall ensure that the
       grammar rules are terminated by %%%%.

   PPrrooggrraammss SSeeccttiioonn
       The _p_r_o_g_r_a_m_s section can include the definition of the lexical analyzer
       _y_y_l_e_x(), and any other functions; for example, those used in the
       actions specified in the grammar rules. It is unspecified whether the
       programs section precedes or follows the semantic actions in the output
       file; therefore, if the application contains any macro definitions and
       declarations intended to apply to the code in the semantic actions, it
       shall place them within ""%%{{ ...... %%}}"" in the declarations section.

   IInnppuutt GGrraammmmaarr
       The following input to _y_a_c_c yields a parser for the input to _y_a_c_c.
       This formal syntax takes precedence over the preceding text syntax
       description.

       The lexical structure is defined less precisely; _L_e_x_i_c_a_l _S_t_r_u_c_t_u_r_e _o_f
       _t_h_e _G_r_a_m_m_a_r defines most terms. The correspondence between the previous
       terms and the tokens below is as follows.

       IIDDEENNTTIIFFIIEERR  This corresponds to the concept of _n_a_m_e, given previously.
                   It also includes literals as defined previously.

       CC__IIDDEENNTTIIFFIIEERR
                   This is a name, and additionally it is known to be followed
                   by a <colon>.  A literal cannot yield this token.

       NNUUMMBBEERR      A string of digits (a non-negative decimal integer).

       TTYYPPEE, LLEEFFTT, MMAARRKK, LLCCUURRLL, RRCCUURRLL
                   These correspond directly to %%ttyyppee, %%lleefftt, %%%%, %%{{, and %%}}.

       {{ ...... }}     This indicates C-language source code, with the possible
                   inclusion of ''$$'' macros as discussed previously.

           //** GGrraammmmaarr ffoorr tthhee iinnppuutt ttoo yyaacccc.. **//
           //** BBaassiicc eennttrriieess.. **//
           //** TThhee ffoolllloowwiinngg aarree rreeccooggnniizzeedd bbyy tthhee lleexxiiccaall aannaallyyzzeerr.. **//

           %token    IDENTIFIER      /* Includes identifiers and literals */
           %token    C_IDENTIFIER    /* identifier (but not literal)
                                        followed by a :. */
           %token    NUMBER          /* [0-9][0-9]* */

           /* Reserved words : %type=>TYPE %left=>LEFT, and so on */

           %token    LEFT RIGHT NONASSOC TOKEN PREC TYPE START UNION

           %token    MARK            /* The %% mark. */
           %token    LCURL           /* The %{ mark. */
           %token    RCURL           /* The %} mark. */

           /* 8-bit character literals stand for themselves; */
           /* tokens have to be defined for multi-byte characters. */

           %start    spec

           %%

           spec  : defs MARK rules tail
                 ;
           tail  : MARK
                 {
                   /* In this action, set up the rest of the file. */
                 }
                 | /* Empty; the second MARK is optional. */
                 ;
           defs  : /* Empty. */
                 |    defs def
                 ;
           def   : START IDENTIFIER
                 |    UNION
                 {
                   /* Copy union definition to output. */
                 }
                 |    LCURL
                 {
                   /* Copy C code to output file. */
                 }
                   RCURL
                 |    rword tag nlist
                 ;
           rword : TOKEN
                 | LEFT
                 | RIGHT
                 | NONASSOC
                 | TYPE
                 ;
           tag   : /* Empty: union tag ID optional. */
                 | '<' IDENTIFIER '>'
                 ;
           nlist : nmno
                 | nlist nmno
                 ;
           nmno  : IDENTIFIER         /* Note: literal invalid with % type. */
                 | IDENTIFIER NUMBER  /* Note: invalid with % type. */
                 ;

           /* Rule section */

           rules : C_IDENTIFIER rbody prec
                 | rules  rule
                 ;
           rule  : C_IDENTIFIER rbody prec
                 | '|' rbody prec
                 ;
           rbody : /* empty */
                 | rbody IDENTIFIER
                 | rbody act
                 ;
           act   : '{'
                   {
                     /* Copy action, translate $$, and so on. */
                   }
                   '}'
                 ;
           prec  : /* Empty */
                 | PREC IDENTIFIER
                 | PREC IDENTIFIER act
                 | prec ';'
                 ;

   CCoonnfflliiccttss
       The parser produced for an input grammar may contain states in which
       conflicts occur. The conflicts occur because the grammar is not
       LALR(1). An ambiguous grammar always contains at least one LALR(1)
       conflict. The _y_a_c_c utility shall resolve all conflicts, using either
       default rules or user-specified precedence rules.

       Conflicts are either shift/reduce conflicts or reduce/reduce conflicts.
       A shift/reduce conflict is where, for a given state and lookahead
       symbol, both a shift action and a reduce action are possible. A
       reduce/reduce conflict is where, for a given state and lookahead
       symbol, reductions by two different rules are possible.

       The rules below describe how to specify what actions to take when a
       conflict occurs. Not all shift/reduce conflicts can be successfully
       resolved this way because the conflict may be due to something other
       than ambiguity, so incautious use of these facilities can cause the
       language accepted by the parser to be much different from that which
       was intended. The description file shall contain sufficient information
       to understand the cause of the conflict. Where ambiguity is the reason
       either the default or explicit rules should be adequate to produce a
       working parser.

       The declared precedences and associativities (see _D_e_c_l_a_r_a_t_i_o_n_s _S_e_c_t_i_o_n)
       are used to resolve parsing conflicts as follows:

        1. A precedence and associativity is associated with each grammar
           rule; it is the precedence and associativity of the last token or
           literal in the body of the rule. If the %%pprreecc keyword is used, it
           overrides this default. Some grammar rules might not have both
           precedence and associativity.

        2. If there is a shift/reduce conflict, and both the grammar rule and
           the input symbol have precedence and associativity associated with
           them, then the conflict is resolved in favor of the action (shift
           or reduce) associated with the higher precedence. If the
           precedences are the same, then the associativity is used; left
           associative implies reduce, right associative implies shift, and
           non-associative implies an error in the string being parsed.

        3. When there is a shift/reduce conflict that cannot be resolved by
           rule 2, the shift is done. Conflicts resolved this way are counted
           in the diagnostic output described in _E_r_r_o_r _H_a_n_d_l_i_n_g.

        4. When there is a reduce/reduce conflict, a reduction is done by the
           grammar rule that occurs earlier in the input sequence. Conflicts
           resolved this way are counted in the diagnostic output described in
           _E_r_r_o_r _H_a_n_d_l_i_n_g.

       Conflicts resolved by precedence or associativity shall not be counted
       in the shift/reduce and reduce/reduce conflicts reported by _y_a_c_c on
       either standard error or in the description file.

   EErrrroorr HHaannddlliinngg
       The token eerrrroorr shall be reserved for error handling. The name eerrrroorr
       can be used in grammar rules. It indicates places where the parser can
       recover from a syntax error. The default value of eerrrroorr shall be 256.
       Its value can be changed using a %%ttookkeenn declaration. The lexical
       analyzer should not return the value of eerrrroorr.

       The parser shall detect a syntax error when it is in a state where the
       action associated with the lookahead symbol is eerrrroorr.  A semantic
       action can cause the parser to initiate error handling by executing the
       macro YYERROR. When YYERROR is executed, the semantic action passes
       control back to the parser. YYERROR cannot be used outside of semantic
       actions.

       When the parser detects a syntax error, it normally calls _y_y_e_r_r_o_r()
       with the character string ""ssyynnttaaxx eerrrroorr"" as its argument. The call
       shall not be made if the parser is still recovering from a previous
       error when the error is detected. The parser is considered to be
       recovering from a previous error until the parser has shifted over at
       least three normal input symbols since the last error was detected or a
       semantic action has executed the macro _y_y_e_r_r_o_k.  The parser shall not
       call _y_y_e_r_r_o_r() when YYERROR is executed.

       The macro function YYRECOVERING shall return 1 if a syntax error has
       been detected and the parser has not yet fully recovered from it.
       Otherwise, zero shall be returned.

       When a syntax error is detected by the parser, the parser shall check
       if a previous syntax error has been detected. If a previous error was
       detected, and if no normal input symbols have been shifted since the
       preceding error was detected, the parser checks if the lookahead symbol
       is an endmarker (see _I_n_t_e_r_f_a_c_e _t_o _t_h_e _L_e_x_i_c_a_l _A_n_a_l_y_z_e_r).  If it is, the
       parser shall return with a non-zero value. Otherwise, the lookahead
       symbol shall be discarded and normal parsing shall resume.

       When YYERROR is executed or when the parser detects a syntax error and
       no previous error has been detected, or at least one normal input
       symbol has been shifted since the previous error was detected, the
       parser shall pop back one state at a time until the parse stack is
       empty or the current state allows a shift over eerrrroorr.  If the parser
       empties the parse stack, it shall return with a non-zero value.
       Otherwise, it shall shift over eerrrroorr and then resume normal parsing. If
       the parser reads a lookahead symbol before the error was detected, that
       symbol shall still be the lookahead symbol when parsing is resumed.

       The macro _y_y_e_r_r_o_k in a semantic action shall cause the parser to act as
       if it has fully recovered from any previous errors. The macro _y_y_c_l_e_a_r_i_n
       shall cause the parser to discard the current lookahead token. If the
       current lookahead token has not yet been read, _y_y_c_l_e_a_r_i_n shall have no
       effect.

       The macro YYACCEPT shall cause the parser to return with the value
       zero. The macro YYABORT shall cause the parser to return with a non-
       zero value.

   IInntteerrffaaccee ttoo tthhee LLeexxiiccaall AAnnaallyyzzeerr
       The _y_y_l_e_x() function is an integer-valued function that returns a _t_o_k_e_n
       _n_u_m_b_e_r representing the kind of token read. If there is a value
       associated with the token returned by _y_y_l_e_x() (see the discussion of
       _t_a_g above), it shall be assigned to the external variable _y_y_l_v_a_l.

       If the parser and _y_y_l_e_x() do not agree on these token numbers, reliable
       communication between them cannot occur. For (single-byte character)
       literals, the token is simply the numeric value of the character in the
       current character set.  The numbers for other tokens can either be
       chosen by _y_a_c_c, or chosen by the user. In either case, the ##ddeeffiinnee
       construct of C is used to allow _y_y_l_e_x() to return these numbers
       symbolically. The ##ddeeffiinnee statements are put into the code file, and
       the header file if that file is requested. The set of characters
       permitted by _y_a_c_c in an identifier is larger than that permitted by C.
       Token names found to contain such characters shall not be included in
       the ##ddeeffiinnee declarations.

       If the token numbers are chosen by _y_a_c_c, the tokens other than literals
       shall be assigned numbers greater than 256, although no order is
       implied. A token can be explicitly assigned a number by following its
       first appearance in the declarations section with a number. Names and
       literals not defined this way retain their default definition. All
       token numbers assigned by _y_a_c_c shall be unique and distinct from the
       token numbers used for literals and user-assigned tokens. If duplicate
       token numbers cause conflicts in parser generation, _y_a_c_c shall report
       an error; otherwise, it is unspecified whether the token assignment is
       accepted or an error is reported.

       The end of the input is marked by a special token called the _e_n_d_m_a_r_k_e_r,
       which has a token number that is zero or negative. (These values are
       invalid for any other token.) All lexical analyzers shall return zero
       or negative as a token number upon reaching the end of their input. If
       the tokens up to, but excluding, the endmarker form a structure that
       matches the start symbol, the parser shall accept the input. If the
       endmarker is seen in any other context, it shall be considered an
       error.

   CCoommpplleettiinngg tthhee PPrrooggrraamm
       In addition to _y_y_p_a_r_s_e() and _y_y_l_e_x(), the functions _y_y_e_r_r_o_r() and
       _m_a_i_n() are required to make a complete program. The application can
       supply _m_a_i_n() and _y_y_e_r_r_o_r(), or those routines can be obtained from the
       _y_a_c_c library.

   YYaacccc LLiibbrraarryy
       The following functions shall appear only in the _y_a_c_c library
       accessible through the --ll yy operand to _c_9_9; they can therefore be
       redefined by a conforming application:

       iinntt _m_a_i_n(vvooiidd)
             This function shall call _y_y_p_a_r_s_e() and exit with an unspecified
             value. Other actions within this function are unspecified.

       iinntt _y_y_e_r_r_o_r(ccoonnsstt cchhaarr *_s)
             This function shall write the NUL-terminated argument to standard
             error, followed by a <newline>.

       The order of the --ll yy and --ll ll operands given to _c_9_9 is significant;
       the application shall either provide its own _m_a_i_n() function or ensure
       that --ll yy precedes --ll ll.

   DDeebbuuggggiinngg tthhee PPaarrsseerr
       The parser generated by _y_a_c_c shall have diagnostic facilities in it
       that can be optionally enabled at either compile time or at runtime (if
       enabled at compile time).  The compilation of the runtime debugging
       code is under the control of YYDEBUG, a preprocessor symbol. If YYDEBUG
       has a non-zero value, the debugging code shall be included. If its
       value is zero, the code shall not be included.

       In parsers where the debugging code has been included, the external iinntt
       _y_y_d_e_b_u_g can be used to turn debugging on (with a non-zero value) and
       off (zero value) at runtime. The initial value of _y_y_d_e_b_u_g shall be
       zero.

       When --tt is specified, the code file shall be built such that, if
       YYDEBUG is not already defined at compilation time (using the _c_9_9 --DD
       YYDEBUG option, for example), YYDEBUG shall be set explicitly to 1.
       When --tt is not specified, the code file shall be built such that, if
       YYDEBUG is not already defined, it shall be set explicitly to zero.

       The format of the debugging output is unspecified but includes at least
       enough information to determine the shift and reduce actions, and the
       input symbols. It also provides information about error recovery.

   AAllggoorriitthhmmss
       The parser constructed by _y_a_c_c implements an LALR(1) parsing algorithm
       as documented in the literature. It is unspecified whether the parser
       is table-driven or direct-coded.

       A parser generated by _y_a_c_c shall never request an input symbol from
       _y_y_l_e_x() while in a state where the only actions other than the error
       action are reductions by a single rule.

       The literature of parsing theory defines these concepts.

   LLiimmiittss
       The _y_a_c_c utility may have several internal tables. The minimum maximums
       for these tables are shown in the following table. The exact meaning of
       these values is implementation-defined. The implementation shall define
       the relationship between these values and between them and any error
       messages that the implementation may generate should it run out of
       space for any internal structure. An implementation may combine groups
       of these resources into a single pool as long as the total available to
       the user does not fall below the sum of the sizes specified by this
       section.

                           TTaabbllee:: IInntteerrnnaall LLiimmiittss iinn _y_a_c_c

               +-----------+---------+--------------------------------+
               |           | MMiinniimmuumm |                                |
               |  LLiimmiitt    | MMaaxxiimmuumm |          DDeessccrriippttiioonn           |
               +-----------+---------+--------------------------------+
               |{NTERMS}   |   126   | Number of tokens.              |
               |{NNONTERM} |   200   | Number of non-terminals.       |
               |{NPROD}    |   300   | Number of rules.               |
               |{NSTATES}  |   600   | Number of states.              |
               |{MEMSIZE}  |  5200   | Length of rules. The total     |
               |           |         | length, in names (tokens and   |
               |           |         | non-terminals), of all the     |
               |           |         | rules of the grammar. The      |
               |           |         | left-hand side is counted for  |
               |           |         | each rule, even if it is not   |
               |           |         | explicitly repeated, as        |
               |           |         | specified in _G_r_a_m_m_a_r _R_u_l_e_s _i_n  |
               |           |         | _y_a_c_c.                          |
               |{ACTSIZE}  |  4000   | Number of actions. ``Actions'' |
               |           |         | here (and in the description   |
               |           |         | file) refer to parser actions  |
               |           |         | (shift, reduce, and so on) not |
               |           |         | to semantic actions defined in |
               |           |         | _G_r_a_m_m_a_r _R_u_l_e_s _i_n _y_a_c_c.         |
               +-----------+---------+--------------------------------+
EEXXIITT SSTTAATTUUSS
       The following exit values shall be returned:

        0    Successful completion.

       >0    An error occurred.

CCOONNSSEEQQUUEENNCCEESS OOFF EERRRROORRSS
       If any errors are encountered, the run is aborted and _y_a_c_c exits with a
       non-zero status. Partial code files and header files may be produced.
       The summary information in the description file shall always be
       produced if the --vv flag is present.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       Historical implementations experience name conflicts on the names
       yyaacccc..ttmmpp, yyaacccc..aaccttss, yyaacccc..ddeebbuugg, yy..ttaabb..cc, yy..ttaabb..hh, and yy..oouuttppuutt if more
       than one copy of _y_a_c_c is running in a single directory at one time. The
       --bb option was added to overcome this problem. The related problem of
       allowing multiple _y_a_c_c parsers to be placed in the same file was
       addressed by adding a --pp option to override the previously hard-coded
       yyyy variable prefix.

       The description of the --pp option specifies the minimal set of function
       and variable names that cause conflict when multiple parsers are linked
       together. YYSTYPE does not need to be changed. Instead, the programmer
       can use --bb to give the header files for different parsers different
       names, and then the file with the _y_y_l_e_x() for a given parser can
       include the header for that parser. Names such as _y_y_c_l_e_a_r_e_r_r do not
       need to be changed because they are used only in the actions; they do
       not have linkage. It is possible that an implementation has other
       names, either internal ones for implementing things such as _y_y_c_l_e_a_r_e_r_r,
       or providing non-standard features that it wants to change with --pp.

       Unary operators that are the same token as a binary operator in general
       need their precedence adjusted. This is handled by the %%pprreecc advisory
       symbol associated with the particular grammar rule defining that unary
       operator. (See _G_r_a_m_m_a_r _R_u_l_e_s _i_n _y_a_c_c.)  Applications are not required
       to use this operator for unary operators, but the grammars that do not
       require it are rare.

EEXXAAMMPPLLEESS
       Access to the _y_a_c_c library is obtained with library search operands to
       _c_9_9.  To use the _y_a_c_c library _m_a_i_n():

           cc9999 yy..ttaabb..cc --ll yy

       Both the _l_e_x library and the _y_a_c_c library contain _m_a_i_n().  To access
       the _y_a_c_c _m_a_i_n():

           cc9999 yy..ttaabb..cc lleexx..yyyy..cc --ll yy --ll ll

       This ensures that the _y_a_c_c library is searched first, so that its
       _m_a_i_n() is used.

       The historical _y_a_c_c libraries have contained two simple functions that
       are normally coded by the application programmer. These functions are
       similar to the following code:

           ##iinncclluuddee <<llooccaallee..hh>>
           iinntt mmaaiinn((vvooiidd))
           {{
               eexxtteerrnn iinntt yyyyppaarrssee(());;

               setlocale(LC_ALL, "");

               /* If the following parser is one created by lex, the
                  application must be careful to ensure that LC_CTYPE
                  and LC_COLLATE are set to the POSIX locale. */
               (void) yyparse();
               return (0);
           }

           #include <stdio.h>

           int yyerror(const char *msg)
           {
               (void) fprintf(stderr, "%s\n", msg);
               return (0);
           }

RRAATTIIOONNAALLEE
       The references in RReeffeerreenncceedd DDooccuummeennttss may be helpful in constructing
       the parser generator. The referenced DeRemer and Pennello article
       (along with the works it references) describes a technique to generate
       parsers that conform to this volume of POSIX.1-2008. Work in this area
       continues to be done, so implementors should consult current literature
       before doing any new implementations. The original Knuth article is the
       theoretical basis for this kind of parser, but the tables it generates
       are impractically large for reasonable grammars and should not be used.
       The ``equivalent to'' wording is intentional to assure that the best
       tables that are LALR(1) can be generated.

       There has been confusion between the class of grammars, the algorithms
       needed to generate parsers, and the algorithms needed to parse the
       languages. They are all reasonably orthogonal. In particular, a parser
       generator that accepts the full range of LR(1) grammars need not
       generate a table any more complex than one that accepts SLR(1) (a
       relatively weak class of LR grammars) for a grammar that happens to be
       SLR(1). Such an implementation need not recognize the case, either;
       table compression can yield the SLR(1) table (or one even smaller than
       that) without recognizing that the grammar is SLR(1).  The speed of an
       LR(1) parser for any class is dependent more upon the table
       representation and compression (or the code generation if a direct
       parser is generated) than upon the class of grammar that the table
       generator handles.

       The speed of the parser generator is somewhat dependent upon the class
       of grammar it handles. However, the original Knuth article algorithms
       for constructing LR parsers were judged by its author to be
       impractically slow at that time. Although full LR is more complex than
       LALR(1), as computer speeds and algorithms improve, the difference (in
       terms of acceptable wall-clock execution time) is becoming less
       significant.

       Potential authors are cautioned that the referenced DeRemer and
       Pennello article previously cited identifies a bug (an over-
       simplification of the computation of LALR(1) lookahead sets) in some of
       the LALR(1) algorithm statements that preceded it to publication. They
       should take the time to seek out that paper, as well as current
       relevant work, particularly Aho's.

       The --bb option was added to provide a portable method for permitting
       _y_a_c_c to work on multiple separate parsers in the same directory. If a
       directory contains more than one _y_a_c_c grammar, and both grammars are
       constructed at the same time (by, for example, a parallel _m_a_k_e
       program), conflict results. While the solution is not historical
       practice, it corrects a known deficiency in historical implementations.
       Corresponding changes were made to all sections that referenced the
       filenames yy..ttaabb..cc (now ``the code file''), yy..ttaabb..hh (now ``the header
       file''), and yy..oouuttppuutt (now ``the description file'').

       The grammar for _y_a_c_c input is based on System V documentation. The
       textual description shows there that the '';;'' is required at the end of
       the rule. The grammar and the implementation do not require this. (The
       use of CC__IIDDEENNTTIIFFIIEERR causes a reduce to occur in the right place.)

       Also, in that implementation, the constructs such as %%ttookkeenn can be
       terminated by a <semicolon>, but this is not permitted by the grammar.
       The keywords such as %%ttookkeenn can also appear in uppercase, which is
       again not discussed. In most places where ''%%'' is used, <backslash> can
       be substituted, and there are alternate spellings for some of the
       symbols (for example, %%LLEEFFTT can be ""%%<<"" or even ""\\<<"").

       Historically, <_t_a_g> can contain any characters except ''>>'', including
       white space, in the implementation. However, since the _t_a_g must
       reference an ISO C standard union member, in practice conforming
       implementations need to support only the set of characters for ISO C
       standard identifiers in this context.

       Some historical implementations are known to accept actions that are
       terminated by a period. Historical implementations often allow ''$$'' in
       names. A conforming implementation does not need to support either of
       these behaviors.

       Deciding when to use %%pprreecc illustrates the difficulty in specifying the
       behavior of _y_a_c_c.  There may be situations in which the _g_r_a_m_m_a_r is not,
       strictly speaking, in error, and yet _y_a_c_c cannot interpret it
       unambiguously. The resolution of ambiguities in the grammar can in many
       instances be resolved by providing additional information, such as
       using %%ttyyppee or %%uunniioonn declarations. It is often easier and it usually
       yields a smaller parser to take this alternative when it is
       appropriate.

       The size and execution time of a program produced without the runtime
       debugging code is usually smaller and slightly faster in historical
       implementations.

       Statistics messages from several historical implementations include the
       following types of information:

           _n/512 terminals, _n/300 non-terminals
           _n/600 grammar rules, _n/1500 states
           _n shift/reduce, _n reduce/reduce conflicts reported
           _n/350 working sets used
           Memory: states, etc. _n/15000, parser _n/15000
           _n/600 distinct lookahead sets
           _n extra closures
           _n shift entries, _n exceptions
           _n goto entries
           _n entries saved by goto default
           Optimizer space used: input _n/15000, output _n/15000
           _n table entries, _n zero
           Maximum spread: _n, Maximum offset: _n

       The report of internal tables in the description file is left
       implementation-defined because all aspects of these limits are also
       implementation-defined. Some implementations may use dynamic allocation
       techniques and have no specific limit values to report.

       The format of the yy..oouuttppuutt file is not given because specification of
       the format was not seen to enhance applications portability. The
       listing is primarily intended to help human users understand and debug
       the parser; use of yy..oouuttppuutt by a conforming application script would be
       unusual. Furthermore, implementations have not produced consistent
       output and no popular format was apparent. The format selected by the
       implementation should be human-readable, in addition to the requirement
       that it be a text file.

       Standard error reports are not specifically described because they are
       seldom of use to conforming applications and there was no reason to
       restrict implementations.

       Some implementations recognize ""=={{"" as equivalent to ''{{'' because it
       appears in historical documentation. This construction was recognized
       and documented as obsolete as long ago as 1978, in the referenced _Y_a_c_c_:
       _Y_e_t _A_n_o_t_h_e_r _C_o_m_p_i_l_e_r_-_C_o_m_p_i_l_e_r. This volume of POSIX.1-2008 chose to
       leave it as obsolete and omit it.

       Multi-byte characters should be recognized by the lexical analyzer and
       returned as tokens. They should not be returned as multi-byte character
       literals. The token eerrrroorr that is used for error recovery is normally
       assigned the value 256 in the historical implementation. Thus, the
       token value 256, which is used in many multi-byte character sets, is
       not available for use as the value of a user-defined token.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _c_9_9, _l_e_x

       The Base Definitions volume of POSIX.1-2008, _C_h_a_p_t_e_r _8, _E_n_v_i_r_o_n_m_e_n_t
       _V_a_r_i_a_b_l_e_s, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group Standard
       is the referee document. The original Standard can be obtained online
       at http://www.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2013                              YACC(1)
