@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.
+1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
* 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
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
+* C++ Parsers:: Compiling Parsers with C++ Compilers
+* Implementing Loops:: Control Flow in the Calculator
Copying This Manual
@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
@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,
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
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
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
Declare that the @var{code} must be invoked for each of the
@var{symbols} that will be discarded by the parser. The @var{code}
should use @code{$$} to designate the semantic value associated to the
-@var{symbols}. The additional parser parameters are also avaible
+@var{symbols}. The additional parser parameters are also available
(@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
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.
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
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.
@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
* 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
@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, ,
@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.
@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}.
@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
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
@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
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
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
@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
+* C++ Parsers:: Compiling Parsers with C++ Compilers
+* Implementing Loops:: Control Flow in the Calculator
@end menu
@node Parser Stack Overflow
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 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 the error flag of @code{yyparse}?
+@end display
+
+@noindent
+or
+
+@display
+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 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}:
+
+@verbatim
+%{
+#include <stdio.h>
+#include <stdlib.h>
+%}
+%%
+.*\n ECHO; return 1;
+%%
+int
+yyparse (char const *file)
+{
+ yyin = fopen (file, "r");
+ if (!yyin)
+ exit (2);
+ /* One token only. */
+ yylex ();
+ if (fclose (yyin) != 0)
+ exit (3);
+ return 0;
+}
+
+int
+main (void)
+{
+ 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 the first line twice, 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 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
+
+@display
+My parser seems to destroy old strings, or maybe it loses 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 <stdio.h>
+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
+
+
+@node C++ Parsers
+@section C++ Parsers
+
+@display
+How can I generate parsers in C++?
+@end display
+
+We are working on a C++ output for Bison, but unfortunately, for lack
+of time, the skeleton is not finished. It is functional, but in
+numerous respects, it will require additional work which @emph{might}
+break backward compatibility. Since the skeleton for C++ is not
+documented, we do not consider ourselves bound to this interface,
+nevertheless, as much as possible we will try to keep compatibility.
+
+Another possibility is to use the regular C parsers, and to compile
+them with a C++ compiler. This works properly, provided that you bear
+some simple C++ rules in mind, such as not including ``real classes''
+(i.e., structure with constructors) in unions. Therefore, in the
+@code{%union}, use pointers to classes, or better yet, a single
+pointer type to the root of your lexical/syntactic hierarchy.
+
+
+@node Implementing Loops
+@section Implementing Loops
+
+@display
+My simple calculator supports variables, assignments, and functions,
+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 structure of a text and to transmit it to subsequent modules of
+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.
+
+@cindex abstract syntax tree
+@cindex @acronym{AST}
+If you want a richer model, you will probably need to use the parser
+to construct a tree that does represent the structure it has
+recovered; this tree is usually called the @dfn{abstract syntax tree},
+or @dfn{@acronym{AST}} for short. Then, walking through this tree,
+traversing it in various ways, will enable treatments such as its
+execution or its translation, which will result in an interpreter or a
+compiler.
+
+This topic is way beyond the scope of this manual, and the reader is
+invited to consult the dedicated literature.
+
+
+
@c ================================================= Table of Symbols
@node Table of Symbols
@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}.
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
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
@printindex cp
@bye
+
+@c LocalWords: texinfo setfilename settitle setchapternewpage finalout
+@c LocalWords: ifinfo smallbook shorttitlepage titlepage GPL FIXME iftex
+@c LocalWords: akim fn cp syncodeindex vr tp synindex dircategory direntry
+@c LocalWords: ifset vskip pt filll insertcopying sp ISBN Etienne Suvasa
+@c LocalWords: ifnottex yyparse detailmenu GLR RPN Calc var Decls Rpcalc
+@c LocalWords: rpcalc Lexer Gen Comp Expr ltcalc mfcalc Decl Symtab yylex
+@c LocalWords: yyerror pxref LR yylval cindex dfn LALR samp gpl BNF xref
+@c LocalWords: const int paren ifnotinfo AC noindent emph expr stmt findex
+@c LocalWords: glr YYSTYPE TYPENAME prog dprec printf decl init stmtMerge
+@c LocalWords: pre STDC GNUC endif yy YY alloca lf stddef stdlib YYDEBUG
+@c LocalWords: NUM exp subsubsection kbd Ctrl ctype EOF getchar isdigit
+@c LocalWords: ungetc stdin scanf sc calc ulator ls lm cc NEG prec yyerrok
+@c LocalWords: longjmp fprintf stderr preg yylloc YYLTYPE cos ln
+@c LocalWords: smallexample symrec val tptr FNCT fnctptr func struct sym
+@c LocalWords: fnct putsym getsym fname arith fncts atan ptr malloc sizeof
+@c LocalWords: strlen strcpy fctn strcmp isalpha symbuf realloc isalnum
+@c LocalWords: ptypes itype YYPRINT trigraphs yytname expseq vindex dtype
+@c LocalWords: Rhs YYRHSLOC LE nonassoc op deffn typeless typefull yynerrs
+@c LocalWords: yychar yydebug msg YYNTOKENS YYNNTS YYNRULES YYNSTATES
+@c LocalWords: cparse clex deftypefun NE defmac YYACCEPT YYABORT param
+@c LocalWords: strncmp intval tindex lvalp locp llocp typealt YYBACKUP
+@c LocalWords: YYEMPTY YYRECOVERING yyclearin GE def UMINUS maybeword
+@c LocalWords: Johnstone Shamsa Sadaf Hussain Tomita TR uref YYMAXDEPTH
+@c LocalWords: YYINITDEPTH stmnts ref stmnt initdcl maybeasm VCG notype
+@c LocalWords: hexflag STR exdent itemset asis DYYDEBUG YYFPRINTF args
+@c LocalWords: YYPRINTF infile ypp yxx outfile itemx vcg tex leaderfill
+@c LocalWords: hbox hss hfill tt ly yyin fopen fclose ofirst gcc ll
+@c LocalWords: yyrestart nbar yytext fst snd osplit ntwo strdup AST
+@c LocalWords: YYSTACK DVI fdl printindex
projects / bison.git / blobdiff