X-Git-Url: https://git.saurik.com/bison.git/blobdiff_plain/258cddbc3695f2095cbfbc9ff95309b28733f7d2..db8ab2be3337ef87629b761078ebc46a01e7f876:/doc/bison.texi?ds=sidebyside diff --git a/doc/bison.texi b/doc/bison.texi index b1631665..75e80183 100644 --- a/doc/bison.texi +++ b/doc/bison.texi @@ -110,7 +110,7 @@ Reference sections: * Glossary:: Basic concepts are explained. * Copying This Manual:: License for copying this manual. * Bibliography:: Publications cited in this manual. -* Index:: Cross-references to the text. +* Index of Terms:: Cross-references to the text. @detailmenu --- The Detailed Node Listing --- @@ -327,6 +327,7 @@ C++ Location Values * C++ position:: One point in the source file * C++ location:: Two points in the source file +* User Defined Location Type:: Required interface for locations A Complete C++ Example @@ -4552,9 +4553,9 @@ code. @deffn {Directive} %initial-action @{ @var{code} @} @findex %initial-action Declare that the braced @var{code} must be invoked before parsing each time -@code{yyparse} is called. The @var{code} may use @code{$$} and -@code{@@$} --- initial value and location of the lookahead --- and the -@code{%parse-param}. +@code{yyparse} is called. The @var{code} may use @code{$$} (or +@code{$<@var{tag}>$}) and @code{@@$} --- initial value and location of the +lookahead --- and the @code{%parse-param}. @end deffn For instance, if your locations use a file name, you may use @@ -4592,11 +4593,11 @@ symbol is automatically discarded. @deffn {Directive} %destructor @{ @var{code} @} @var{symbols} @findex %destructor Invoke the braced @var{code} whenever the parser discards one of the -@var{symbols}. -Within @var{code}, @code{$$} designates the semantic value associated -with the discarded symbol, and @code{@@$} designates its location. -The additional parser parameters are also available (@pxref{Parser Function, , -The Parser Function @code{yyparse}}). +@var{symbols}. Within @var{code}, @code{$$} (or @code{$<@var{tag}>$}) +designates the semantic value associated with the discarded symbol, and +@code{@@$} designates its location. The additional parser parameters are +also available (@pxref{Parser Function, , The Parser Function +@code{yyparse}}). When a symbol is listed among @var{symbols}, its @code{%destructor} is called a per-symbol @code{%destructor}. @@ -4701,6 +4702,10 @@ incoming terminals during the second phase of error recovery, the current lookahead and the entire stack (except the current right-hand side symbols) when the parser returns immediately, and @item +the current lookahead and the entire stack (including the current right-hand +side symbols) when the C++ parser (@file{lalr1.cc}) catches an exception in +@code{parse}, +@item the start symbol, when the parser succeeds. @end itemize @@ -4734,10 +4739,11 @@ Decl, , Freeing Discarded Symbols}). @c This is the same text as for %destructor. Invoke the braced @var{code} whenever the parser displays one of the @var{symbols}. Within @var{code}, @code{yyoutput} denotes the output stream -(a @code{FILE*} in C, and an @code{std::ostream&} in C++), -@code{$$} designates the semantic value associated with the symbol, and -@code{@@$} its location. The additional parser parameters are also -available (@pxref{Parser Function, , The Parser Function @code{yyparse}}). +(a @code{FILE*} in C, and an @code{std::ostream&} in C++), @code{$$} (or +@code{$<@var{tag}>$}) designates the semantic value associated with the +symbol, and @code{@@$} its location. The additional parser parameters are +also available (@pxref{Parser Function, , The Parser Function +@code{yyparse}}). The @var{symbols} are defined as for @code{%destructor} (@pxref{Destructor Decl, , Freeing Discarded Symbols}.): they can be per-type (e.g., @@ -5074,9 +5080,11 @@ default location or at the location specified by @var{qualifier}. @end deffn @deffn {Directive} %debug -In the parser implementation file, define the macro @code{YYDEBUG} to -1 if it is not already defined, so that the debugging facilities are -compiled. @xref{Tracing, ,Tracing Your Parser}. +In the parser implementation file, define the macro @code{YYDEBUG} (or +@code{@var{prefix}DEBUG} with @samp{%define api.prefix @var{prefix}}, see +@ref{Multiple Parsers, ,Multiple Parsers in the Same Program}) to 1 if it is +not already defined, so that the debugging facilities are compiled. +@xref{Tracing, ,Tracing Your Parser}. @end deffn @deffn {Directive} %define @var{variable} @@ -5121,6 +5129,23 @@ Values, ,Semantic Values of Tokens}. If you have declared @code{%code requires} or @code{%code provides}, the output header also contains their code. @xref{%code Summary}. + +@cindex Header guard +The generated header is protected against multiple inclusions with a C +preprocessor guard: @samp{YY_@var{PREFIX}_@var{FILE}_INCLUDED}, where +@var{PREFIX} and @var{FILE} are the prefix (@pxref{Multiple Parsers, +,Multiple Parsers in the Same Program}) and generated file name turned +uppercase, with each series of non alphanumerical characters converted to a +single underscore. + +For instance with @samp{%define api.prefix "calc"} and @samp{%defines +"lib/parse.h"}, the header will be guarded as follows. +@example +#ifndef YY_CALC_LIB_PARSE_H_INCLUDED +# define YY_CALC_LIB_PARSE_H_INCLUDED +... +#endif /* ! YY_CALC_LIB_PARSE_H_INCLUDED */ +@end example @end deffn @deffn {Directive} %defines @var{defines-file} @@ -5154,22 +5179,6 @@ grammar does not use it, using @samp{%locations} allows for more accurate syntax error messages. @end deffn -@deffn {Directive} %name-prefix "@var{prefix}" -Rename the external symbols used in the parser so that they start with -@var{prefix} instead of @samp{yy}. The precise list of symbols renamed -in C parsers -is @code{yyparse}, @code{yylex}, @code{yyerror}, @code{yynerrs}, -@code{yylval}, @code{yychar}, @code{yydebug}, and -(if locations are used) @code{yylloc}. If you use a push parser, -@code{yypush_parse}, @code{yypull_parse}, @code{yypstate}, -@code{yypstate_new} and @code{yypstate_delete} will -also be renamed. For example, if you use @samp{%name-prefix "c_"}, the -names become @code{c_parse}, @code{c_lex}, and so on. -For C++ parsers, see the @code{%define namespace} documentation in this -section. -@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} @@ -5317,8 +5326,42 @@ Unaccepted @var{variable}s produce an error. Some of the accepted @var{variable}s are: @itemize @bullet +@c ================================================== api.location.type +@item @code{api.location.type} +@findex %define api.location.type + +@itemize @bullet +@item Language(s): C++ + +@item Purpose: Define the location type. +@xref{User Defined Location Type}. + +@item Accepted Values: String + +@item Default Value: none + +@item History: introduced in Bison 2.7 +@end itemize + +@c ================================================== api.prefix +@item @code{api.prefix} +@findex %define api.prefix + +@itemize @bullet +@item Language(s): All + +@item Purpose: Rename exported symbols. +@xref{Multiple Parsers, ,Multiple Parsers in the Same Program}. + +@item Accepted Values: String + +@item Default Value: @code{yy} + +@item History: introduced in Bison 2.6 +@end itemize + @c ================================================== api.pure -@item api.pure +@item @code{api.pure} @findex %define api.pure @itemize @bullet @@ -5332,7 +5375,9 @@ Some of the accepted @var{variable}s are: @item Default Value: @code{false} @end itemize -@item api.push-pull +@c ================================================== api.push-pull + +@item @code{api.push-pull} @findex %define api.push-pull @itemize @bullet @@ -5350,7 +5395,7 @@ More user feedback will help to stabilize it.) @c ================================================== lr.default-reductions -@item lr.default-reductions +@item @code{lr.default-reductions} @findex %define lr.default-reductions @itemize @bullet @@ -5371,7 +5416,7 @@ feedback will help to stabilize it.) @c ============================================ lr.keep-unreachable-states -@item lr.keep-unreachable-states +@item @code{lr.keep-unreachable-states} @findex %define lr.keep-unreachable-states @itemize @bullet @@ -5384,7 +5429,7 @@ remain in the parser tables. @xref{Unreachable States}. @c ================================================== lr.type -@item lr.type +@item @code{lr.type} @findex %define lr.type @itemize @bullet @@ -5399,7 +5444,9 @@ More user feedback will help to stabilize it.) @item Default Value: @code{lalr} @end itemize -@item namespace +@c ================================================== namespace + +@item @code{namespace} @findex %define namespace @itemize @@ -5452,7 +5499,7 @@ The parser namespace is @code{foo} and @code{yylex} is referenced as @end itemize @c ================================================== parse.lac -@item parse.lac +@item @code{parse.lac} @findex %define parse.lac @itemize @@ -5585,34 +5632,88 @@ of the standard Bison skeletons. @section Multiple Parsers in the Same Program Most programs that use Bison parse only one language and therefore contain -only one Bison parser. But what if you want to parse more than one -language with the same program? Then you need to avoid a name conflict -between different definitions of @code{yyparse}, @code{yylval}, and so on. - -The easy way to do this is to use the option @samp{-p @var{prefix}} -(@pxref{Invocation, ,Invoking Bison}). This renames the interface -functions and variables of the Bison parser to start with @var{prefix} -instead of @samp{yy}. You can use this to give each parser distinct -names that do not conflict. - -The precise list of symbols renamed is @code{yyparse}, @code{yylex}, -@code{yyerror}, @code{yynerrs}, @code{yylval}, @code{yylloc}, -@code{yychar} and @code{yydebug}. If you use a push parser, -@code{yypush_parse}, @code{yypull_parse}, @code{yypstate}, -@code{yypstate_new} and @code{yypstate_delete} will also be renamed. -For example, if you use @samp{-p c}, the names become @code{cparse}, -@code{clex}, and so on. - -@strong{All the other variables and macros associated with Bison are not -renamed.} These others are not global; there is no conflict if the same -name is used in different parsers. For example, @code{YYSTYPE} is not -renamed, but defining this in different ways in different parsers causes -no trouble (@pxref{Value Type, ,Data Types of Semantic Values}). - -The @samp{-p} option works by adding macro definitions to the -beginning of the parser implementation file, defining @code{yyparse} -as @code{@var{prefix}parse}, and so on. This effectively substitutes -one name for the other in the entire parser implementation file. +only one Bison parser. But what if you want to parse more than one language +with the same program? Then you need to avoid name conflicts between +different definitions of functions and variables such as @code{yyparse}, +@code{yylval}. To use different parsers from the same compilation unit, you +also need to avoid conflicts on types and macros (e.g., @code{YYSTYPE}) +exported in the generated header. + +The easy way to do this is to define the @code{%define} variable +@code{api.prefix}. With different @code{api.prefix}s it is guaranteed that +headers do not conflict when included together, and that compiled objects +can be linked together too. Specifying @samp{%define api.prefix +@var{prefix}} (or passing the option @samp{-Dapi.prefix=@var{prefix}}, see +@ref{Invocation, ,Invoking Bison}) renames the interface functions and +variables of the Bison parser to start with @var{prefix} instead of +@samp{yy}, and all the macros to start by @var{PREFIX} (i.e., @var{prefix} +upper-cased) instead of @samp{YY}. + +The renamed symbols include @code{yyparse}, @code{yylex}, @code{yyerror}, +@code{yynerrs}, @code{yylval}, @code{yylloc}, @code{yychar} and +@code{yydebug}. If you use a push parser, @code{yypush_parse}, +@code{yypull_parse}, @code{yypstate}, @code{yypstate_new} and +@code{yypstate_delete} will also be renamed. The renamed macros include +@code{YYSTYPE}, @code{YYLTYPE}, and @code{YYDEBUG}, which is treated +specifically --- more about this below. + +For example, if you use @samp{%define api.prefix c}, the names become +@code{cparse}, @code{clex}, @dots{}, @code{CSTYPE}, @code{CLTYPE}, and so +on. + +The @code{%define} variable @code{api.prefix} works in two different ways. +In the implementation file, it works by adding macro definitions to the +beginning of the parser implementation file, defining @code{yyparse} as +@code{@var{prefix}parse}, and so on: + +@example +#define YYSTYPE CTYPE +#define yyparse cparse +#define yylval clval +... +YYSTYPE yylval; +int yyparse (void); +@end example + +This effectively substitutes one name for the other in the entire parser +implementation file, thus the ``original'' names (@code{yylex}, +@code{YYSTYPE}, @dots{}) are also usable in the parser implementation file. + +However, in the parser header file, the symbols are defined renamed, for +instance: + +@example +extern CSTYPE clval; +int cparse (void); +@end example + +The macro @code{YYDEBUG} is commonly used to enable the tracing support in +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. */ +#ifndef CDEBUG +# if defined YYDEBUG +# if YYDEBUG +# define CDEBUG 1 +# else +# define CDEBUG 0 +# endif +# else +# define CDEBUG 0 +# endif +#endif +#if CDEBUG +extern int cdebug; +#endif +@end example + +@sp 2 + +Prior to Bison 2.6, a feature similar to @code{api.prefix} was provided by +the obsolete directive @code{%name-prefix} (@pxref{Table of Symbols, ,Bison +Symbols}) and the option @code{--name-prefix} (@pxref{Bison Options}). @node Interface @chapter Parser C-Language Interface @@ -5729,9 +5830,9 @@ function is available if either the @code{%define api.push-pull push} or @xref{Push Decl, ,A Push Parser}. @deftypefun int yypush_parse (yypstate *yyps) -The value returned by @code{yypush_parse} is the same as for yyparse with the -following exception. @code{yypush_parse} will return YYPUSH_MORE if more input -is required to finish parsing the grammar. +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. @end deftypefun @node Pull Parser Function @@ -8437,18 +8538,24 @@ parser. This is compliant with POSIX Yacc. You could use YYDEBUG 1} in the prologue of the grammar file (@pxref{Prologue, , The Prologue}). -@item the option @option{-t}, @option{--debug} -Use the @samp{-t} option when you run Bison (@pxref{Invocation, -,Invoking Bison}). This is POSIX compliant too. +If the @code{%define} variable @code{api.prefix} is used (@pxref{Multiple +Parsers, ,Multiple Parsers in the Same Program}), for instance @samp{%define +api.prefix x}, then if @code{CDEBUG} is defined, its value controls the +tracing feature (enabled if and only if nonzero); otherwise tracing is +enabled if and only if @code{YYDEBUG} is nonzero. + +@item the option @option{-t} (POSIX Yacc compliant) +@itemx the option @option{--debug} (Bison extension) +Use the @samp{-t} option when you run Bison (@pxref{Invocation, ,Invoking +Bison}). With @samp{%define api.prefix c}, it defines @code{CDEBUG} to 1, +otherwise it defines @code{YYDEBUG} to 1. @item the directive @samp{%debug} @findex %debug -Add the @code{%debug} directive (@pxref{Decl Summary, ,Bison -Declaration Summary}). This is a Bison extension, which will prove -useful when Bison will output parsers for languages that don't use a -preprocessor. Unless POSIX and Yacc portability matter to -you, this is -the preferred solution. +Add the @code{%debug} directive (@pxref{Decl Summary, ,Bison Declaration +Summary}). This is a Bison extension, especially useful for languages that +don't use a preprocessor. Unless POSIX and Yacc portability matter to you, +this is the preferred solution. @end table We suggest that you always enable the debug option so that debugging is @@ -8924,8 +9031,9 @@ Pretend that @code{%locations} was specified. @xref{Decl Summary}. @item -p @var{prefix} @itemx --name-prefix=@var{prefix} -Pretend that @code{%name-prefix "@var{prefix}"} was specified. -@xref{Decl Summary}. +Pretend that @code{%name-prefix "@var{prefix}"} was specified (@pxref{Decl +Summary}). Obsoleted by @code{-Dapi.prefix=@var{prefix}}. @xref{Multiple +Parsers, ,Multiple Parsers in the Same Program}. @item -l @itemx --no-lines @@ -8986,13 +9094,23 @@ separated list of @var{things} among: Description of the grammar, conflicts (resolved and unresolved), and parser's automaton. +@item itemset +Implies @code{state} and augments the description of the automaton with +the full set of items for each state, instead of its core only. + @item lookahead Implies @code{state} and augments the description of the automaton with each rule's lookahead set. -@item itemset -Implies @code{state} and augments the description of the automaton with -the full set of items for each state, instead of its core only. +@item solved +Implies @code{state}. Explain how conflicts were solved thanks to +precedence and associativity directives. + +@item all +Enable all the items. + +@item none +Do not generate the report. @end table @item --report-file=@var{file} @@ -9110,8 +9228,9 @@ generated in the following files: @table @file @item position.hh @itemx location.hh -The definition of the classes @code{position} and @code{location}, -used for location tracking. @xref{C++ Location Values}. +The definition of the classes @code{position} and @code{location}, used for +location tracking. These files are not generated if the @code{%define} +variable @code{api.location.type} is defined. @xref{C++ Location Values}. @item stack.hh An auxiliary class @code{stack} used by the parser. @@ -9167,18 +9286,22 @@ Symbols}. @c - %define filename_type "const symbol::Symbol" When the directive @code{%locations} is used, the C++ parser supports -location tracking, see @ref{Tracking Locations}. Two auxiliary classes -define a @code{position}, a single point in a file, and a @code{location}, a -range composed of a pair of @code{position}s (possibly spanning several -files). +location tracking, see @ref{Tracking Locations}. + +By default, two auxiliary classes define a @code{position}, a single point +in a file, and a @code{location}, a range composed of a pair of +@code{position}s (possibly spanning several files). But if the +@code{%define} variable @code{api.location.type} is defined, then these +classes will not be generated, and the user defined type will be used. @tindex uint In this section @code{uint} is an abbreviation for @code{unsigned int}: in genuine code only the latter is used. @menu -* C++ position:: One point in the source file -* C++ location:: Two points in the source file +* C++ position:: One point in the source file +* C++ location:: Two points in the source file +* User Defined Location Type:: Required interface for locations @end menu @node C++ position @@ -9282,6 +9405,63 @@ Report @var{p} on @var{o}, taking care of special cases such as: no @code{filename} defined, or equal filename/line or column. @end deftypefun +@node User Defined Location Type +@subsubsection User Defined Location Type +@findex %define api.location.type + +Instead of using the built-in types you may use the @code{%define} variable +@code{api.location.type} to specify your own type: + +@example +%define api.location.type @var{LocationType} +@end example + +The requirements over your @var{LocationType} are: +@itemize +@item +it must be copyable; + +@item +in order to compute the (default) value of @code{@@$} in a reduction, the +parser basically runs +@example +@@$.begin = @@$1.begin; +@@$.end = @@$@var{N}.end; // The location of last right-hand side symbol. +@end example +@noindent +so there must be copyable @code{begin} and @code{end} members; + +@item +alternatively you may redefine the computation of the default location, in +which case these members are not required (@pxref{Location Default Action}); + +@item +if traces are enabled, then there must exist an @samp{std::ostream& + operator<< (std::ostream& o, const @var{LocationType}& s)} function. +@end itemize + +@sp 1 + +In programs with several C++ parsers, you may also use the @code{%define} +variable @code{api.location.type} to share a common set of built-in +definitions for @code{position} and @code{location}. For instance, one +parser @file{master/parser.yy} might use: + +@example +%defines +%locations +%define namespace "master::" +@end example + +@noindent +to generate the @file{master/position.hh} and @file{master/location.hh} +files, reused by other parsers as follows: + +@example +%define location_type "master::location" +%code requires @{ #include @} +@end example + @node C++ Parser Interface @subsection C++ Parser Interface @c - define parser_class_name @@ -9319,6 +9499,11 @@ Build a new parser object. There are no arguments by default, unless @deftypemethod {parser} {int} parse () Run the syntactic analysis, and return 0 on success, 1 otherwise. + +@cindex exceptions +The whole function is wrapped in a @code{try}/@code{catch} block, so that +when an exception is thrown, the @code{%destructor}s are called to release +the lookahead symbol, and the symbols pushed on the stack. @end deftypemethod @deftypemethod {parser} {std::ostream&} debug_stream () @@ -11054,9 +11239,24 @@ function is applied to the two semantic values to get a single result. @end deffn @deffn {Directive} %name-prefix "@var{prefix}" -Bison declaration to rename the external symbols. @xref{Decl Summary}. +Obsoleted by the @code{%define} variable @code{api.prefix} (@pxref{Multiple +Parsers, ,Multiple Parsers in the Same Program}). + +Rename the external symbols (variables and functions) used in the parser so +that they start with @var{prefix} instead of @samp{yy}. Contrary to +@code{api.prefix}, do no rename types and macros. + +The precise list of symbols renamed in C parsers is @code{yyparse}, +@code{yylex}, @code{yyerror}, @code{yynerrs}, @code{yylval}, @code{yychar}, +@code{yydebug}, and (if locations are used) @code{yylloc}. If you use a +push parser, @code{yypush_parse}, @code{yypull_parse}, @code{yypstate}, +@code{yypstate_new} and @code{yypstate_delete} will also be renamed. For +example, if you use @samp{%name-prefix "c_"}, the names become +@code{c_parse}, @code{c_lex}, and so on. For C++ parsers, see the +@code{%define namespace} documentation in this section. @end deffn + @ifset defaultprec @deffn {Directive} %no-default-prec Do not assign a precedence to rules that lack an explicit @samp{%prec} @@ -11621,8 +11821,8 @@ London, Department of Computer Science, TR-00-12 (December 2000). @uref{http://www.cs.rhul.ac.uk/research/languages/publications/tomita_style_1.ps} @end table -@node Index -@unnumbered Index +@node Index of Terms +@unnumbered Index of Terms @printindex cp @@ -11677,10 +11877,11 @@ London, Department of Computer Science, TR-00-12 (December 2000). @c LocalWords: toString deftypeivar deftypeivarx deftypeop YYParser strictfp @c LocalWords: superclasses boolean getErrorVerbose setErrorVerbose deftypecv @c LocalWords: getDebugStream setDebugStream getDebugLevel setDebugLevel url -@c LocalWords: bisonVersion deftypecvx bisonSkeleton getStartPos getEndPos +@c LocalWords: bisonVersion deftypecvx bisonSkeleton getStartPos getEndPos uint @c LocalWords: getLVal defvar deftypefn deftypefnx gotos msgfmt Corbett LALR's -@c LocalWords: subdirectory Solaris nonassociativity perror schemas Malloy -@c LocalWords: Scannerless ispell american +@c LocalWords: subdirectory Solaris nonassociativity perror schemas Malloy ints +@c LocalWords: Scannerless ispell american ChangeLog smallexample CSTYPE CLTYPE +@c LocalWords: clval CDEBUG cdebug deftypeopx yyterminate @c Local Variables: @c ispell-dictionary: "american"