X-Git-Url: https://git.saurik.com/bison.git/blobdiff_plain/38a92d500a6c26a97e90256726241255f6f09d0a..231897ad21e478b0b0821636aa49fe49ca0f3301:/doc/bison.texinfo diff --git a/doc/bison.texinfo b/doc/bison.texinfo index aa6f9ee8..3ed6b7f5 100644 --- a/doc/bison.texinfo +++ b/doc/bison.texinfo @@ -39,8 +39,8 @@ This manual is for @acronym{GNU} Bison (version @value{VERSION}, @value{UPDATED}), the @acronym{GNU} parser generator. -Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1995, 1998, -1999, 2000, 2001, 2002 Free Software Foundation, Inc. +Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1995, 1998, 2003, +1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -119,7 +119,8 @@ Reference sections: * Copying This Manual:: License for copying this manual. * Index:: Cross-references to the text. -@detailmenu --- The Detailed Node Listing --- +@detailmenu + --- The Detailed Node Listing --- The Concepts of Bison @@ -130,6 +131,8 @@ The Concepts of Bison a semantic value (the value of an integer, the name of an identifier, etc.). * Semantic Actions:: Each rule can have an action containing C code. +* GLR Parsers:: Writing parsers for general context-free languages +* Locations Overview:: Tracking Locations. * Bison Parser:: What are Bison's input and output, how is the output used? * Stages:: Stages in writing and running Bison grammars. @@ -143,8 +146,8 @@ Examples Operator precedence is introduced. * Simple Error Recovery:: Continuing after syntax errors. * Location Tracking Calc:: Demonstrating the use of @@@var{n} and @@$. -* Multi-function Calc:: Calculator with memory and trig functions. - It uses multiple data-types for semantic values. +* Multi-function Calc:: Calculator with memory and trig functions. + It uses multiple data-types for semantic values. * Exercises:: Ideas for improving the multi-function calculator. Reverse Polish Notation Calculator @@ -182,15 +185,16 @@ Bison Grammar Files * Rules:: How to write grammar rules. * Recursion:: Writing recursive rules. * Semantics:: Semantic values and actions. +* Locations:: Locations and actions. * Declarations:: All kinds of Bison declarations are described here. * Multiple Parsers:: Putting more than one Bison parser in one program. Outline of a Bison Grammar -* Prologue:: Syntax and usage of the prologue (declarations section). +* Prologue:: Syntax and usage of the prologue. * Bison Declarations:: Syntax and usage of the Bison declarations section. * Grammar Rules:: Syntax and usage of the grammar rules section. -* Epilogue:: Syntax and usage of the epilogue (additional code section). +* Epilogue:: Syntax and usage of the epilogue. Defining Language Semantics @@ -202,6 +206,12 @@ Defining Language Semantics This says when, why and how to use the exceptional action in the middle of a rule. +Tracking Locations + +* Location Type:: Specifying a data type for locations. +* Actions and Locations:: Using locations in actions. +* Location Default Action:: Defining a general way to compute locations. + Bison Declarations * Token Decl:: Declaring terminal symbols. @@ -227,9 +237,9 @@ The Lexical Analyzer Function @code{yylex} * Calling Convention:: How @code{yyparse} calls @code{yylex}. * Token Values:: How @code{yylex} must return the semantic value of the token it has read. -* Token Positions:: How @code{yylex} must return the text position +* Token Locations:: How @code{yylex} must return the text location (line number, etc.) of the token, if the - actions want that. + actions want that. * Pure Calling:: How the calling convention differs in a pure parser (@pxref{Pure Decl, ,A Pure (Reentrant) Parser}). @@ -259,7 +269,7 @@ Handling Context Dependencies * Tie-in Recovery:: Lexical tie-ins have implications for how error recovery rules must be written. -Understanding or Debugging Your Parser +Debugging Your Parser * Understanding:: Understanding the structure of your parser. * Tracing:: Tracing the execution of your parser. @@ -269,10 +279,13 @@ Invoking Bison * Bison Options:: All the options described in detail, in alphabetical order by short options. * Option Cross Key:: Alphabetical list of long options. +* Yacc Library:: Yacc-compatible @code{yylex} and @code{main}. Frequently Asked Questions * Parser Stack Overflow:: Breaking the Stack Limits +* How Can I Reset @code{yyparse}:: @code{yyparse} Keeps some State +* Strings are Destroyed:: @code{yylval} Loses Track of Strings Copying This Manual @@ -844,12 +857,12 @@ will suffice. Otherwise, we suggest @node Locations Overview @section Locations @cindex location -@cindex textual position -@cindex position, textual +@cindex textual location +@cindex location, textual Many applications, like interpreters or compilers, have to produce verbose and useful error messages. To achieve this, one must be able to keep track of -the @dfn{textual position}, or @dfn{location}, of each syntactic construct. +the @dfn{textual location}, or @dfn{location}, of each syntactic construct. Bison provides a mechanism for handling these locations. Each token has a semantic value. In a similar fashion, each token has an @@ -3060,8 +3073,8 @@ actually does to implement mid-rule actions. @node Locations @section Tracking Locations @cindex location -@cindex textual position -@cindex position, textual +@cindex textual location +@cindex location, textual Though grammar rules and semantic actions are enough to write a fully functional parser, it can be useful to process some additional information, @@ -3091,13 +3104,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 @@ -3175,17 +3188,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 @@ -3406,7 +3425,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 @@ -3464,7 +3499,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 @@ -3525,7 +3560,7 @@ The declaration looks like this: Here @var{n} is a decimal integer. The declaration says there should be no warning if there are @var{n} shift/reduce conflicts and no -reduce/reduce conflicts. An error, instead of the usual warning, is +reduce/reduce conflicts. The usual warning is given if there are either more or fewer conflicts, or if there are any reduce/reduce conflicts. @@ -3547,9 +3582,9 @@ Add an @code{%expect} declaration, copying the number @var{n} from the number which Bison printed. @end itemize -Now Bison will stop annoying you about the conflicts you have checked, but -it will warn you again if changes in the grammar result in additional -conflicts. +Now Bison will stop annoying you if you do not change the number of +conflicts, but it will warn you again if changes in the grammar result +in more or fewer conflicts. @node Start Decl @subsection The Start-Symbol @@ -3742,7 +3777,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. @@ -3875,8 +3911,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 @@ -3930,7 +3966,7 @@ that need it. @xref{Invocation, ,Invoking Bison}. * Calling Convention:: How @code{yyparse} calls @code{yylex}. * Token Values:: How @code{yylex} must return the semantic value of the token it has read. -* Token Positions:: How @code{yylex} must return the text position +* Token Locations:: How @code{yylex} must return the text location (line number, etc.) of the token, if the actions want that. * Pure Calling:: How the calling convention differs @@ -4063,8 +4099,8 @@ then the code in @code{yylex} might look like this: @end group @end example -@node Token Positions -@subsection Textual Positions of Tokens +@node Token Locations +@subsection Textual Locations of Tokens @vindex yylloc If you are using the @samp{@@@var{n}}-feature (@pxref{Locations, , @@ -4107,7 +4143,7 @@ yylex (YYSTYPE *lvalp, YYLTYPE *llocp) @end example If the grammar file does not use the @samp{@@} constructs to refer to -textual positions, then the type @code{YYLTYPE} will not be defined. In +textual locations, then the type @code{YYLTYPE} will not be defined. In this case, omit the second argument; @code{yylex} will be called with only one argument. @@ -4219,8 +4255,8 @@ void yyerror (YYLTYPE *locp, char const *msg); /* GLR parsers. */ 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 @@ -4365,7 +4401,7 @@ errors. This is useful primarily in error rules. @deffn {Value} @@$ @findex @@$ -Acts like a structure variable containing information on the textual position +Acts like a structure variable containing information on the textual location of the grouping made by the current rule. @xref{Locations, , Tracking Locations}. @@ -4391,7 +4427,7 @@ Tracking Locations}. @deffn {Value} @@@var{n} @findex @@@var{n} -Acts like a structure variable containing information on the textual position +Acts like a structure variable containing information on the textual location of the @var{n}th component of the current rule. @xref{Locations, , Tracking Locations}. @end deffn @@ -5137,6 +5173,13 @@ structure should generally be adequate. On @acronym{LALR}(1) portions of a grammar, in particular, it is only slightly slower than with the default Bison parser. +For a more detailed exposition of GLR parsers, please see: Elizabeth +Scott, Adrian Johnstone and Shamsa Sadaf Hussain, Tomita-Style +Generalised @acronym{LR} Parsers, Royal Holloway, University of +London, Department of Computer Science, TR-00-12, +@uref{http://www.cs.rhul.ac.uk/research/languages/publications/tomita_style_1.ps}, +(2000-12-24). + @node Stack Overflow @section Stack Overflow, and How to Avoid It @cindex stack overflow @@ -5564,8 +5607,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 @@ -5587,10 +5630,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 @@ -5802,8 +5845,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 @@ -6071,10 +6114,15 @@ 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. * Option Cross Key:: Alphabetical list of long options. +* Yacc Library:: Yacc-compatible @code{yylex} and @code{main}. @end menu @node Bison Options @@ -6110,10 +6158,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 @@ -6266,6 +6316,32 @@ the corresponding short option. @end example @end ifinfo +@node Yacc Library +@section Yacc Library + +The Yacc library contains default implementations of the +@code{yyerror} and @code{main} functions. These default +implementations are normally not useful, but @acronym{POSIX} requires +them. To use the Yacc library, link your program with the +@option{-ly} option. Note that Bison's implementation of the Yacc +library is distributed under the terms of the @acronym{GNU} General +Public License (@pxref{Copying}). + +If you use the Yacc library's @code{yyerror} function, you should +declare @code{yyerror} as follows: + +@example +int yyerror (char const *); +@end example + +Bison ignores the @code{int} value returned by this @code{yyerror}. +If you use the Yacc library's @code{main} function, your +@code{yyparse} function should have the following type signature: + +@example +int yyparse (void); +@end example + @c ================================================= Invoking Bison @node FAQ @@ -6278,6 +6354,8 @@ are addressed. @menu * Parser Stack Overflow:: Breaking the Stack Limits +* How Can I Reset @code{yyparse}:: @code{yyparse} Keeps some State +* Strings are Destroyed:: @code{yylval} Loses Track of Strings @end menu @node Parser Stack Overflow @@ -6291,6 +6369,148 @@ message. What can I do? This question is already addressed elsewhere, @xref{Recursion, ,Recursive Rules}. +@node How Can I Reset @code{yyparse} +@section How Can I Reset @code{yyparse} + +The following phenomenon gives raise to several incarnations, +resulting in the following typical questions: + +@display +I invoke @code{yyparse} several times, and on correct input it works +properly; but when a parse error is found, all the other calls fail +too. How can I reset @code{yyparse}'s error flag? +@end display + +@noindent +or + +@display +My parser includes support for a @samp{#include} like feature, in +which case I run @code{yyparse} from @code{yyparse}. This fails +although I did specify I needed a @code{%pure-parser}. +@end display + +These problems are not related to Bison itself, but with the Lex +generated scanners. Because these scanners use large buffers for +speed, they might not notice a change of input file. As a +demonstration, consider the following source file, +@file{first-line.l}: + +@verbatim +%{ +#include +#include +%} +%% +.*\n ECHO; return 1; +%% +int +yyparse (const char *file) +{ + yyin = fopen (file, "r"); + if (!yyin) + exit (2); + /* One token only. */ + yylex (); + if (!fclose (yyin)) + exit (3); + return 0; +} + +int +main () +{ + yyparse ("input"); + yyparse ("input"); + return 0; +} +@end verbatim + +@noindent +If the file @file{input} contains + +@verbatim +input:1: Hello, +input:2: World! +@end verbatim + +@noindent +then instead of getting twice the first line, you get: + +@example +$ @kbd{flex -ofirst-line.c first-line.l} +$ @kbd{gcc -ofirst-line first-line.c -ll} +$ @kbd{./first-line} +input:1: Hello, +input:2: World! +@end example + +Therefore, whenever you change @code{yyin}, you must tell the Lex +generated scanner to discard its current buffer, and to switch to the +new one. This depends upon your implementation of Lex, see its +documentation for more. For instance, in the case of Flex, a simple +call @samp{yyrestart (yyin)} suffices after each change to +@code{yyin}. + +@node Strings are Destroyed +@section Strings are Destroyed + +@display +My parser seems to destroy old strings, or maybe it losses track of +them. Instead of reporting @samp{"foo", "bar"}, it reports +@samp{"bar", "bar"}, or even @samp{"foo\nbar", "bar"}. +@end display + +This error is probably the single most frequent ``bug report'' sent to +Bison lists, but is only concerned with a misunderstanding of the role +of scanner. Consider the following Lex code: + +@verbatim +%{ +#include +char *yylval = NULL; +%} +%% +.* yylval = yytext; return 1; +\n /* IGNORE */ +%% +int +main () +{ + /* Similar to using $1, $2 in a Bison action. */ + char *fst = (yylex (), yylval); + char *snd = (yylex (), yylval); + printf ("\"%s\", \"%s\"\n", fst, snd); + return 0; +} +@end verbatim + +If you compile and run this code, you get: + +@example +$ @kbd{flex -osplit-lines.c split-lines.l} +$ @kbd{gcc -osplit-lines split-lines.c -ll} +$ @kbd{printf 'one\ntwo\n' | ./split-lines} +"one +two", "two" +@end example + +@noindent +this is because @code{yytext} is a buffer provided for @emph{reading} +in the action, but if you want to keep it, you have to duplicate it +(e.g., using @code{strdup}). Note that the output may depend on how +your implementation of Lex handles @code{yytext}. For instance, when +given the Lex compatibility option @option{-l} (which triggers the +option @samp{%array}) Flex generates a different behavior: + +@example +$ @kbd{flex -l -osplit-lines.c split-lines.l} +$ @kbd{gcc -osplit-lines split-lines.c -ll} +$ @kbd{printf 'one\ntwo\n' | ./split-lines} +"two", "two" +@end example + + @c ================================================= Table of Symbols @node Table of Symbols @@ -6377,8 +6597,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. @@ -6396,15 +6616,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}. @@ -6429,8 +6645,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 @@ -6481,8 +6697,8 @@ 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 variable within @code{yyparse}, and its address is passed to @code{yylex}.) You can ignore this variable if you don't use the -@samp{@@} feature in the grammar actions. @xref{Token Positions, -,Textual Positions of Tokens}. +@samp{@@} feature in the grammar actions. @xref{Token Locations, +,Textual Locations of Tokens}. @end deffn @deffn {Variable} yynerrs