X-Git-Url: https://git.saurik.com/bison.git/blobdiff_plain/93dd49ab29d96605ced5b23162ee772438637164..464c692789eba089bb21ebd3983ebeaa4a8d3312:/doc/bison.texinfo?ds=sidebyside diff --git a/doc/bison.texinfo b/doc/bison.texinfo index 1deeb365..8cabdb63 100644 --- a/doc/bison.texinfo +++ b/doc/bison.texinfo @@ -3102,13 +3102,13 @@ When @code{YYLTYPE} is not defined, Bison uses a default structure type with four members: @example -struct +typedef struct YYLTYPE @{ int first_line; int first_column; int last_line; int last_column; -@} +@} YYLTYPE; @end example @node Actions and Locations @@ -3186,17 +3186,23 @@ Actually, actions are not the best place to compute locations. Since locations are much more general than semantic values, there is room in the output parser to redefine the default action to take for each rule. The @code{YYLLOC_DEFAULT} macro is invoked each time a rule is -matched, before the associated action is run. +matched, before the associated action is run. It is also invoked +while processing a syntax error, to compute the error's location. Most of the time, this macro is general enough to suppress location dedicated code from semantic actions. The @code{YYLLOC_DEFAULT} macro takes three parameters. The first one is -the location of the grouping (the result of the computation). The second one -is an array holding locations of all right hand side elements of the rule -being matched. The last one is the size of the right hand side rule. +the location of the grouping (the result of the computation). When a +rule is matched, the second parameter is an array holding locations of +all right hand side elements of the rule being matched, and the third +parameter is the size of the rule's right hand side. When processing +a syntax error, the second parameter is an array holding locations of +the symbols that were discarded during error processing, and the third +parameter is the number of discarded symbols. -By default, it is defined this way for simple @acronym{LALR}(1) parsers: +By default, @code{YYLLOC_DEFAULT} is defined this way for simple +@acronym{LALR}(1) parsers: @example @group @@ -3417,7 +3423,23 @@ This says that the two alternative types are @code{double} and @code{symrec 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}). -Note that, unlike making a @code{union} declaration in C, you do not write +As an extension to @acronym{POSIX}, a tag is allowed after the +@code{union}. For example: + +@example +@group +%union value @{ + double val; + symrec *tptr; +@} +@end group +@end example + +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}. + +Note that, unlike making a @code{union} declaration in C, you need not write a semicolon after the closing brace. @node Type Decl @@ -3475,7 +3497,7 @@ should use @code{$$} to designate the semantic value associated to the (@pxref{Parser Function, , The Parser Function @code{yyparse}}). @strong{Warning:} as of Bison 1.875, this feature is still considered as -experimental, as there was not enough users feedback. In particular, +experimental, as there was not enough user feedback. In particular, the syntax might still change. @end deffn @@ -3753,7 +3775,8 @@ Request a pure (reentrant) parser program (@pxref{Pure Decl, ,A Pure Generate an array of token names in the parser file. The name of the array is @code{yytname}; @code{yytname[@var{i}]} is the name of the token whose internal Bison token code number is @var{i}. The first -three elements of @code{yytname} are always @code{"$end"}, +three elements of @code{yytname} correspond to the predefined tokens +@code{"$end"}, @code{"error"}, and @code{"$undefined"}; after these come the symbols defined in the grammar file. @@ -3879,6 +3902,12 @@ Return immediately with value 0 (to report success). Return immediately with value 1 (to report failure). @end defmac +@c For now, do not document %lex-param and %parse-param, since it's +@c not clear that the current behavior is stable enough. For example, +@c we may need to add %error-param. +@clear documentparam + +@ifset documentparam If you use a reentrant parser, you can optionally pass additional parameter information to it in a reentrant way. To do so, use the declaration @code{%parse-param}: @@ -3886,8 +3915,8 @@ declaration @code{%parse-param}: @deffn {Directive} %parse-param @{@var{argument-declaration}@} @findex %parse-param Declare that an argument declared by @code{argument-declaration} is an -additional @code{yyparse} argument. This argument is also passed to -@code{yyerror}. The @var{argument-declaration} is used when declaring +additional @code{yyparse} argument. +The @var{argument-declaration} is used when declaring functions or prototypes. The last identifier in @var{argument-declaration} must be the argument name. @end deffn @@ -3917,6 +3946,7 @@ In the grammar actions, use expressions like this to refer to the data: @example exp: @dots{} @{ @dots{}; *randomness += 1; @dots{} @} @end example +@end ifset @node Lexical @@ -4123,6 +4153,7 @@ this case, omit the second argument; @code{yylex} will be called with only one argument. +@ifset documentparam If you wish to pass the additional parameter data to @code{yylex}, use @code{%lex-param} just like @code{%parse-param} (@pxref{Parser Function}). @@ -4163,6 +4194,7 @@ and finally, if both @code{%pure-parser} and @code{%locations} are used: int yylex (YYSTYPE *lvalp, YYLTYPE *llocp, int *nastiness); int yyparse (int *nastiness, int *randomness); @end example +@end ifset @node Error Reporting @section The Error Reporting Function @code{yyerror} @@ -4227,11 +4259,12 @@ void yyerror (char const *msg); /* Yacc parsers. */ void yyerror (YYLTYPE *locp, char const *msg); /* GLR parsers. */ @end example +@ifset documentparam If @samp{%parse-param @{int *nastiness@}} is used, then: @example -void yyerror (int *randomness, char const *msg); /* Yacc parsers. */ -void yyerror (int *randomness, char const *msg); /* GLR parsers. */ +void yyerror (int *nastiness, char const *msg); /* Yacc parsers. */ +void yyerror (int *nastiness, char const *msg); /* GLR parsers. */ @end example Finally, GLR and Yacc parsers share the same @code{yyerror} calling @@ -4260,6 +4293,7 @@ void yyerror (YYLTYPE *locp, int *nastiness, int *randomness, char const *msg); @end example +@end ifset @noindent The prototypes are only indications of how the code produced by Bison @@ -5575,8 +5609,8 @@ useless: STR; @example calc.y: warning: 1 useless nonterminal and 1 useless rule calc.y:11.1-7: warning: useless nonterminal: useless -calc.y:11.8-12: warning: useless rule: useless: STR -calc.y contains 7 shift/reduce conflicts. +calc.y:11.10-12: warning: useless rule: useless: STR +calc.y: conflicts: 7 shift/reduce @end example When given @option{--report=state}, in addition to @file{calc.tab.c}, it @@ -5598,10 +5632,10 @@ Conflict in state 8 between rule 2 and token '*' resolved as shift. The next section lists states that still have conflicts. @example -State 8 contains 1 shift/reduce conflict. -State 9 contains 1 shift/reduce conflict. -State 10 contains 1 shift/reduce conflict. -State 11 contains 4 shift/reduce conflicts. +State 8 conflicts: 1 shift/reduce +State 9 conflicts: 1 shift/reduce +State 10 conflicts: 1 shift/reduce +State 11 conflicts: 4 shift/reduce @end example @noindent @@ -5813,8 +5847,8 @@ state 7 exp go to state 11 @end example -As was announced in beginning of the report, @samp{State 8 contains 1 -shift/reduce conflict}: +As was announced in beginning of the report, @samp{State 8 conflicts: +1 shift/reduce}: @example state 8 @@ -6082,6 +6116,10 @@ bison -d -o @var{output.c++} @var{infile.y} @noindent will produce @file{output.c++} and @file{outfile.h++}. +For compatibility with @acronym{POSIX}, the standard Bison +distribution also contains a shell script called @command{yacc} that +invokes Bison with the @option{-y} option. + @menu * Bison Options:: All the options described in detail, in alphabetical order by short options. @@ -6122,10 +6160,12 @@ Equivalent to @samp{-o y.tab.c}; the parser output file is called @file{y.tab.c}, and the other outputs are called @file{y.output} and @file{y.tab.h}. The purpose of this option is to imitate Yacc's output file name conventions. Thus, the following shell script can substitute -for Yacc: +for Yacc, and the Bison distribution contains such a script for +compatibility with @acronym{POSIX}: @example -bison -y $* +#! /bin/sh +bison -y "$@" @end example @end table @@ -6415,8 +6455,8 @@ Macro to pretend that a syntax error has just been detected: call @end deffn @deffn {Macro} YYERROR_VERBOSE -An obsolete macro that you define with @code{#define} in the Bison -declarations section to request verbose, specific error message strings +An obsolete macro that you define with @code{#define} in the prologue +to request verbose, specific error message strings when @code{yyerror} is called. It doesn't matter what definition you use for @code{YYERROR_VERBOSE}, just whether you define it. Using @code{%error-verbose} is preferred. @@ -6434,15 +6474,11 @@ macro is deprecated, and is supported only for Yacc like parsers. @xref{Pure Calling,, Calling Conventions for Pure Parsers}. @end deffn -@deffn {Macro} YYLTYPE -Macro for the data type of @code{yylloc}; a structure with four +@deffn {Type} YYLTYPE +Data type of @code{yylloc}; by default, a structure with four members. @xref{Location Type, , Data Types of Locations}. @end deffn -@deffn {Type} yyltype -Default value for YYLTYPE. -@end deffn - @deffn {Macro} YYMAXDEPTH Macro for specifying the maximum size of the parser stack. @xref{Stack Overflow}. @@ -6467,8 +6503,8 @@ grow its internal stacks. Do @emph{not} define @code{YYSTACK_USE_ALLOCA} to anything else. @end deffn -@deffn {Macro} YYSTYPE -Macro for the data type of semantic values; @code{int} by default. +@deffn {Type} YYSTYPE +Data type of semantic values; @code{int} by default. @xref{Value Type, ,Data Types of Semantic Values}. @end deffn @@ -6574,11 +6610,13 @@ Bison declaration to assign left associativity to token(s). @xref{Precedence Decl, ,Operator Precedence}. @end deffn +@ifset documentparam @deffn {Directive} %lex-param @{@var{argument-declaration}@} Bison declaration to specifying an additional parameter that @code{yylex} should accept. @xref{Pure Calling,, Calling Conventions for Pure Parsers}. @end deffn +@end ifset @deffn {Directive} %merge Bison declaration to assign a merging function to a rule. If there is a @@ -6606,11 +6644,13 @@ Bison declaration to set the name of the parser file. @xref{Decl Summary}. @end deffn +@ifset documentparam @deffn {Directive} %parse-param @{@var{argument-declaration}@} Bison declaration to specifying an additional parameter that @code{yyparse} should accept. @xref{Parser Function,, The Parser Function @code{yyparse}}. @end deffn +@end ifset @deffn {Directive} %prec Bison declaration to assign a precedence to a specific rule.