* 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 ---
* 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
@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
@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}.
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
@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.,
@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}
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}
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}
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
@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
@c ================================================== lr.default-reductions
-@item lr.default-reductions
+@item @code{lr.default-reductions}
@findex %define lr.default-reductions
@itemize @bullet
@c ============================================ lr.keep-unreachable-states
-@item lr.keep-unreachable-states
+@item @code{lr.keep-unreachable-states}
@findex %define lr.keep-unreachable-states
@itemize @bullet
@c ================================================== lr.type
-@item lr.type
+@item @code{lr.type}
@findex %define lr.type
@itemize @bullet
@item Default Value: @code{lalr}
@end itemize
-@item namespace
+@c ================================================== namespace
+
+@item @code{namespace}
@findex %define namespace
@itemize
@end itemize
@c ================================================== parse.lac
-@item parse.lac
+@item @code{parse.lac}
@findex %define parse.lac
@itemize
@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
@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
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
@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
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}
@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.
@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
@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 <master/location.hh> @}
+@end example
+
@node C++ Parser Interface
@subsection C++ Parser Interface
@c - define parser_class_name
@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 ()
@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}
@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
@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"
projects / bison.git / blobdiff