X-Git-Url: https://git.saurik.com/bison.git/blobdiff_plain/a06ea4aa98143a6ad9ff5c4bcd9189aee44d8eaf..eda429346ae70445be1cffbe729c63fca7848ad6:/doc/bison.texinfo diff --git a/doc/bison.texinfo b/doc/bison.texinfo index 22abaada..8f35ac60 100644 --- a/doc/bison.texinfo +++ b/doc/bison.texinfo @@ -16,6 +16,10 @@ @c @clear shorttitlepage-enabled @c @set shorttitlepage-enabled +@c Set following if you want to document %default-prec and %no-default-prec. +@c This feature is experimental and may change in future Bison versions. +@c @set defaultprec + @c ISPELL CHECK: done, 14 Jan 1993 --bob @c Check COPYRIGHT dates. should be updated in the titlepage, ifinfo @@ -284,7 +288,7 @@ Invoking Bison Frequently Asked Questions * Parser Stack Overflow:: Breaking the Stack Limits -* How Can I Reset @code{yyparse}:: @code{yyparse} Keeps some State +* How Can I Reset the Parser:: @code{yyparse} Keeps some State * Strings are Destroyed:: @code{yylval} Loses Track of Strings * C++ Parsers:: Compiling Parsers with C++ Compilers * Implementing Loops:: Control Flow in the Calculator @@ -352,7 +356,7 @@ encourage people to make other software free. So we decided to make the practical conditions for using Bison match the practical conditions for using the other @acronym{GNU} tools. -This exception applies only when Bison is generating C code for a +This exception applies only when Bison is generating C code for an @acronym{LALR}(1) parser; otherwise, the @acronym{GPL} terms operate as usual. You can tell whether the exception applies to your @samp{.c} output file by @@ -1415,7 +1419,7 @@ here is the definition we will use: void yyerror (char const *s) @{ - printf ("%s\n", s); + fprintf (stderr, "%s\n", s); @} @end group @end example @@ -2477,7 +2481,8 @@ does not enforce this convention, but if you depart from it, people who read your program will be confused. All the escape sequences used in string literals in C can be used in -Bison as well. However, unlike Standard C, trigraphs have no special +Bison as well, except that you must not use a null character within a +string literal. Also, unlike Standard C, trigraphs have no special meaning in Bison string literals, nor is backslash-newline allowed. A literal string token must contain two or more characters; for a token containing just one character, use a character token (see above). @@ -2797,9 +2802,10 @@ Actions, ,Actions in Mid-Rule}). The C code in an action can refer to the semantic values of the components matched by the rule with the construct @code{$@var{n}}, which stands for the value of the @var{n}th component. The semantic value for the grouping -being constructed is @code{$$}. (Bison translates both of these constructs -into array element references when it copies the actions into the parser -file.) +being constructed is @code{$$}. Bison translates both of these +constructs into expressions of the appropriate type when it copies the +actions into the parser file. @code{$$} is translated to a modifiable +lvalue, so it can be assigned to. Here is a typical example: @@ -3082,8 +3088,6 @@ Though grammar rules and semantic actions are enough to write a fully functional parser, it can be useful to process some additional information, especially symbol locations. -@c (terminal or not) ? - The way locations are handled is defined by providing a data type, and actions to take when rules are matched. @@ -3148,9 +3152,10 @@ exp: @dots{} else @{ $$ = 1; - printf("Division by zero, l%d,c%d-l%d,c%d", - @@3.first_line, @@3.first_column, - @@3.last_line, @@3.last_column); + fprintf (stderr, + "Division by zero, l%d,c%d-l%d,c%d", + @@3.first_line, @@3.first_column, + @@3.last_line, @@3.last_column); @} @} @end group @@ -3174,9 +3179,10 @@ exp: @dots{} else @{ $$ = 1; - printf("Division by zero, l%d,c%d-l%d,c%d", - @@3.first_line, @@3.first_column, - @@3.last_line, @@3.last_column); + fprintf (stderr, + "Division by zero, l%d,c%d-l%d,c%d", + @@3.first_line, @@3.first_column, + @@3.last_line, @@3.last_column); @} @} @end group @@ -3210,11 +3216,11 @@ By default, @code{YYLLOC_DEFAULT} is defined this way for simple @example @group -#define YYLLOC_DEFAULT(Current, Rhs, N) \ - Current.first_line = Rhs[1].first_line; \ - Current.first_column = Rhs[1].first_column; \ - Current.last_line = Rhs[N].last_line; \ - Current.last_column = Rhs[N].last_column; +# define YYLLOC_DEFAULT(Current, Rhs, N) \ + ((Current).first_line = (Rhs)[1].first_line, \ + (Current).first_column = (Rhs)[1].first_column, \ + (Current).last_line = (Rhs)[N].last_line, \ + (Current).last_column = (Rhs)[N].last_column) @end group @end example @@ -3223,11 +3229,11 @@ and like this for @acronym{GLR} parsers: @example @group -#define YYLLOC_DEFAULT(Current, Rhs, N) \ - Current.first_line = YYRHSLOC(Rhs,1).first_line; \ - Current.first_column = YYRHSLOC(Rhs,1).first_column; \ - Current.last_line = YYRHSLOC(Rhs,N).last_line; \ - Current.last_column = YYRHSLOC(Rhs,N).last_column; +# define YYLLOC_DEFAULT(yyCurrent, yyRhs, YYN) \ + ((yyCurrent).first_line = YYRHSLOC(yyRhs, 1).first_line, \ + (yyCurrent).first_column = YYRHSLOC(yyRhs, 1).first_column, \ + (yyCurrent).last_line = YYRHSLOC(yyRhs, YYN).last_line, \ + (yyCurrent).last_column = YYRHSLOC(yyRhs, YYN).last_column) @end group @end example @@ -3241,6 +3247,12 @@ result) should be modified by @code{YYLLOC_DEFAULT}. @item For consistency with semantic actions, valid indexes for the location array range from 1 to @var{n}. + +@item +Your macro should parenthesize its arguments, if need be, since the +actual arguments may not be surrounded by parentheses. Also, your +macro should expand to something that can be used as a single +statement when it is followed by a semicolon. @end itemize @node Declarations @@ -3673,9 +3685,16 @@ Declare a terminal symbol (token type name) that is left-associative @deffn {Directive} %nonassoc Declare a terminal symbol (token type name) that is nonassociative -(using it in a way that would be associative is a syntax error) -@end deffn (@pxref{Precedence Decl, ,Operator Precedence}). +Using it in a way that would be associative is a syntax error. +@end deffn + +@ifset defaultprec +@deffn {Directive} %default-prec +Assign a precedence to rules lacking an explicit @code{%prec} modifier +(@pxref{Contextual Precedence, ,Context-Dependent Precedence}). +@end deffn +@end ifset @deffn {Directive} %type Declare the type of semantic values for a nonterminal symbol @@ -3747,6 +3766,14 @@ and so on. @xref{Multiple Parsers, ,Multiple Parsers in the Same Program}. @end deffn +@ifset defaultprec +@deffn {Directive} %no-default-prec +Do not assign a precedence to rules lacking an explicit @code{%prec} +modifier (@pxref{Contextual Precedence, ,Context-Dependent +Precedence}). +@end deffn +@end ifset + @deffn {Directive} %no-parser Do not include any C code in the parser file; generate tables only. The parser file contains just @code{#define} directives and static variable @@ -4845,6 +4872,28 @@ exp: @dots{} @end group @end example +@ifset defaultprec +If you forget to append @code{%prec UMINUS} to the rule for unary +minus, Bison silently assumes that minus has its usual precedence. +This kind of problem can be tricky to debug, since one typically +discovers the mistake only by testing the code. + +The @code{%no-default-prec;} declaration makes it easier to discover +this kind of problem systematically. It causes rules that lack a +@code{%prec} modifier to have no precedence, even if the last terminal +symbol mentioned in their components has a declared precedence. + +If @code{%no-default-prec;} is in effect, you must specify @code{%prec} +for all rules that participate in precedence conflict resolution. +Then you will see any shift/reduce conflict until you tell Bison how +to resolve it, either by changing your grammar or by adding an +explicit precedence. This will probably add declarations to the +grammar, but it helps to protect against incorrect rule precedences. + +The effect of @code{%no-default-prec;} can be reversed by giving +@code{%default-prec;}, which is the default. +@end ifset + @node Parser States @section Parser States @cindex finite-state machine @@ -6356,7 +6405,7 @@ are addressed. @menu * Parser Stack Overflow:: Breaking the Stack Limits -* How Can I Reset @code{yyparse}:: @code{yyparse} Keeps some State +* How Can I Reset the Parser:: @code{yyparse} Keeps some State * Strings are Destroyed:: @code{yylval} Loses Track of Strings * C++ Parsers:: Compiling Parsers with C++ Compilers * Implementing Loops:: Control Flow in the Calculator @@ -6373,29 +6422,29 @@ 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} +@node How Can I Reset the Parser +@section How Can I Reset the Parser -The following phenomenon gives raise to several incarnations, -resulting in the following typical questions: +The following phenomenon has several symptoms, 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? +too. How can I reset the error flag of @code{yyparse}? @end display @noindent or @display -My parser includes support for a @samp{#include} like feature, in +My parser includes support for an @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 +These problems typically come not from Bison itself, but from +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}: @@ -6409,20 +6458,20 @@ demonstration, consider the following source file, .*\n ECHO; return 1; %% int -yyparse (const char *file) +yyparse (char const *file) { yyin = fopen (file, "r"); if (!yyin) exit (2); /* One token only. */ yylex (); - if (!fclose (yyin)) + if (fclose (yyin) != 0) exit (3); return 0; } int -main () +main (void) { yyparse ("input"); yyparse ("input"); @@ -6439,7 +6488,7 @@ input:2: World! @end verbatim @noindent -then instead of getting twice the first line, you get: +then instead of getting the first line twice, you get: @example $ @kbd{flex -ofirst-line.c first-line.l} @@ -6449,12 +6498,15 @@ 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}. +Therefore, whenever you change @code{yyin}, you must tell the +Lex-generated scanner to discard its current buffer and switch to the +new one. This depends upon your implementation of Lex; see its +documentation for more. For Flex, it suffices to call +@samp{YY_FLUSH_BUFFER} after each change to @code{yyin}. If your +Flex-generated scanner needs to read from several input streams to +handle features like include files, you might consider using Flex +functions like @samp{yy_switch_to_buffer} that manipulate multiple +input buffers. @node Strings are Destroyed @section Strings are Destroyed @@ -6546,9 +6598,9 @@ but how can I implement loops? @end display Although very pedagogical, the examples included in the document blur -the distinction to make between the parser ---whose job is to recover +the distinction to make between the parser---whose job is to recover the structure of a text and to transmit it to subsequent modules of -the program--- and the processing (such as the execution) of this +the program---and the processing (such as the execution) of this structure. This works well with so called straight line programs, i.e., precisely those that have a straightforward execution model: execute simple instructions one after the others. @@ -6773,6 +6825,14 @@ parsing. @xref{Parser Function, ,The Parser Function @code{yyparse}}. Equip the parser for debugging. @xref{Decl Summary}. @end deffn +@ifset defaultprec +@deffn {Directive} %default-prec +Assign a precedence to rules that lack an explicit @samp{%prec} +modifier. @xref{Contextual Precedence, ,Context-Dependent +Precedence}. +@end deffn +@end ifset + @deffn {Directive} %defines Bison declaration to create a header file meant for the scanner. @xref{Decl Summary}. @@ -6826,6 +6886,14 @@ function is applied to the two semantic values to get a single result. Bison declaration to rename the external symbols. @xref{Decl Summary}. @end deffn +@ifset defaultprec +@deffn {Directive} %no-default-prec +Do not assign a precedence to rules that lack an explicit @samp{%prec} +modifier. @xref{Contextual Precedence, ,Context-Dependent +Precedence}. +@end deffn +@end ifset + @deffn {Directive} %no-lines Bison declaration to avoid generating @code{#line} directives in the parser file. @xref{Decl Summary}.