c++: api.location.type

[bison.git] / doc / bison.texi

diff --git a/doc/bison.texi b/doc/bison.texi
index 15ee270e2726bd065f8236141fbb2c8ddc22457f..75e801830e8e48cd1afc61077d30a14f645d7243 100644 (file)
--- 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.
 * 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 ---
 
 @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
 
 * 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
 
 
 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
 @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
 @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
 @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}.
 
 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 (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
 
 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
 @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.,
 
 The @var{symbols} are defined as for @code{%destructor} (@pxref{Destructor
 Decl, , Freeing Discarded Symbols}.): they can be per-type (e.g.,


@@ -5075,7 +5081,7 @@ default location or at the location specified by @var{qualifier}.
 
 @deffn {Directive} %debug
 In the parser implementation file, define the macro @code{YYDEBUG} (or
 
 @deffn {Directive} %debug
 In the parser implementation file, define the macro @code{YYDEBUG} (or

-@code{@var{prefix}DEBUG} with @samp{%define api.prefix @var{prefix}}), see
+@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}.
 @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}.


@@ -5123,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}.
 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}
 @end deffn
 
 @deffn {Directive} %defines @var{defines-file}


@@ -5303,6 +5326,23 @@ Unaccepted @var{variable}s produce an error.
 Some of the accepted @var{variable}s are:
 
 @itemize @bullet
 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
 @c ================================================== api.prefix
 @item @code{api.prefix}
 @findex %define api.prefix


@@ -5310,7 +5350,7 @@ Some of the accepted @var{variable}s are:
 @itemize @bullet
 @item Language(s): All
 
 @itemize @bullet
 @item Language(s): All
 

-@item Purpose: Rename exported symbols
+@item Purpose: Rename exported symbols.

 @xref{Multiple Parsers, ,Multiple Parsers in the Same Program}.
 
 @item Accepted Values: String
 @xref{Multiple Parsers, ,Multiple Parsers in the Same Program}.
 
 @item Accepted Values: String


@@ -8498,11 +8538,11 @@ parser.  This is compliant with POSIX Yacc.  You could use
 YYDEBUG 1} in the prologue of the grammar file (@pxref{Prologue, , The
 Prologue}).
 
 YYDEBUG 1} in the prologue of the grammar file (@pxref{Prologue, , The
 Prologue}).
 

-If the @code{%define} variable @code{api.prefix} is used (@xref{Multiple
+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
 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 iff nonzero); otherwise tracing is enabled iff
-@code{YYDEBUG} is nonzero.
+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)
 
 @item the option @option{-t} (POSIX Yacc compliant)
 @itemx the option @option{--debug} (Bison extension)


@@ -9054,13 +9094,23 @@ separated list of @var{things} among:
 Description of the grammar, conflicts (resolved and unresolved), and
 parser's automaton.
 
 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 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}
 @end table
 
 @item --report-file=@var{file}


@@ -9178,8 +9228,9 @@ generated in the following files:
 @table @file
 @item position.hh
 @itemx location.hh
 @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.
 
 @item stack.hh
 An auxiliary class @code{stack} used by the parser.


@@ -9235,18 +9286,22 @@ Symbols}.
 @c - %define filename_type "const symbol::Symbol"
 
 When the directive @code{%locations} is used, the C++ parser supports
 @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
 
 @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
 @end menu
 
 @node C++ position


@@ -9350,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
 
 @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
 @node C++ Parser Interface
 @subsection C++ Parser Interface
 @c - define parser_class_name


@@ -9387,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.
 
 @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 deftypemethod
 
 @deftypemethod {parser} {std::ostream&} debug_stream ()


@@ -11704,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
 
 @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
 
 
 @printindex cp
 


@@ -11760,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: 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: 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"
 
 @c Local Variables:
 @c ispell-dictionary: "american"