X-Git-Url: https://git.saurik.com/bison.git/blobdiff_plain/064e42b0aca1db0ca84b06b01cac5a40f3016591..cc8962bdde81b04aa728aef21e53b4a08a0debfe:/doc/bison.texi diff --git a/doc/bison.texi b/doc/bison.texi index a6ff03b2..250e94d8 100644 --- a/doc/bison.texi +++ b/doc/bison.texi @@ -33,7 +33,7 @@ This manual (@value{UPDATED}) is for GNU Bison (version @value{VERSION}), the GNU parser generator. -Copyright @copyright{} 1988-1993, 1995, 1998-2012 Free Software +Copyright @copyright{} 1988-1993, 1995, 1998-2013 Free Software Foundation, Inc. @quotation @@ -186,7 +186,6 @@ Bison Grammar Files * Grammar Outline:: Overall layout of the grammar file. * Symbols:: Terminal and nonterminal symbols. * Rules:: How to write grammar rules. -* Recursion:: Writing recursive rules. * Semantics:: Semantic values and actions. * Tracking Locations:: Locations and actions. * Named References:: Using named references in actions. @@ -201,16 +200,32 @@ Outline of a Bison Grammar * Grammar Rules:: Syntax and usage of the grammar rules section. * Epilogue:: Syntax and usage of the epilogue. +Grammar Rules + +* Rules Syntax:: Syntax of the rules. +* Empty Rules:: Symbols that can match the empty string. +* Recursion:: Writing recursive rules. + + Defining Language Semantics * Value Type:: Specifying one data type for all semantic values. * Multiple Types:: Specifying several alternative data types. +* Type Generation:: Generating the semantic value type. +* Union Decl:: Declaring the set of all semantic value types. +* Structured Value Type:: Providing a structured semantic value type. * Actions:: An action is the semantic definition of a grammar rule. * Action Types:: Specifying data types for actions to operate on. * Mid-Rule Actions:: Most actions go at the end of a rule. This says when, why and how to use the exceptional action in the middle of a rule. +Actions in Mid-Rule + +* Using Mid-Rule Actions:: Putting an action in the middle of a rule. +* Mid-Rule Action Translation:: How mid-rule actions are actually processed. +* Mid-Rule Conflicts:: Mid-rule actions can cause conflicts. + Tracking Locations * Location Type:: Specifying a data type for locations. @@ -222,7 +237,6 @@ Bison Declarations * Require Decl:: Requiring a Bison version. * Token Decl:: Declaring terminal symbols. * Precedence Decl:: Declaring terminals with precedence and associativity. -* Union Decl:: Declaring the set of all semantic value types. * Type Decl:: Declaring the choice of type for a nonterminal symbol. * Initial Action Decl:: Code run before parsing starts. * Destructor Decl:: Declaring how symbols are freed. @@ -1001,7 +1015,7 @@ Let's consider an example, vastly simplified from a C++ grammar. %% prog: - /* Nothing. */ + %empty | prog stmt @{ printf ("\n"); @} ; @@ -1532,14 +1546,16 @@ calculator. As in C, comments are placed between @samp{/*@dots{}*/}. @example /* Reverse polish notation calculator. */ +@group %@{ - #define YYSTYPE double #include #include int yylex (void); void yyerror (char const *); %@} +@end group +%define api.value.type @{double@} %token NUM %% /* Grammar rules and actions follow. */ @@ -1548,14 +1564,6 @@ calculator. As in C, comments are placed between @samp{/*@dots{}*/}. The declarations section (@pxref{Prologue, , The prologue}) contains two preprocessor directives and two forward declarations. -The @code{#define} directive defines the macro @code{YYSTYPE}, thus -specifying the C data type for semantic values of both tokens and -groupings (@pxref{Value Type, ,Data Types of Semantic Values}). The -Bison parser will use whatever type @code{YYSTYPE} is defined as; if you -don't define it, @code{int} is the default. Because we specify -@code{double}, each token and each expression has an associated value, -which is a floating point number. - The @code{#include} directive is used to declare the exponentiation function @code{pow}. @@ -1565,14 +1573,24 @@ before they are used. These functions will be defined in the epilogue, but the parser calls them so they must be declared in the prologue. -The second section, Bison declarations, provides information to Bison -about the token types (@pxref{Bison Declarations, ,The Bison -Declarations Section}). Each terminal symbol that is not a -single-character literal must be declared here. (Single-character -literals normally don't need to be declared.) In this example, all the -arithmetic operators are designated by single-character literals, so the -only terminal symbol that needs to be declared is @code{NUM}, the token -type for numeric constants. +The second section, Bison declarations, provides information to Bison about +the tokens and their types (@pxref{Bison Declarations, ,The Bison +Declarations Section}). + +The @code{%define} directive defines the variable @code{api.value.type}, +thus specifying the C data type for semantic values of both tokens and +groupings (@pxref{Value Type, ,Data Types of Semantic Values}). The Bison +parser will use whatever type @code{api.value.type} is defined as; if you +don't define it, @code{int} is the default. Because we specify +@samp{@{double@}}, each token and each expression has an associated value, +which is a floating point number. C code can use @code{YYSTYPE} to refer to +the value @code{api.value.type}. + +Each terminal symbol that is not a single-character literal must be +declared. (Single-character literals normally don't need to be declared.) +In this example, all the arithmetic operators are designated by +single-character literals, so the only terminal symbol that needs to be +declared is @code{NUM}, the token type for numeric constants. @node Rpcalc Rules @subsection Grammar Rules for @code{rpcalc} @@ -1583,7 +1601,7 @@ Here are the grammar rules for the reverse polish notation calculator. @example @group input: - /* empty */ + %empty | input line ; @end group @@ -1640,7 +1658,7 @@ Consider the definition of @code{input}: @example input: - /* empty */ + %empty | input line ; @end example @@ -1655,8 +1673,9 @@ The first alternative is empty because there are no symbols between the colon and the first @samp{|}; this means that @code{input} can match an empty string of input (no tokens). We write the rules this way because it is legitimate to type @kbd{Ctrl-d} right after you start the calculator. -It's conventional to put an empty alternative first and write the comment -@samp{/* empty */} in it. +It's conventional to put an empty alternative first and to use the +(optional) @code{%empty} directive, or to write the comment @samp{/* empty +*/} in it (@pxref{Empty Rules}). The second alternate rule (@code{input line}) handles all nontrivial input. It means, ``After reading any number of lines, read one more line if @@ -1785,9 +1804,9 @@ therefore, @code{NUM} becomes a macro for @code{yylex} to use. The semantic value of the token (if it has one) is stored into the global variable @code{yylval}, which is where the Bison parser will look -for it. (The C data type of @code{yylval} is @code{YYSTYPE}, which was -defined at the beginning of the grammar; @pxref{Rpcalc Declarations, -,Declarations for @code{rpcalc}}.) +for it. (The C data type of @code{yylval} is @code{YYSTYPE}, whose value +was defined at the beginning of the grammar via @samp{%define api.value.type +@{double@}}; @pxref{Rpcalc Declarations,,Declarations for @code{rpcalc}}.) A token type code of zero is returned if the end-of-input is encountered. (Bison recognizes any nonpositive value as indicating end-of-input.) @@ -1976,7 +1995,6 @@ parentheses nested to arbitrary depth. Here is the Bison code for @group %@{ - #define YYSTYPE double #include #include int yylex (void); @@ -1986,6 +2004,7 @@ parentheses nested to arbitrary depth. Here is the Bison code for @group /* Bison declarations. */ +%define api.value.type @{double@} %token NUM %left '-' '+' %left '*' '/' @@ -1996,7 +2015,7 @@ parentheses nested to arbitrary depth. Here is the Bison code for %% /* The grammar follows. */ @group input: - /* empty */ + %empty | input line ; @end group @@ -2135,13 +2154,13 @@ the same as the declarations for the infix notation calculator. /* Location tracking calculator. */ %@{ - #define YYSTYPE int #include int yylex (void); void yyerror (char const *); %@} /* Bison declarations. */ +%define api.value.type int %token NUM %left '-' '+' @@ -2176,7 +2195,7 @@ wrong expressions or subexpressions. @example @group input: - /* empty */ + %empty | input line ; @end group @@ -2388,24 +2407,19 @@ Here are the C and Bison declarations for the multi-function calculator. %@{ #include /* For printf, etc. */ #include /* For pow, used in the grammar. */ - #include "calc.h" /* Contains definition of `symrec'. */ + #include "calc.h" /* Contains definition of 'symrec'. */ int yylex (void); void yyerror (char const *); %@} @end group -@group -%union @{ - double val; /* For returning numbers. */ - symrec *tptr; /* For returning symbol-table pointers. */ -@} -@end group -%token NUM /* Simple double precision number. */ -%token VAR FNCT /* Variable and function. */ -%type exp +%define api.value.type union /* Generate YYSTYPE from these types: */ +%token NUM /* Simple double precision number. */ +%token VAR FNCT /* Symbol table pointer: variable and function. */ +%type exp @group -%right '=' +%precedence '=' %left '-' '+' %left '*' '/' %precedence NEG /* negation--unary minus */ @@ -2417,23 +2431,23 @@ The above grammar introduces only two new features of the Bison language. These features allow semantic values to have various data types (@pxref{Multiple Types, ,More Than One Value Type}). -The @code{%union} declaration specifies the entire list of possible types; -this is instead of defining @code{YYSTYPE}. The allowable types are now -double-floats (for @code{exp} and @code{NUM}) and pointers to entries in -the symbol table. @xref{Union Decl, ,The Collection of Value Types}. - -Since values can now have various types, it is necessary to associate a -type with each grammar symbol whose semantic value is used. These symbols -are @code{NUM}, @code{VAR}, @code{FNCT}, and @code{exp}. Their -declarations are augmented with information about their data type (placed -between angle brackets). - -The Bison construct @code{%type} is used for declaring nonterminal -symbols, just as @code{%token} is used for declaring token types. We -have not used @code{%type} before because nonterminal symbols are -normally declared implicitly by the rules that define them. But -@code{exp} must be declared explicitly so we can specify its value type. -@xref{Type Decl, ,Nonterminal Symbols}. +The special @code{union} value assigned to the @code{%define} variable +@code{api.value.type} specifies that the symbols are defined with their data +types. Bison will generate an appropriate definition of @code{YYSTYPE} to +store these values. + +Since values can now have various types, it is necessary to associate a type +with each grammar symbol whose semantic value is used. These symbols are +@code{NUM}, @code{VAR}, @code{FNCT}, and @code{exp}. Their declarations are +augmented with their data type (placed between angle brackets). For +instance, values of @code{NUM} are stored in @code{double}. + +The Bison construct @code{%type} is used for declaring nonterminal symbols, +just as @code{%token} is used for declaring token types. Previously we did +not use @code{%type} before because nonterminal symbols are normally +declared implicitly by the rules that define them. But @code{exp} must be +declared explicitly so we can specify its value type. @xref{Type Decl, +,Nonterminal Symbols}. @node Mfcalc Rules @subsection Grammar Rules for @code{mfcalc} @@ -2447,7 +2461,7 @@ those which mention @code{VAR} or @code{FNCT}, are new. %% /* The grammar follows. */ @group input: - /* empty */ + %empty | input line ; @end group @@ -2517,7 +2531,7 @@ struct symrec @group typedef struct symrec symrec; -/* The symbol table: a chain of `struct symrec'. */ +/* The symbol table: a chain of 'struct symrec'. */ extern symrec *sym_table; symrec *putsym (char const *, int); @@ -2552,7 +2566,7 @@ struct init const arith_fncts[] = @end group @group -/* The symbol table: a chain of `struct symrec'. */ +/* The symbol table: a chain of 'struct symrec'. */ symrec *sym_table; @end group @@ -2657,11 +2671,18 @@ yylex (void) if (c == '.' || isdigit (c)) @{ ungetc (c, stdin); - scanf ("%lf", &yylval.val); + scanf ("%lf", &yylval.NUM); return NUM; @} @end group +@end example +@noindent +Bison generated a definition of @code{YYSTYPE} with a member named +@code{NUM} to store value of @code{NUM} symbols. + +@comment file: mfcalc.y: 3 +@example @group /* Char starts an identifier => read the name. */ if (isalpha (c)) @@ -2703,7 +2724,7 @@ yylex (void) s = getsym (symbuf); if (s == 0) s = putsym (symbuf, VAR); - yylval.tptr = s; + *((symrec**) &yylval) = s; return s->type; @} @@ -2781,7 +2802,6 @@ The Bison grammar file conventionally has a name ending in @samp{.y}. * Grammar Outline:: Overall layout of the grammar file. * Symbols:: Terminal and nonterminal symbols. * Rules:: How to write grammar rules. -* Recursion:: Writing recursive rules. * Semantics:: Semantic values and actions. * Tracking Locations:: Locations and actions. * Named References:: Using named references in actions. @@ -2791,6 +2811,9 @@ The Bison grammar file conventionally has a name ending in @samp{.y}. @node Grammar Outline @section Outline of a Bison Grammar +@cindex comment +@findex // @dots{} +@findex /* @dots{} */ A Bison grammar file has four main sections, shown here with the appropriate delimiters: @@ -2810,8 +2833,8 @@ appropriate delimiters: @end example Comments enclosed in @samp{/* @dots{} */} may appear in any of the sections. -As a GNU extension, @samp{//} introduces a comment that -continues until end of line. +As a GNU extension, @samp{//} introduces a comment that continues until end +of line. @menu * Prologue:: Syntax and usage of the prologue. @@ -2848,21 +2871,27 @@ can be done with two @var{Prologue} blocks, one before and one after the @code{%union} declaration. @example +@group %@{ #define _GNU_SOURCE #include #include "ptypes.h" %@} +@end group +@group %union @{ long int n; tree t; /* @r{@code{tree} is defined in @file{ptypes.h}.} */ @} +@end group +@group %@{ static void print_token_value (FILE *, int, YYSTYPE); #define YYPRINT(F, N, L) print_token_value (F, N, L) %@} +@end group @dots{} @end example @@ -2894,21 +2923,27 @@ location, or it can be one of @code{requires}, @code{provides}, Look again at the example of the previous section: @example +@group %@{ #define _GNU_SOURCE #include #include "ptypes.h" %@} +@end group +@group %union @{ long int n; tree t; /* @r{@code{tree} is defined in @file{ptypes.h}.} */ @} +@end group +@group %@{ static void print_token_value (FILE *, int, YYSTYPE); #define YYPRINT(F, N, L) print_token_value (F, N, L) %@} +@end group @dots{} @end example @@ -2946,7 +2981,7 @@ Let's go ahead and add the new @code{YYLTYPE} definition and the #include /* WARNING: The following code really belongs - * in a `%code requires'; see below. */ + * in a '%code requires'; see below. */ #include "ptypes.h" #define YYLTYPE YYLTYPE @@ -2960,16 +2995,20 @@ Let's go ahead and add the new @code{YYLTYPE} definition and the @} YYLTYPE; @} +@group %union @{ long int n; tree t; /* @r{@code{tree} is defined in @file{ptypes.h}.} */ @} +@end group +@group %code @{ static void print_token_value (FILE *, int, YYSTYPE); #define YYPRINT(F, N, L) print_token_value (F, N, L) static void trace_token (enum yytokentype token, YYLTYPE loc); @} +@end group @dots{} @end example @@ -3380,7 +3419,18 @@ value of the error token is 256, unless you explicitly assigned 256 to one of your tokens with a @code{%token} declaration. @node Rules -@section Syntax of Grammar Rules +@section Grammar Rules + +A Bison grammar is a list of rules. + +@menu +* Rules Syntax:: Syntax of the rules. +* Empty Rules:: Symbols that can match the empty string. +* Recursion:: Writing recursive rules. +@end menu + +@node Rules Syntax +@subsection Syntax of Grammar Rules @cindex rule syntax @cindex grammar rule syntax @cindex syntax of grammar rules @@ -3454,33 +3504,57 @@ be joined with the vertical-bar character @samp{|} as follows: @noindent They are still considered distinct rules even when joined in this way. -If @var{components} in a rule is empty, it means that @var{result} can -match the empty string. For example, here is how to define a -comma-separated sequence of zero or more @code{exp} groupings: +@node Empty Rules +@subsection Empty Rules +@cindex empty rule +@cindex rule, empty +@findex %empty + +A rule is said to be @dfn{empty} if its right-hand side (@var{components}) +is empty. It means that @var{result} can match the empty string. For +example, here is how to define an optional semicolon: + +@example +semicolon.opt: | ";"; +@end example + +@noindent +It is easy not to see an empty rule, especially when @code{|} is used. The +@code{%empty} directive allows to make explicit that a rule is empty on +purpose: @example @group -expseq: - /* empty */ -| expseq1 +semicolon.opt: + %empty +| ";" ; @end group +@end example +Flagging a non-empty rule with @code{%empty} is an error. If run with +@option{-Wempty-rule}, @command{bison} will report empty rules without +@code{%empty}. Using @code{%empty} enables this warning, unless +@option{-Wno-empty-rule} was specified. + +The @code{%empty} directive is a Bison extension, it does not work with +Yacc. To remain compatible with POSIX Yacc, it is customary to write a +comment @samp{/* empty */} in each rule with no components: + +@example @group -expseq1: - exp -| expseq1 ',' exp +semicolon.opt: + /* empty */ +| ";" ; @end group @end example -@noindent -It is customary to write a comment @samp{/* empty */} in each rule -with no components. @node Recursion -@section Recursive Rules +@subsection Recursive Rules @cindex recursive rule +@cindex rule, recursive A rule is called @dfn{recursive} when its @var{result} nonterminal appears also on its right hand side. Nearly all Bison grammars need to @@ -3568,6 +3642,9 @@ the numbers associated with @var{x} and @var{y}. @menu * Value Type:: Specifying one data type for all semantic values. * Multiple Types:: Specifying several alternative data types. +* Type Generation:: Generating the semantic value type. +* Union Decl:: Declaring the set of all semantic value types. +* Structured Value Type:: Providing a structured semantic value type. * Actions:: An action is the semantic definition of a grammar rule. * Action Types:: Specifying data types for actions to operate on. * Mid-Rule Actions:: Most actions go at the end of a rule. @@ -3589,17 +3666,38 @@ Notation Calculator}). Bison normally uses the type @code{int} for semantic values if your program uses the same data type for all language constructs. To -specify some other type, define @code{YYSTYPE} as a macro, like this: +specify some other type, define the @code{%define} variable +@code{api.value.type} like this: + +@example +%define api.value.type @{double@} +@end example + +@noindent +or + +@example +%define api.value.type @{struct semantic_type@} +@end example + +The value of @code{api.value.type} should be a type name that does not +contain parentheses or square brackets. + +Alternatively, instead of relying of Bison's @code{%define} support, you may +rely on the C/C++ preprocessor and define @code{YYSTYPE} as a macro, like +this: @example #define YYSTYPE double @end example @noindent -@code{YYSTYPE}'s replacement list should be a type name -that does not contain parentheses or square brackets. This macro definition must go in the prologue of the grammar file -(@pxref{Grammar Outline, ,Outline of a Bison Grammar}). +(@pxref{Grammar Outline, ,Outline of a Bison Grammar}). If compatibility +with POSIX Yacc matters to you, use this. Note however that Bison cannot +know @code{YYSTYPE}'s value, not even whether it is defined, so there are +services it cannot provide. Besides this works only for languages that have +a preprocessor. @node Multiple Types @subsection More Than One Value Type @@ -3615,11 +3713,25 @@ requires you to do two things: @itemize @bullet @item -Specify the entire collection of possible data types, either by using the -@code{%union} Bison declaration (@pxref{Union Decl, ,The Collection of -Value Types}), or by using a @code{typedef} or a @code{#define} to -define @code{YYSTYPE} to be a union type whose member names are -the type tags. +Specify the entire collection of possible data types. There are several +options: +@itemize @bullet +@item +let Bison compute the union type from the tags you assign to symbols; + +@item +use the @code{%union} Bison declaration (@pxref{Union Decl, ,The Union +Declaration}); + +@item +define the @code{%define} variable @code{api.value.type} to be a union type +whose members are the type tags (@pxref{Structured Value Type,, Providing a +Structured Semantic Value Type}); + +@item +use a @code{typedef} or a @code{#define} to define @code{YYSTYPE} to be a +union type whose member names are the type tags. +@end itemize @item Choose one of those types for each symbol (terminal or nonterminal) for @@ -3629,6 +3741,164 @@ and for groupings with the @code{%type} Bison declaration (@pxref{Type Decl, ,Nonterminal Symbols}). @end itemize +@node Type Generation +@subsection Generating the Semantic Value Type +@cindex declaring value types +@cindex value types, declaring +@findex %define api.value.type union + +The special value @code{union} of the @code{%define} variable +@code{api.value.type} instructs Bison that the tags used with the +@code{%token} and @code{%type} directives are genuine types, not names of +members of @code{YYSTYPE}. + +For example: + +@example +%define api.value.type union +%token INT "integer" +%token 'n' +%type expr +%token ID "identifier" +@end example + +@noindent +generates an appropriate value of @code{YYSTYPE} to support each symbol +type. The name of the member of @code{YYSTYPE} for tokens than have a +declared identifier @var{id} (such as @code{INT} and @code{ID} above, but +not @code{'n'}) is @code{@var{id}}. The other symbols have unspecified +names on which you should not depend; instead, relying on C casts to access +the semantic value with the appropriate type: + +@example +/* For an "integer". */ +yylval.INT = 42; +return INT; + +/* For an 'n', also declared as int. */ +*((int*)&yylval) = 42; +return 'n'; + +/* For an "identifier". */ +yylval.ID = "42"; +return ID; +@end example + +If the @code{%define} variable @code{api.token.prefix} is defined +(@pxref{%define Summary,,api.token.prefix}), then it is also used to prefix +the union member names. For instance, with @samp{%define api.token.prefix +TOK_}: + +@example +/* For an "integer". */ +yylval.TOK_INT = 42; +return TOK_INT; +@end example + +This Bison extension cannot work if @code{%yacc} (or +@option{-y}/@option{--yacc}) is enabled, as POSIX mandates that Yacc +generate tokens as macros (e.g., @samp{#define INT 258}, or @samp{#define +TOK_INT 258}). + +This feature is new, and user feedback would be most welcome. + +A similar feature is provided for C++ that in addition overcomes C++ +limitations (that forbid non-trivial objects to be part of a @code{union}): +@samp{%define api.value.type variant}, see @ref{C++ Variants}. + +@node Union Decl +@subsection The Union Declaration +@cindex declaring value types +@cindex value types, declaring +@findex %union + +The @code{%union} declaration specifies the entire collection of possible +data types for semantic values. The keyword @code{%union} is followed by +braced code containing the same thing that goes inside a @code{union} in C@. + +For example: + +@example +@group +%union @{ + double val; + symrec *tptr; +@} +@end group +@end example + +@noindent +This says that the two alternative types are @code{double} and @code{symrec +*}. They are given names @code{val} and @code{tptr}; these names are used +in the @code{%token} and @code{%type} declarations to pick one of the types +for a terminal or nonterminal symbol (@pxref{Type Decl, ,Nonterminal Symbols}). + +As an extension to POSIX, a tag is allowed after the @code{%union}. For +example: + +@example +@group +%union value @{ + double val; + symrec *tptr; +@} +@end group +@end example + +@noindent +specifies the union tag @code{value}, so the corresponding C type is +@code{union value}. If you do not specify a tag, it defaults to +@code{YYSTYPE}. + +As another extension to POSIX, you may specify multiple @code{%union} +declarations; their contents are concatenated. However, only the first +@code{%union} declaration can specify a tag. + +Note that, unlike making a @code{union} declaration in C, you need not write +a semicolon after the closing brace. + +@node Structured Value Type +@subsection Providing a Structured Semantic Value Type +@cindex declaring value types +@cindex value types, declaring +@findex %union + +Instead of @code{%union}, you can define and use your own union type +@code{YYSTYPE} if your grammar contains at least one @samp{<@var{type}>} +tag. For example, you can put the following into a header file +@file{parser.h}: + +@example +@group +union YYSTYPE @{ + double val; + symrec *tptr; +@}; +@end group +@end example + +@noindent +and then your grammar can use the following instead of @code{%union}: + +@example +@group +%@{ +#include "parser.h" +%@} +%define api.value.type "union YYSTYPE" +%type expr +%token ID +@end group +@end example + +Actually, you may also provide a @code{struct} rather that a @code{union}, +which may be handy if you want to track information for every symbol (such +as preceding comments). + +The type you provide may even be structured and include pointers, in which +case the type tags you provide may be composite, with @samp{.} and @samp{->} +operators. + @node Actions @subsection Actions @cindex action @@ -3730,7 +4000,7 @@ foo: @group bar: - /* empty */ @{ previous_expr = $0; @} + %empty @{ previous_expr = $0; @} ; @end group @end example @@ -3799,6 +4069,15 @@ Occasionally it is useful to put an action in the middle of a rule. These actions are written just like usual end-of-rule actions, but they are executed before the parser even recognizes the following components. +@menu +* Using Mid-Rule Actions:: Putting an action in the middle of a rule. +* Mid-Rule Action Translation:: How mid-rule actions are actually processed. +* Mid-Rule Conflicts:: Mid-rule actions can cause conflicts. +@end menu + +@node Using Mid-Rule Actions +@subsubsection Using Mid-Rule Actions + A mid-rule action may refer to the components preceding it using @code{$@var{n}}, but it may not refer to subsequent components because it is run before they are parsed. @@ -3831,10 +4110,16 @@ remove it afterward. Here is how it is done: @example @group stmt: - LET '(' var ')' - @{ $$ = push_context (); declare_variable ($3); @} + "let" '(' var ')' + @{ + $$ = push_context (); + declare_variable ($3); + @} stmt - @{ $$ = $6; pop_context ($5); @} + @{ + $$ = $6; + pop_context ($5); + @} @end group @end example @@ -3845,8 +4130,27 @@ list of accessible variables) as its semantic value, using alternative @code{context} in the data-type union. Then it calls @code{declare_variable} to add the new variable to that list. Once the first action is finished, the embedded statement @code{stmt} can be -parsed. Note that the mid-rule action is component number 5, so the -@samp{stmt} is component number 6. +parsed. + +Note that the mid-rule action is component number 5, so the @samp{stmt} is +component number 6. Named references can be used to improve the readability +and maintainability (@pxref{Named References}): + +@example +@group +stmt: + "let" '(' var ')' + @{ + $let = push_context (); + declare_variable ($3); + @}[let] + stmt + @{ + $$ = $6; + pop_context ($let); + @} +@end group +@end example After the embedded statement is parsed, its semantic value becomes the value of the entire @code{let}-statement. Then the semantic value from the @@ -3873,20 +4177,24 @@ declare a destructor for that symbol: @group %type let %destructor @{ pop_context ($$); @} let +@end group %% +@group stmt: let stmt @{ $$ = $2; - pop_context ($1); + pop_context ($let); @}; +@end group +@group let: - LET '(' var ')' + "let" '(' var ')' @{ - $$ = push_context (); + $let = push_context (); declare_variable ($3); @}; @@ -3898,6 +4206,76 @@ Note that the action is now at the end of its rule. Any mid-rule action can be converted to an end-of-rule action in this way, and this is what Bison actually does to implement mid-rule actions. +@node Mid-Rule Action Translation +@subsubsection Mid-Rule Action Translation +@vindex $@@@var{n} +@vindex @@@var{n} + +As hinted earlier, mid-rule actions are actually transformed into regular +rules and actions. The various reports generated by Bison (textual, +graphical, etc., see @ref{Understanding, , Understanding Your Parser}) +reveal this translation, best explained by means of an example. The +following rule: + +@example +exp: @{ a(); @} "b" @{ c(); @} @{ d(); @} "e" @{ f(); @}; +@end example + +@noindent +is translated into: + +@example +$@@1: %empty @{ a(); @}; +$@@2: %empty @{ c(); @}; +$@@3: %empty @{ d(); @}; +exp: $@@1 "b" $@@2 $@@3 "e" @{ f(); @}; +@end example + +@noindent +with new nonterminal symbols @code{$@@@var{n}}, where @var{n} is a number. + +A mid-rule action is expected to generate a value if it uses @code{$$}, or +the (final) action uses @code{$@var{n}} where @var{n} denote the mid-rule +action. In that case its nonterminal is rather named @code{@@@var{n}}: + +@example +exp: @{ a(); @} "b" @{ $$ = c(); @} @{ d(); @} "e" @{ f = $1; @}; +@end example + +@noindent +is translated into + +@example +@@1: %empty @{ a(); @}; +@@2: %empty @{ $$ = c(); @}; +$@@3: %empty @{ d(); @}; +exp: @@1 "b" @@2 $@@3 "e" @{ f = $1; @} +@end example + +There are probably two errors in the above example: the first mid-rule +action does not generate a value (it does not use @code{$$} although the +final action uses it), and the value of the second one is not used (the +final action does not use @code{$3}). Bison reports these errors when the +@code{midrule-value} warnings are enabled (@pxref{Invocation, ,Invoking +Bison}): + +@example +$ bison -fcaret -Wmidrule-value mid.y +@group +mid.y:2.6-13: warning: unset value: $$ + exp: @{ a(); @} "b" @{ $$ = c(); @} @{ d(); @} "e" @{ f = $1; @}; + ^^^^^^^^ +@end group +@group +mid.y:2.19-31: warning: unused value: $3 + exp: @{ a(); @} "b" @{ $$ = c(); @} @{ d(); @} "e" @{ f = $1; @}; + ^^^^^^^^^^^^^ +@end group +@end example + + +@node Mid-Rule Conflicts +@subsubsection Conflicts due to Mid-Rule Actions Taking action before a rule is completely recognized often leads to conflicts since the parser must commit to a parse in order to execute the action. For example, the following two rules, without mid-rule actions, @@ -3979,7 +4357,7 @@ serves as a subroutine: @example @group subroutine: - /* empty */ @{ prepare_for_local_variables (); @} + %empty @{ prepare_for_local_variables (); @} ; @end group @@ -3995,6 +4373,7 @@ compound: Now Bison can execute the action in the rule for @code{subroutine} without deciding which rule for @code{compound} it will eventually use. + @node Tracking Locations @section Tracking Locations @cindex location @@ -4085,8 +4464,7 @@ exp: else @{ $$ = 1; - fprintf (stderr, - "Division by zero, l%d,c%d-l%d,c%d", + fprintf (stderr, "%d.%d-%d.%d: division by zero", @@3.first_line, @@3.first_column, @@3.last_line, @@3.last_column); @} @@ -4113,8 +4491,7 @@ exp: else @{ $$ = 1; - fprintf (stderr, - "Division by zero, l%d,c%d-l%d,c%d", + fprintf (stderr, "%d.%d-%d.%d: division by zero", @@3.first_line, @@3.first_column, @@3.last_line, @@3.last_column); @} @@ -4322,7 +4699,6 @@ and Context-Free Grammars}). * Require Decl:: Requiring a Bison version. * Token Decl:: Declaring terminal symbols. * Precedence Decl:: Declaring terminals with precedence and associativity. -* Union Decl:: Declaring the set of all semantic value types. * Type Decl:: Declaring the choice of type for a nonterminal symbol. * Initial Action Decl:: Code run before parsing starts. * Destructor Decl:: Declaring how symbols are freed. @@ -4469,121 +4845,40 @@ And indeed any of these declarations serves the purposes of @code{%token}. But in addition, they specify the associativity and relative precedence for all the @var{symbols}: -@itemize @bullet -@item -The associativity of an operator @var{op} determines how repeated uses -of the operator nest: whether @samp{@var{x} @var{op} @var{y} @var{op} -@var{z}} is parsed by grouping @var{x} with @var{y} first or by -grouping @var{y} with @var{z} first. @code{%left} specifies -left-associativity (grouping @var{x} with @var{y} first) and -@code{%right} specifies right-associativity (grouping @var{y} with -@var{z} first). @code{%nonassoc} specifies no associativity, which -means that @samp{@var{x} @var{op} @var{y} @var{op} @var{z}} is -considered a syntax error. - -@code{%precedence} gives only precedence to the @var{symbols}, and -defines no associativity at all. Use this to define precedence only, -and leave any potential conflict due to associativity enabled. - -@item -The precedence of an operator determines how it nests with other operators. -All the tokens declared in a single precedence declaration have equal -precedence and nest together according to their associativity. -When two tokens declared in different precedence declarations associate, -the one declared later has the higher precedence and is grouped first. -@end itemize - -For backward compatibility, there is a confusing difference between the -argument lists of @code{%token} and precedence declarations. -Only a @code{%token} can associate a literal string with a token type name. -A precedence declaration always interprets a literal string as a reference to a -separate token. -For example: - -@example -%left OR "<=" // Does not declare an alias. -%left OR 134 "<=" 135 // Declares 134 for OR and 135 for "<=". -@end example - -@node Union Decl -@subsection The Collection of Value Types -@cindex declaring value types -@cindex value types, declaring -@findex %union - -The @code{%union} declaration specifies the entire collection of -possible data types for semantic values. The keyword @code{%union} is -followed by braced code containing the same thing that goes inside a -@code{union} in C@. - -For example: - -@example -@group -%union @{ - double val; - symrec *tptr; -@} -@end group -@end example - -@noindent -This says that the two alternative types are @code{double} and @code{symrec -*}. They are given names @code{val} and @code{tptr}; these names are used -in the @code{%token} and @code{%type} declarations to pick one of the types -for a terminal or nonterminal symbol (@pxref{Type Decl, ,Nonterminal Symbols}). - -As an extension to POSIX, a tag is allowed after the -@code{union}. For example: - -@example -@group -%union value @{ - double val; - symrec *tptr; -@} -@end group -@end example - -@noindent -specifies the union tag @code{value}, so the corresponding C type is -@code{union value}. If you do not specify a tag, it defaults to -@code{YYSTYPE}. - -As another extension to POSIX, you may specify multiple -@code{%union} declarations; their contents are concatenated. However, -only the first @code{%union} declaration can specify a tag. - -Note that, unlike making a @code{union} declaration in C, you need not write -a semicolon after the closing brace. +@itemize @bullet +@item +The associativity of an operator @var{op} determines how repeated uses +of the operator nest: whether @samp{@var{x} @var{op} @var{y} @var{op} +@var{z}} is parsed by grouping @var{x} with @var{y} first or by +grouping @var{y} with @var{z} first. @code{%left} specifies +left-associativity (grouping @var{x} with @var{y} first) and +@code{%right} specifies right-associativity (grouping @var{y} with +@var{z} first). @code{%nonassoc} specifies no associativity, which +means that @samp{@var{x} @var{op} @var{y} @var{op} @var{z}} is +considered a syntax error. -Instead of @code{%union}, you can define and use your own union type -@code{YYSTYPE} if your grammar contains at least one -@samp{<@var{type}>} tag. For example, you can put the following into -a header file @file{parser.h}: +@code{%precedence} gives only precedence to the @var{symbols}, and +defines no associativity at all. Use this to define precedence only, +and leave any potential conflict due to associativity enabled. -@example -@group -union YYSTYPE @{ - double val; - symrec *tptr; -@}; -typedef union YYSTYPE YYSTYPE; -@end group -@end example +@item +The precedence of an operator determines how it nests with other operators. +All the tokens declared in a single precedence declaration have equal +precedence and nest together according to their associativity. +When two tokens declared in different precedence declarations associate, +the one declared later has the higher precedence and is grouped first. +@end itemize -@noindent -and then your grammar can use the following -instead of @code{%union}: +For backward compatibility, there is a confusing difference between the +argument lists of @code{%token} and precedence declarations. +Only a @code{%token} can associate a literal string with a token type name. +A precedence declaration always interprets a literal string as a reference to a +separate token. +For example: @example -@group -%@{ -#include "parser.h" -%@} -%type expr -%token ID -@end group +%left OR "<=" // Does not declare an alias. +%left OR 134 "<=" 135 // Declares 134 for OR and 135 for "<=". @end example @node Type Decl @@ -4604,7 +4899,7 @@ used. This is done with a @code{%type} declaration, like this: @noindent Here @var{nonterminal} is the name of a nonterminal symbol, and @var{type} is the name given in the @code{%union} to the alternative -that you want (@pxref{Union Decl, ,The Collection of Value Types}). You +that you want (@pxref{Union Decl, ,The Union Declaration}). You can give any number of nonterminal symbols in the same @code{%type} declaration, if they have the same value type. Use spaces to separate the symbol names. @@ -4700,10 +4995,8 @@ For example: @example %union @{ char *string; @} -%token STRING1 -%token STRING2 -%type string1 -%type string2 +%token STRING1 STRING2 +%type string1 string2 %union @{ char character; @} %token CHR %type chr @@ -4829,10 +5122,8 @@ For example: @example %union @{ char *string; @} -%token STRING1 -%token STRING2 -%type string1 -%type string2 +%token STRING1 STRING2 +%type string1 string2 %union @{ char character; @} %token CHR %type chr @@ -4963,7 +5254,7 @@ calling convention is used for the lexical analyzer function @code{yylex}. @xref{Pure Calling, ,Calling Conventions for Pure Parsers}, for the details of this. The variable @code{yynerrs} becomes local in @code{yyparse} in pull mode but it becomes a member -of yypstate in push mode. (@pxref{Error Reporting, ,The Error +of @code{yypstate} in push mode. (@pxref{Error Reporting, ,The Error Reporting Function @code{yyerror}}). The convention for calling @code{yyparse} itself is unchanged. @@ -5091,7 +5382,7 @@ Here is a summary of the declarations used to define a grammar: @deffn {Directive} %union Declare the collection of data types that semantic values may have -(@pxref{Union Decl, ,The Collection of Value Types}). +(@pxref{Union Decl, ,The Union Declaration}). @end deffn @deffn {Directive} %token @@ -5219,7 +5510,7 @@ For instance with @samp{%define api.prefix "calc"} and @samp{%defines @end deffn @deffn {Directive} %defines @var{defines-file} -Same as above, but save in the file @var{defines-file}. +Same as above, but save in the file @file{@var{defines-file}}. @end deffn @deffn {Directive} %destructor @@ -5237,8 +5528,6 @@ Specify the programming language for the generated parser. Currently supported languages include C, C++, and Java. @var{language} is case-insensitive. -This directive is experimental and its effect may be modified in future -releases. @end deffn @deffn {Directive} %locations @@ -5284,7 +5573,7 @@ own right. @end deffn @deffn {Directive} %output "@var{file}" -Specify @var{file} for the parser implementation file. +Generate the parser implementation in @file{@var{file}}. @end deffn @deffn {Directive} %pure-parser @@ -5409,12 +5698,10 @@ values, depend on the selected target language and/or the parser skeleton (@pxref{Decl Summary,,%language}, @pxref{Decl Summary,,%skeleton}). Unaccepted @var{variable}s produce an error. -Some of the accepted @var{variable}s are: +Some of the accepted @var{variable}s are described below. -@table @code @c ================================================== api.namespace -@item api.namespace -@findex %define api.namespace +@deffn Directive {%define api.namespace} @{@var{namespace}@} @itemize @item Languages(s): C++ @@ -5422,7 +5709,7 @@ Some of the accepted @var{variable}s are: For example, if you specify: @example -%define api.namespace "foo::bar" +%define api.namespace @{foo::bar@} @end example Bison uses @code{foo::bar} verbatim in references such as: @@ -5455,18 +5742,18 @@ api.namespace} so that @code{%name-prefix} @emph{only} affects the lexical analyzer function. For example, if you specify: @example -%define api.namespace "foo" +%define api.namespace @{foo@} %name-prefix "bar::" @end example The parser namespace is @code{foo} and @code{yylex} is referenced as @code{bar::lex}. @end itemize -@c namespace +@end deffn +@c api.namespace @c ================================================== api.location.type -@item @code{api.location.type} -@findex %define api.location.type +@deffn {Directive} {%define api.location.type} @var{type} @itemize @bullet @item Language(s): C++, Java @@ -5478,12 +5765,14 @@ The parser namespace is @code{foo} and @code{yylex} is referenced as @item Default Value: none -@item History: introduced in Bison 2.7 +@item History: +Introduced in Bison 2.7 for C, C++ and Java. Introduced under the name +@code{location_type} for C++ in Bison 2.5 and for Java in Bison 2.4. @end itemize +@end deffn @c ================================================== api.prefix -@item api.prefix -@findex %define api.prefix +@deffn {Directive} {%define api.prefix} @var{prefix} @itemize @bullet @item Language(s): All @@ -5497,10 +5786,10 @@ The parser namespace is @code{foo} and @code{yylex} is referenced as @item History: introduced in Bison 2.6 @end itemize +@end deffn @c ================================================== api.pure -@item api.pure -@findex %define api.pure +@deffn Directive {%define api.pure} @itemize @bullet @item Language(s): C @@ -5526,8 +5815,8 @@ I.e., if @samp{%locations %define api.pure} is passed then the prototypes for @code{yyerror} are: @example -void yyerror (char const *msg); /* Yacc parsers. */ -void yyerror (YYLTYPE *locp, char const *msg); /* GLR parsers. */ +void yyerror (char const *msg); // Yacc parsers. +void yyerror (YYLTYPE *locp, char const *msg); // GLR parsers. @end example But if @samp{%locations %define api.pure %parse-param @{int *nastiness@}} is @@ -5542,15 +5831,16 @@ Reporting Function @code{yyerror}}) @item Default Value: @code{false} -@item History: the @code{full} value was introduced in Bison 2.7 +@item History: +the @code{full} value was introduced in Bison 2.7 @end itemize +@end deffn @c api.pure @c ================================================== api.push-pull -@item api.push-pull -@findex %define api.push-pull +@deffn Directive {%define api.push-pull} @var{kind} @itemize @bullet @item Language(s): C (deterministic parsers only) @@ -5564,13 +5854,13 @@ More user feedback will help to stabilize it.) @item Default Value: @code{pull} @end itemize +@end deffn @c api.push-pull @c ================================================== api.token.constructor -@item api.token.constructor -@findex %define api.token.constructor +@deffn Directive {%define api.token.constructor} @itemize @bullet @item Language(s): @@ -5589,12 +5879,12 @@ Boolean. @item History: introduced in Bison 2.8 @end itemize +@end deffn @c api.token.constructor @c ================================================== api.token.prefix -@item api.token.prefix -@findex %define api.token.prefix +@deffn Directive {%define api.token.prefix} @var{prefix} @itemize @item Languages(s): all @@ -5616,8 +5906,13 @@ and @code{TOK_ERROR} in the generated source files. In particular, the scanner must use these prefixed token names, while the grammar itself may still use the short names (as in the sample rule given above). The generated informational files (@file{*.output}, @file{*.xml}, -@file{*.dot}) are not modified by this prefix. See @ref{Calc++ Parser} -and @ref{Calc++ Scanner}, for a complete example. +@file{*.dot}) are not modified by this prefix. + +Bison also prefixes the generated member names of the semantic value union. +@xref{Type Generation,, Generating the Semantic Value Type}, for more +details. + +See @ref{Calc++ Parser} and @ref{Calc++ Scanner}, for a complete example. @item Accepted Values: Any string. Should be a valid identifier prefix in the target language, @@ -5629,13 +5924,114 @@ empty @item History: introduced in Bison 2.8 @end itemize +@end deffn @c api.token.prefix +@c ================================================== api.value.type +@deffn Directive {%define api.value.type} @var{type} +@itemize @bullet +@item Language(s): +all + +@item Purpose: +The type for semantic values. + +@item Accepted Values: +@table @asis +@item @code{""} +This grammar has no semantic value at all. This is not properly supported +yet. +@item @code{%union} (C, C++) +The type is defined thanks to the @code{%union} directive. You don't have +to define @code{api.value.type} in that case, using @code{%union} suffices. +@xref{Union Decl, ,The Union Declaration}. +For instance: +@example +%define api.value.type "%union" +%union +@{ + int ival; + char *sval; +@} +%token INT "integer" +%token STR "string" +@end example + +@item @code{union} (C, C++) +The symbols are defined with type names, from which Bison will generate a +@code{union}. For instance: +@example +%define api.value.type "union" +%token INT "integer" +%token STR "string" +@end example +This feature needs user feedback to stabilize. Note that most C++ objects +cannot be stored in a @code{union}. + +@item @code{variant} (C++) +This is similar to @code{union}, but special storage techniques are used to +allow any kind of C++ object to be used. For instance: +@example +%define api.value.type "variant" +%token INT "integer" +%token STR "string" +@end example +This feature needs user feedback to stabilize. +@xref{C++ Variants}. + +@item any other identifier +Use this name as semantic value. +@example +%code requires +@{ + struct my_value + @{ + enum + @{ + is_int, is_str + @} kind; + union + @{ + int ival; + char *sval; + @} u; + @}; +@} +%define api.value.type "struct my_value" +%token INT "integer" +%token STR "string" +@end example +@end table + +@item Default Value: +@itemize @minus +@item +@code{%union} if @code{%union} is used, otherwise @dots{} +@item +@code{int} if type tags are used (i.e., @samp{%token <@var{type}>@dots{}} or +@samp{%token <@var{type}>@dots{}} is used), otherwise @dots{} +@item +@code{""} +@end itemize + +@item History: +introduced in Bison 2.8. Was introduced for Java only in 2.3b as +@code{stype}. +@end itemize +@end deffn +@c api.value.type + + +@c ================================================== location_type +@deffn Directive {%define location_type} +Obsoleted by @code{api.location.type} since Bison 2.7. +@end deffn + + @c ================================================== lr.default-reduction -@item lr.default-reduction -@findex %define lr.default-reduction +@deffn Directive {%define lr.default-reduction} @var{when} @itemize @bullet @item Language(s): all @@ -5655,11 +6051,11 @@ feedback will help to stabilize it.) introduced as @code{lr.default-reduction} in 2.5, renamed as @code{lr.default-reduction} in 2.8. @end itemize +@end deffn @c ============================================ lr.keep-unreachable-state -@item lr.keep-unreachable-state -@findex %define lr.keep-unreachable-state +@deffn Directive {%define lr.keep-unreachable-state} @itemize @bullet @item Language(s): all @@ -5667,16 +6063,17 @@ introduced as @code{lr.default-reduction} in 2.5, renamed as remain in the parser tables. @xref{Unreachable States}. @item Accepted Values: Boolean @item Default Value: @code{false} -@end itemize +@item History: introduced as @code{lr.keep_unreachable_states} in 2.3b, renamed as @code{lr.keep-unreachable-states} in 2.5, and as @code{lr.keep-unreachable-state} in 2.8. +@end itemize +@end deffn @c lr.keep-unreachable-state @c ================================================== lr.type -@item lr.type -@findex %define lr.type +@deffn Directive {%define lr.type} @var{type} @itemize @bullet @item Language(s): all @@ -5689,18 +6086,16 @@ More user feedback will help to stabilize it.) @item Default Value: @code{lalr} @end itemize - +@end deffn @c ================================================== namespace -@item namespace -@findex %define namespace +@deffn Directive %define namespace @{@var{namespace}@} Obsoleted by @code{api.namespace} @c namespace - +@end deffn @c ================================================== parse.assert -@item parse.assert -@findex %define parse.assert +@deffn Directive {%define parse.assert} @itemize @item Languages(s): C++ @@ -5714,12 +6109,12 @@ destroyed properly. This option checks these constraints. @item Default Value: @code{false} @end itemize +@end deffn @c parse.assert @c ================================================== parse.error -@item parse.error -@findex %define parse.error +@deffn Directive {%define parse.error} @itemize @item Languages(s): all @@ -5741,12 +6136,12 @@ However, this report can often be incorrect when LAC is not enabled @item Default Value: @code{simple} @end itemize +@end deffn @c parse.error @c ================================================== parse.lac -@item parse.lac -@findex %define parse.lac +@deffn Directive {%define parse.lac} @itemize @item Languages(s): C (deterministic parsers only) @@ -5756,11 +6151,11 @@ syntax error handling. @xref{LAC}. @item Accepted Values: @code{none}, @code{full} @item Default Value: @code{none} @end itemize +@end deffn @c parse.lac @c ================================================== parse.trace -@item parse.trace -@findex %define parse.trace +@deffn Directive {%define parse.trace} @itemize @item Languages(s): C, C++, Java @@ -5778,30 +6173,9 @@ compiled. @item Default Value: @code{false} @end itemize +@end deffn @c parse.trace -@c ================================================== variant -@item variant -@findex %define variant - -@itemize @bullet -@item Language(s): -C++ - -@item Purpose: -Request variant-based semantic values. -@xref{C++ Variants}. - -@item Accepted Values: -Boolean. - -@item Default Value: -@code{false} -@end itemize -@c variant -@end table - - @node %code Summary @subsection %code Summary @findex %code @@ -5853,10 +6227,11 @@ qualifiers produce an error. Some of the accepted qualifiers are: @item Language(s): C, C++ @item Purpose: This is the best place to write dependency code required for -@code{YYSTYPE} and @code{YYLTYPE}. -In other words, it's the best place to define types referenced in @code{%union} -directives, and it's the best place to override Bison's default @code{YYSTYPE} -and @code{YYLTYPE} definitions. +@code{YYSTYPE} and @code{YYLTYPE}. In other words, it's the best place to +define types referenced in @code{%union} directives. If you use +@code{#define} to override Bison's default @code{YYSTYPE} and @code{YYLTYPE} +definitions, then it is also the best place. However you should rather +@code{%define} @code{api.value.type} and @code{api.location.type}. @item Location(s): The parser header file and the parser implementation file before the Bison-generated @code{YYSTYPE} and @code{YYLTYPE} @@ -5981,7 +6356,7 @@ parsers. To comply with this tradition, when @code{api.prefix} is used, @code{YYDEBUG} (not renamed) is used as a default value: @example -/* Enabling traces. */ +/* Debug traces. */ #ifndef CDEBUG # if defined YYDEBUG # if YYDEBUG @@ -6138,7 +6513,7 @@ function is available if either the @samp{%define api.push-pull push} or @samp{%define api.push-pull both} declaration is used. @xref{Push Decl, ,A Push Parser}. -@deftypefun int yypush_parse (yypstate *yyps) +@deftypefun int yypush_parse (yypstate *@var{yyps}) The value returned by @code{yypush_parse} is the same as for yyparse with the following exception: it returns @code{YYPUSH_MORE} if more input is required to finish parsing the grammar. @@ -6156,7 +6531,7 @@ stream. This function is available if the @samp{%define api.push-pull both} declaration is used. @xref{Push Decl, ,A Push Parser}. -@deftypefun int yypull_parse (yypstate *yyps) +@deftypefun int yypull_parse (yypstate *@var{yyps}) The value returned by @code{yypull_parse} is the same as for @code{yyparse}. @end deftypefun @@ -6191,7 +6566,7 @@ function is available if either the @samp{%define api.push-pull push} or @samp{%define api.push-pull both} declaration is used. @xref{Push Decl, ,A Push Parser}. -@deftypefun void yypstate_delete (yypstate *yyps) +@deftypefun void yypstate_delete (yypstate *@var{yyps}) This function will reclaim the memory associated with a parser instance. After this call, you should no longer attempt to use the parser instance. @end deftypefun @@ -6256,7 +6631,7 @@ yylex (void) return 0; @dots{} if (c == '+' || c == '-') - return c; /* Assume token type for `+' is '+'. */ + return c; /* Assume token type for '+' is '+'. */ @dots{} return INT; /* Return the type of the token. */ @dots{} @@ -6328,7 +6703,7 @@ Thus, if the type is @code{int} (the default), you might write this in When you are using multiple data types, @code{yylval}'s type is a union made from the @code{%union} declaration (@pxref{Union Decl, ,The -Collection of Value Types}). So when you store a token's value, you +Union Declaration}). So when you store a token's value, you must use the proper member of the union. If the @code{%union} declaration looks like this: @@ -6664,7 +7039,6 @@ Actions}). @end deffn @deffn {Value} @@$ -@findex @@$ Acts like a structure variable containing information on the textual location of the grouping made by the current rule. @xref{Tracking Locations}. @@ -6723,7 +7097,7 @@ GNU Automake. @item @cindex bison-i18n.m4 Into the directory containing the GNU Autoconf macros used -by the package---often called @file{m4}---copy the +by the package ---often called @file{m4}--- copy the @file{bison-i18n.m4} file installed by Bison under @samp{share/aclocal/bison-i18n.m4} in Bison's installation directory. For example: @@ -7354,7 +7728,7 @@ of zero or more @code{word} groupings. @example @group sequence: - /* empty */ @{ printf ("empty sequence\n"); @} + %empty @{ printf ("empty sequence\n"); @} | maybeword | sequence word @{ printf ("added word %s\n", $2); @} ; @@ -7362,8 +7736,8 @@ sequence: @group maybeword: - /* empty */ @{ printf ("empty maybeword\n"); @} -| word @{ printf ("single word %s\n", $1); @} + %empty @{ printf ("empty maybeword\n"); @} +| word @{ printf ("single word %s\n", $1); @} ; @end group @end example @@ -7394,7 +7768,7 @@ proper way to define @code{sequence}: @example @group sequence: - /* empty */ @{ printf ("empty sequence\n"); @} + %empty @{ printf ("empty sequence\n"); @} | sequence word @{ printf ("added word %s\n", $2); @} ; @end group @@ -7405,7 +7779,7 @@ Here is another common error that yields a reduce/reduce conflict: @example @group sequence: - /* empty */ + %empty | sequence words | sequence redirects ; @@ -7413,14 +7787,14 @@ sequence: @group words: - /* empty */ + %empty | words word ; @end group @group redirects: - /* empty */ + %empty | redirects redirect ; @end group @@ -7443,7 +7817,7 @@ of sequence: @example sequence: - /* empty */ + %empty | sequence word | sequence redirect ; @@ -7455,7 +7829,7 @@ from being empty: @example @group sequence: - /* empty */ + %empty | sequence words | sequence redirects ; @@ -7499,7 +7873,7 @@ rule: %% @group sequence: - /* empty */ + %empty | sequence word %prec "sequence" | sequence redirect %prec "sequence" ; @@ -7521,7 +7895,7 @@ rule with the same precedence, but make them right-associative: %% @group sequence: - /* empty */ + %empty | sequence word %prec "word" | sequence redirect %prec "redirect" ; @@ -8218,7 +8592,7 @@ For example: @example stmts: - /* empty string */ + %empty | stmts '\n' | stmts exp '\n' | stmts error '\n' @@ -8528,8 +8902,26 @@ clear the flag. Developing a parser can be a challenge, especially if you don't understand the algorithm (@pxref{Algorithm, ,The Bison Parser Algorithm}). This -chapter explains how to generate and read the detailed description of the -automaton, and how to enable and understand the parser run-time traces. +chapter explains how understand and debug a parser. + +The first sections focus on the static part of the parser: its structure. +They explain how to generate and read the detailed description of the +automaton. There are several formats available: +@itemize @minus +@item +as text, see @ref{Understanding, , Understanding Your Parser}; + +@item +as a graph, see @ref{Graphviz,, Visualizing Your Parser}; + +@item +or as a markup report that can be turned, for instance, into HTML, see +@ref{Xml,, Visualizing your parser in multiple formats}. +@end itemize + +The last section focuses on the dynamic part of the parser: how to enable +and understand the parser run-time traces (@pxref{Tracing, ,Tracing Your +Parser}). @menu * Understanding:: Understanding the structure of your parser. @@ -8544,8 +8936,7 @@ automaton, and how to enable and understand the parser run-time traces. As documented elsewhere (@pxref{Algorithm, ,The Bison Parser Algorithm}) Bison parsers are @dfn{shift/reduce automata}. In some cases (much more frequent than one would hope), looking at this automaton is required to -tune or simply fix a parser. Bison provides two different -representation of it, either textually or graphically (as a DOT file). +tune or simply fix a parser. The textual file is generated when the options @option{--report} or @option{--verbose} are specified, see @ref{Invocation, , Invoking @@ -8559,9 +8950,12 @@ The following grammar file, @file{calc.y}, will be used in the sequel: @example %token NUM STR +@group %left '+' '-' %left '*' +@end group %% +@group exp: exp '+' exp | exp '-' exp @@ -8569,6 +8963,7 @@ exp: | exp '/' exp | NUM ; +@end group useless: STR; %% @end example @@ -8578,8 +8973,8 @@ useless: STR; @example calc.y: warning: 1 nonterminal useless in grammar calc.y: warning: 1 rule useless in grammar -calc.y:11.1-7: warning: nonterminal useless in grammar: useless -calc.y:11.10-12: warning: rule useless in grammar: useless: STR +calc.y:12.1-7: warning: nonterminal useless in grammar: useless +calc.y:12.10-12: warning: rule useless in grammar: useless: STR calc.y: conflicts: 7 shift/reduce @end example @@ -8673,7 +9068,7 @@ item is a production rule together with a point (@samp{.}) marking the location of the input cursor. @example -state 0 +State 0 0 $accept: . exp $end @@ -8703,7 +9098,7 @@ you want to see more detail you can invoke @command{bison} with @option{--report=itemset} to list the derived items as well: @example -state 0 +State 0 0 $accept: . exp $end 1 exp: . exp '+' exp @@ -8721,7 +9116,7 @@ state 0 In the state 1@dots{} @example -state 1 +State 1 5 exp: NUM . @@ -8731,11 +9126,11 @@ state 1 @noindent the rule 5, @samp{exp: NUM;}, is completed. Whatever the lookahead token (@samp{$default}), the parser will reduce it. If it was coming from -state 0, then, after this reduction it will return to state 0, and will +State 0, then, after this reduction it will return to state 0, and will jump to state 2 (@samp{exp: go to state 2}). @example -state 2 +State 2 0 $accept: exp . $end 1 exp: exp . '+' exp @@ -8763,7 +9158,7 @@ The state 3 is named the @dfn{final state}, or the @dfn{accepting state}: @example -state 3 +State 3 0 $accept: exp $end . @@ -8778,7 +9173,7 @@ The interpretation of states 4 to 7 is straightforward, and is left to the reader. @example -state 4 +State 4 1 exp: exp '+' . exp @@ -8787,7 +9182,7 @@ state 4 exp go to state 8 -state 5 +State 5 2 exp: exp '-' . exp @@ -8796,7 +9191,7 @@ state 5 exp go to state 9 -state 6 +State 6 3 exp: exp '*' . exp @@ -8805,7 +9200,7 @@ state 6 exp go to state 10 -state 7 +State 7 4 exp: exp '/' . exp @@ -8818,7 +9213,7 @@ As was announced in beginning of the report, @samp{State 8 conflicts: 1 shift/reduce}: @example -state 8 +State 8 1 exp: exp . '+' exp 1 | exp '+' exp . @@ -8861,7 +9256,7 @@ with some set of possible lookahead tokens. When run with @option{--report=lookahead}, Bison specifies these lookahead tokens: @example -state 8 +State 8 1 exp: exp . '+' exp 1 | exp '+' exp . [$end, '+', '-', '/'] @@ -8893,7 +9288,7 @@ The remaining states are similar: @example @group -state 9 +State 9 1 exp: exp . '+' exp 2 | exp . '-' exp @@ -8909,7 +9304,7 @@ state 9 @end group @group -state 10 +State 10 1 exp: exp . '+' exp 2 | exp . '-' exp @@ -8924,7 +9319,7 @@ state 10 @end group @group -state 11 +State 11 1 exp: exp . '+' exp 2 | exp . '-' exp @@ -8947,12 +9342,11 @@ state 11 @noindent Observe that state 11 contains conflicts not only due to the lack of -precedence of @samp{/} with respect to @samp{+}, @samp{-}, and -@samp{*}, but also because the -associativity of @samp{/} is not specified. +precedence of @samp{/} with respect to @samp{+}, @samp{-}, and @samp{*}, but +also because the associativity of @samp{/} is not specified. -Note that Bison may also produce an HTML version of this output, via an XML -file and XSLT processing (@pxref{Xml}). +Bison may also produce an HTML version of this output, via an XML file and +XSLT processing (@pxref{Xml,,Visualizing your parser in multiple formats}). @c ================================================= Graphical Representation @@ -8972,7 +9366,10 @@ This file is generated when the @option{--graph} option is specified (@pxref{Invocation, , Invoking Bison}). Its name is made by removing @samp{.tab.c} or @samp{.c} from the parser implementation file name, and adding @samp{.dot} instead. If the grammar file is @file{foo.y}, the -Graphviz output file is called @file{foo.dot}. +Graphviz output file is called @file{foo.dot}. A DOT file may also be +produced via an XML file and XSLT processing (@pxref{Xml,,Visualizing your +parser in multiple formats}). + The following grammar file, @file{rr.y}, will be used in the sequel: @@ -8985,10 +9382,20 @@ b: "0"; @end group @end example -The graphical output is very similar to the textual one, and as such it is -easier understood by making direct comparisons between them. See -@ref{Debugging, , Debugging Your Parser} for a detailled analysis of the -textual report. +The graphical output +@ifnotinfo +(see @ref{fig:graph}) +@end ifnotinfo +is very similar to the textual one, and as such it is easier understood by +making direct comparisons between them. @xref{Debugging, , Debugging Your +Parser}, for a detailled analysis of the textual report. + +@ifnotinfo +@float Figure,fig:graph +@image{figs/example, 430pt} +@caption{A graphical rendering of the parser.} +@end float +@end ifnotinfo @subheading Graphical Representation of States @@ -9013,7 +9420,7 @@ shift. The following describes a reduction in the @file{rr.output} file: @example @group -state 3 +State 3 1 exp: a . ";" @@ -9034,7 +9441,7 @@ action for the given state, there is no such label. This is how reductions are represented in the verbose file @file{rr.output}: @example -state 1 +State 1 3 a: "0" . [";"] 4 b: "0" . ["."] @@ -9053,17 +9460,14 @@ reduction, see @ref{Shift/Reduce, , Shift/Reduce Conflicts}. Discarded actions are distinguished by a red filling color on these nodes, just like how they are reported between square brackets in the verbose file. -The reduction corresponding to the rule number 0 is the acceptation state. It -is shown as a blue diamond, labelled "Acc". +The reduction corresponding to the rule number 0 is the acceptation +state. It is shown as a blue diamond, labelled ``Acc''. @subheading Graphical representation of go tos The @samp{go to} jump transitions are represented as dotted lines bearing the name of the rule being jumped to. -Note that a DOT file may also be produced via an XML file and XSLT -processing (@pxref{Xml}). - @c ================================================= XML @node Xml @@ -9071,8 +9475,10 @@ processing (@pxref{Xml}). @cindex xml Bison supports two major report formats: textual output -(@pxref{Understanding}) when invoked with option @option{--verbose}, and DOT -(@pxref{Graphviz}) when invoked with option @option{--graph}. However, +(@pxref{Understanding, ,Understanding Your Parser}) when invoked +with option @option{--verbose}, and DOT +(@pxref{Graphviz,, Visualizing Your Parser}) when invoked with +option @option{--graph}. However, another alternative is to output an XML file that may then be, with @command{xsltproc}, rendered as either a raw text format equivalent to the verbose file, or as an HTML version of the same file, with clickable @@ -9080,7 +9486,7 @@ transitions, or even as a DOT. The @file{.output} and DOT files obtained via XSLT have no difference whatsoever with those obtained by invoking @command{bison} with options @option{--verbose} or @option{--graph}. -The textual file is generated when the options @option{-x} or +The XML file is generated when the options @option{-x} or @option{--xml[=FILE]} are specified, see @ref{Invocation,,Invoking Bison}. If not specified, its name is made by removing @samp{.tab.c} or @samp{.c} from the parser implementation file name, and adding @samp{.xml} instead. @@ -9094,19 +9500,19 @@ files to apply to the XML file. Their names are non-ambiguous: @item xml2dot.xsl Used to output a copy of the DOT visualization of the automaton. @item xml2text.xsl -Used to output a copy of the .output file. +Used to output a copy of the @samp{.output} file. @item xml2xhtml.xsl -Used to output an xhtml enhancement of the .output file. +Used to output an xhtml enhancement of the @samp{.output} file. @end table -Sample usage (requires @code{xsltproc}): +Sample usage (requires @command{xsltproc}): @example -$ bison -x input.y +$ bison -x gr.y @group $ bison --print-datadir /usr/local/share/bison @end group -$ xsltproc /usr/local/share/bison/xslt/xml2xhtml.xsl input.xml > input.html +$ xsltproc /usr/local/share/bison/xslt/xml2xhtml.xsl gr.xml >gr.html @end example @c ================================================= Tracing @@ -9240,7 +9646,7 @@ prologue: /* Formatting semantic values. */ %printer @{ fprintf (yyoutput, "%s", $$->name); @} VAR; %printer @{ fprintf (yyoutput, "%s()", $$->name); @} FNCT; -%printer @{ fprintf (yyoutput, "%g", $$); @} ; +%printer @{ fprintf (yyoutput, "%g", $$); @} ; @end example The @code{%define} directive instructs Bison to generate run-time trace @@ -9253,8 +9659,8 @@ ill-named) @code{%verbose} directive. The set of @code{%printer} directives demonstrates how to format the semantic value in the traces. Note that the specification can be done either on the symbol type (e.g., @code{VAR} or @code{FNCT}), or on the type -tag: since @code{} is the type for both @code{NUM} and @code{exp}, this -printer will be used for them. +tag: since @code{} is the type for both @code{NUM} and @code{exp}, +this printer will be used for them. Here is a sample of the information provided by run-time traces. The traces are sent onto standard error. @@ -9304,7 +9710,7 @@ Entering state 24 @noindent The previous reduction demonstrates the @code{%printer} directive for -@code{}: both the token @code{NUM} and the resulting non-terminal +@code{}: both the token @code{NUM} and the resulting nonterminal @code{exp} have @samp{1} as value. @example @@ -9488,7 +9894,7 @@ Here is a list of options that can be used with Bison, alphabetized by short option. It is followed by a cross key alphabetized by long option. -@c Please, keep this ordered as in `bison --help'. +@c Please, keep this ordered as in 'bison --help'. @noindent Operations modes: @table @option @@ -9569,6 +9975,72 @@ no effect on the conflict report. Deprecated constructs whose support will be removed in future versions of Bison. +@item empty-rule +Empty rules without @code{%empty}. @xref{Empty Rules}. Disabled by +default, but enabled by uses of @code{%empty}, unless +@option{-Wno-empty-rule} was specified. + +@item precedence +Useless precedence and associativity directives. Disabled by default. + +Consider for instance the following grammar: + +@example +@group +%nonassoc "=" +%left "+" +%left "*" +%precedence "(" +@end group +%% +@group +stmt: + exp +| "var" "=" exp +; +@end group + +@group +exp: + exp "+" exp +| exp "*" "num" +| "(" exp ")" +| "num" +; +@end group +@end example + +Bison reports: + +@c cannot leave the location and the [-Wprecedence] for lack of +@c width in PDF. +@example +@group +warning: useless precedence and associativity for "=" + %nonassoc "=" + ^^^ +@end group +@group +warning: useless associativity for "*", use %precedence + %left "*" + ^^^ +@end group +@group +warning: useless precedence for "(" + %precedence "(" + ^^^ +@end group +@end example + +One would get the exact same parser with the following directives instead: + +@example +@group +%left "+" +%precedence "*" +@end group +@end example + @item other All warnings not categorized above. These warnings are enabled by default. @@ -9577,9 +10049,11 @@ releases of Bison may move warnings from this category to new, more specific categories. @item all -All the warnings. +All the warnings except @code{yacc}. + @item none Turn off all the warnings. + @item error See @option{-Werror}, below. @end table @@ -9608,6 +10082,70 @@ S/R conflicts as errors. $ bison -Werror=yacc,conflicts-sr input.y $ bison -Werror=yacc,error=conflicts-sr input.y @end example + +@item -f [@var{feature}] +@itemx --feature[=@var{feature}] +Activate miscellaneous @var{feature}. @var{feature} can be one of: +@table @code +@item caret +@itemx diagnostics-show-caret +Show caret errors, in a manner similar to GCC's +@option{-fdiagnostics-show-caret}, or Clang's @option{-fcaret-diagnotics}. The +location provided with the message is used to quote the corresponding line of +the source file, underlining the important part of it with carets (^). Here is +an example, using the following file @file{in.y}: + +@example +%type exp +%% +exp: exp '+' exp @{ $exp = $1 + $2; @}; +@end example + +When invoked with @option{-fcaret} (or nothing), Bison will report: + +@example +@group +in.y:3.20-23: error: ambiguous reference: '$exp' + exp: exp '+' exp @{ $exp = $1 + $2; @}; + ^^^^ +@end group +@group +in.y:3.1-3: refers to: $exp at $$ + exp: exp '+' exp @{ $exp = $1 + $2; @}; + ^^^ +@end group +@group +in.y:3.6-8: refers to: $exp at $1 + exp: exp '+' exp @{ $exp = $1 + $2; @}; + ^^^ +@end group +@group +in.y:3.14-16: refers to: $exp at $3 + exp: exp '+' exp @{ $exp = $1 + $2; @}; + ^^^ +@end group +@group +in.y:3.32-33: error: $2 of 'exp' has no declared type + exp: exp '+' exp @{ $exp = $1 + $2; @}; + ^^ +@end group +@end example + +Whereas, when invoked with @option{-fno-caret}, Bison will only report: + +@example +@group +in.y:3.20-23: error: ambiguous reference: ‘$exp’ +in.y:3.1-3: refers to: $exp at $$ +in.y:3.6-8: refers to: $exp at $1 +in.y:3.14-16: refers to: $exp at $3 +in.y:3.32-33: error: $2 of ‘exp’ has no declared type +@end group +@end example + +This option is activated by default. + +@end table @end table @noindent @@ -9656,9 +10194,6 @@ Specify the programming language for the generated parser, as if Summary}). Currently supported languages include C, C++, and Java. @var{language} is case-insensitive. -This option is experimental and its effect may be modified in future -releases. - @item --locations Pretend that @code{%locations} was specified. @xref{Decl Summary}. @@ -9904,7 +10439,7 @@ approach is provided, based on variants (@pxref{C++ Variants}). @subsubsection C++ Unions The @code{%union} directive works as for C, see @ref{Union Decl, ,The -Collection of Value Types}. In particular it produces a genuine +Union Declaration}. In particular it produces a genuine @code{union}, which have a few specific features in C++. @itemize @minus @item @@ -9925,10 +10460,9 @@ Symbols}. @node C++ Variants @subsubsection C++ Variants -Starting with version 2.6, Bison provides a @emph{variant} based -implementation of semantic values for C++. This alleviates all the -limitations reported in the previous section, and in particular, object -types can be used without pointers. +Bison provides a @emph{variant} based implementation of semantic values for +C++. This alleviates all the limitations reported in the previous section, +and in particular, object types can be used without pointers. To enable variant-based semantic values, set @code{%define} variable @code{variant} (@pxref{%define Summary,, variant}). Once this defined, @@ -10000,14 +10534,6 @@ therefore, since, as far as we know, @code{double} is the most demanding type on all platforms, alignments are enforced for @code{double} whatever types are actually used. This may waste space in some cases. -@item -Our implementation is not conforming with strict aliasing rules. Alias -analysis is a technique used in optimizing compilers to detect when two -pointers are disjoint (they cannot ``meet''). Our implementation breaks -some of the rules that G++ 4.4 uses in its alias analysis, so @emph{strict -alias analysis must be disabled}. Use the option -@option{-fno-strict-aliasing} to compile the generated parser. - @item There might be portability issues we are not aware of. @end itemize @@ -10356,7 +10882,7 @@ or @node Complete Symbols @subsubsection Complete Symbols -If you specified both @code{%define variant} and +If you specified both @code{%define api.value.type variant} and @code{%define api.token.constructor}, the @code{parser} class also defines the class @code{parser::symbol_type} which defines a @emph{complete} symbol, aggregating its type (i.e., the @@ -10620,7 +11146,7 @@ the grammar for. @noindent @findex %define api.token.constructor -@findex %define variant +@findex %define api.value.type variant This example will use genuine C++ objects as semantic values, therefore, we require the variant-based interface. To make sure we properly use it, we enable assertions. To fully benefit from type-safety and more natural @@ -10629,8 +11155,8 @@ definition of ``symbol'', we enable @code{api.token.constructor}. @comment file: calc++-parser.yy @example %define api.token.constructor +%define api.value.type variant %define parse.assert -%define variant @end example @noindent @@ -10760,7 +11286,7 @@ Location Tracking Calculator: @code{ltcalc}}). unit: assignments exp @{ driver.result = $2; @}; assignments: - /* Nothing. */ @{@} + %empty @{@} | assignments assignment @{@}; assignment: @@ -10829,7 +11355,7 @@ Finally, we enable scanner tracing. @comment file: calc++-scanner.ll @example -%option noyywrap nounput batch debug +%option noyywrap nounput batch debug noinput @end example @noindent @@ -11045,11 +11571,11 @@ semantic values' types (class names) should be specified in the By default, the semantic stack is declared to have @code{Object} members, which means that the class types you specify can be of any class. To improve the type safety of the parser, you can declare the common -superclass of all the semantic values using the @samp{%define stype} +superclass of all the semantic values using the @samp{%define api.value.type} directive. For example, after the following declaration: @example -%define stype "ASTNode" +%define api.value.type "ASTNode" @end example @noindent @@ -11275,7 +11801,7 @@ The return type can be changed using @code{%define api.position.type @deftypemethod {Lexer} {Object} getLVal () Return the semantic value of the last token that yylex returned. -The return type can be changed using @samp{%define stype +The return type can be changed using @samp{%define api.value.type "@var{class-name}".} @end deftypemethod @@ -11303,7 +11829,7 @@ Like @code{$@var{n}} but specifies a alternative type @var{typealt}. @defvar $$ The semantic value for the grouping made by the current rule. As a value, this is in the base type (@code{Object} or as specified by -@samp{%define stype}) as in not cast to the declared subtype because +@samp{%define api.value.type}) as in not cast to the declared subtype because casts are not allowed on the left-hand side of Java assignments. Use an explicit Java cast if the correct subtype is needed. @xref{Java Semantic Values}. @@ -11385,7 +11911,7 @@ corresponds to these C macros.}. @item Java lacks unions, so @code{%union} has no effect. Instead, semantic values have a common base type: @code{Object} or as specified by -@samp{%define stype}. Angle brackets on @code{%token}, @code{type}, +@samp{%define api.value.type}. Angle brackets on @code{%token}, @code{type}, @code{$@var{n}} and @code{$$} specify subtypes rather than fields of an union. The type of @code{$$}, even with angle brackets, is the base type since Java casts are not allow on the left-hand side of assignments. @@ -11561,7 +12087,7 @@ Whether the parser class is declared @code{public}. Default is false. @xref{Java Bison Interface}. @end deffn -@deffn {Directive} {%define stype} "@var{class}" +@deffn {Directive} {%define api.value.type} "@var{class}" The base type of semantic values. Default is @code{Object}. @xref{Java Semantic Values}. @end deffn @@ -11935,7 +12461,7 @@ operating system's name and version and your compiler's name and version. If you have trouble compiling, you should also include a transcript of the build session, starting with the invocation of `configure'. Depending on the nature of the bug, you may be asked to -send additional files as well (such as `config.h' or `config.cache'). +send additional files as well (such as @file{config.h} or @file{config.cache}). Patches are most welcome, but not required. That is, do not hesitate to send a bug report just because you cannot provide a fix. @@ -11995,18 +12521,23 @@ In an action, the location of the left-hand side of the rule. @end deffn @deffn {Variable} @@@var{n} +@deffnx {Symbol} @@@var{n} In an action, the location of the @var{n}-th symbol of the right-hand side of the rule. @xref{Tracking Locations}. + +In a grammar, the Bison-generated nonterminal symbol for a mid-rule action +with a semantical value. @xref{Mid-Rule Action Translation}. @end deffn @deffn {Variable} @@@var{name} -In an action, the location of a symbol addressed by name. @xref{Tracking -Locations}. +@deffnx {Variable} @@[@var{name}] +In an action, the location of a symbol addressed by @var{name}. +@xref{Tracking Locations}. @end deffn -@deffn {Variable} @@[@var{name}] -In an action, the location of a symbol addressed by name. @xref{Tracking -Locations}. +@deffn {Symbol} $@@@var{n} +In a grammar, the Bison-generated nonterminal symbol for a mid-rule action +with no semantical value. @xref{Mid-Rule Action Translation}. @end deffn @deffn {Variable} $$ @@ -12020,12 +12551,8 @@ right-hand side of the rule. @xref{Actions}. @end deffn @deffn {Variable} $@var{name} -In an action, the semantic value of a symbol addressed by name. -@xref{Actions}. -@end deffn - -@deffn {Variable} $[@var{name}] -In an action, the semantic value of a symbol addressed by name. +@deffnx {Variable} $[@var{name}] +In an action, the semantic value of a symbol addressed by @var{name}. @xref{Actions}. @end deffn @@ -12056,8 +12583,9 @@ More user feedback will help to determine whether it should become a permanent feature. @end deffn -@deffn {Construct} /*@dots{}*/ -Comment delimiters, as in C. +@deffn {Construct} /* @dots{} */ +@deffnx {Construct} // @dots{} +Comments, as in C/C++. @end deffn @deffn {Delimiter} : @@ -12148,6 +12676,11 @@ time to resolve reduce/reduce conflicts. @xref{GLR Parsers, ,Writing GLR Parsers}. @end deffn +@deffn {Directive} %empty +Bison declaration to declare make explicit that a rule has an empty +right-hand side. @xref{Empty Rules}. +@end deffn + @deffn {Symbol} $end The predefined token marking the end of the token stream. It cannot be used in the grammar. @@ -12318,7 +12851,7 @@ The predefined token onto which all undefined values returned by @deffn {Directive} %union Bison declaration to specify several possible data types for semantic -values. @xref{Union Decl, ,The Collection of Value Types}. +values. @xref{Union Decl, ,The Union Declaration}. @end deffn @deffn {Macro} YYABORT @@ -12414,13 +12947,6 @@ the next token. @xref{Lexical, ,The Lexical Analyzer Function @code{yylex}}. @end deffn -@deffn {Macro} YYLEX_PARAM -An obsolete macro for specifying an extra argument (or list of extra -arguments) for @code{yyparse} to pass to @code{yylex}. The use of this -macro is deprecated, and is supported only for Yacc like parsers. -@xref{Pure Calling,, Calling Conventions for Pure Parsers}. -@end deffn - @deffn {Variable} yylloc External variable in which @code{yylex} should place the line and column numbers associated with a token. (In a pure parser, it is a local @@ -12456,7 +12982,7 @@ Management}. @deffn {Variable} yynerrs Global variable which Bison increments each time it reports a syntax error. (In a pure parser, it is a local variable within @code{yyparse}. In a -pure push parser, it is a member of yypstate.) +pure push parser, it is a member of @code{yypstate}.) @xref{Error Reporting, ,The Error Reporting Function @code{yyerror}}. @end deffn @@ -12530,6 +13056,7 @@ require some expertise in low-level implementation details. @end deffn @deffn {Type} YYSTYPE +Deprecated in favor of the @code{%define} variable @code{api.value.type}. Data type of semantic values; @code{int} by default. @xref{Value Type, ,Data Types of Semantic Values}. @end deffn @@ -12542,7 +13069,7 @@ Data type of semantic values; @code{int} by default. @item Accepting state A state whose only action is the accept action. The accepting state is thus a consistent state. -@xref{Understanding,,}. +@xref{Understanding, ,Understanding Your Parser}. @item Backus-Naur Form (BNF; also called ``Backus Normal Form'') Formal method of specifying context-free grammars originally proposed