[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
doc: improve the C++ section
From: |
Akim Demaille |
Subject: |
doc: improve the C++ section |
Date: |
Sat, 20 Oct 2018 19:02:43 +0200 |
More improvements to come, but reading the documentation
prompted the following commits.
commit 35068fbe66ba7eac8baae619c86b610f52143dee
Author: Akim Demaille <address@hidden>
Date: Fri Oct 19 08:52:46 2018 +0200
doc: improve the C++ section
* doc/bison.texi (C++ Parser): file.hh and location.hh are no longer
mandatory.
Various minor fixes.
diff --git a/doc/bison.texi b/doc/bison.texi
index 344b467f..61666c44 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -10593,6 +10593,10 @@ int yyparse (void);
@node Other Languages
@chapter Parsers Written In Other Languages
+In addition to C, Bison can generate parsers in C++ and Java. This chapter
+is devoted to these languages. The reader is expected to understand how
+Bison works; read the introductory chapters first if you don't.
+
@menu
* C++ Parsers:: The interface to generate C++ parser classes
* Java Parsers:: The interface to generate Java parser classes
@@ -10601,6 +10605,9 @@ int yyparse (void);
@node C++ Parsers
@section C++ Parsers
+The Bison parser in C++ is an object, an instance of the class
address@hidden::parser}.
+
@menu
* C++ Bison Interface:: Asking for C++ parser generation
* C++ Parser Interface:: Instantiating and running the parser
@@ -10617,9 +10624,7 @@ int yyparse (void);
@c - initial action
The C++ deterministic parser is selected using the skeleton directive,
address@hidden "lalr1.cc"}, or the synonymous command-line option
address@hidden
address@hidden Summary}.
address@hidden "lalr1.cc"}. @xref{Decl Summary}.
When run, @command{bison} will create several entities in the @samp{yy}
namespace.
@@ -10629,19 +10634,22 @@ see @ref{%define Summary,,api.namespace}. The
various classes are generated
in the following files:
@table @file
address@hidden @var{file}.hh
+(Assuming the extension of the grammar file was @samp{.yy}.) The
+declaration of the C++ parser class and auxiliary types. By default, this
+file is not generated (@pxref{Decl Summary, ,%defines}).
+
address@hidden @var{file}.cc
+The implementation of the C++ parser class. The basename and extension of
+these two files (@address@hidden and @address@hidden) follow the
+same rules as with regular C parsers (@pxref{Invocation}).
+
@item location.hh
The definition of the classes @code{position} and @code{location}, used for
location tracking when enabled. This file is not generated if user defined
locations are used, i.e., if the @code{%define} variable
@code{api.location.type} is defined. @xref{C++ Location Values}.
address@hidden @var{file}.hh
address@hidden @var{file}.cc
-(Assuming the extension of the grammar file was @samp{.yy}.) The
-declaration and implementation of the C++ parser class. The basename and
-extension of these two files follow the same rules as with regular C parsers
-(@pxref{Invocation}).
-
@item position.hh
@itemx stack.hh
Useless legacy files. To get rid of then, use @samp{%require "3.2"} or
@@ -10659,7 +10667,7 @@ complete and accurate documentation.
@c debug_stream.
@c - Reporting errors
-The output files @address@hidden and @address@hidden declare
+The output files @address@hidden and @address@hidden declare
and define the parser class in the namespace @code{yy}. The class name
defaults to @code{parser}, but may be changed using @samp{%define
parser_class_name @address@hidden@}}. The interface of this class is detailed
@@ -10668,16 +10676,20 @@ semantics is slightly changed since it describes an
additional member of the
parser class, and an additional argument for its constructor.
@defcv {Type} {parser} {semantic_type}
address@hidden {Type} {parser} {location_type}
-The types for semantic values and locations (if enabled).
+The types for semantic values. @xref{C++ Semantic Values}.
address@hidden defcv
+
address@hidden {Type} {parser} {location_type}
+The type of locations, if location tracking is enabled. @xref{C++ Location
+Values}.
@end defcv
@defcv {Type} {parser} {token}
A structure that contains (only) the @code{yytokentype} enumeration, which
-defines the tokens. To refer to the token @code{FOO},
-use @code{yy::parser::token::FOO}. The scanner can use
address@hidden yy::parser::token token;} to ``import'' the token enumeration
-(@pxref{Calc++ Scanner}).
+defines the tokens. To refer to the token @code{FOO}, use
address@hidden::parser::token::FOO}. The scanner can use @samp{typedef
+yy::parser::token token;} to ``import'' the token enumeration (@pxref{Calc++
+Scanner}).
@end defcv
@defcv {Type} {parser} {syntax_error}
@@ -10687,7 +10699,7 @@ equivalent with first invoking @code{error} to report
the location and
message of the syntax error, and then to invoke @code{YYERROR} to enter the
error-recovery mode. But contrary to @code{YYERROR} which can only be
invoked from user actions (i.e., written in the action itself), the
-exception can be thrown from function invoked from the user action.
+exception can be thrown from functions invoked from the user action.
@end defcv
@deftypeop {Constructor} {parser} {} parser ()
@@ -10721,9 +10733,9 @@ Get or set the stream used for tracing the parsing. It
defaults to
@end deftypemethod
@deftypemethod {parser} {debug_level_type} debug_level ()
address@hidden {parser} {void} set_debug_level (debug_level @var{l})
-Get or set the tracing level. Currently its value is either 0, no trace,
-or nonzero, full tracing.
address@hidden {parser} {void} set_debug_level (debug_level_type @var{l})
+Get or set the tracing level (an integral). Currently its value is either
+0, no trace, or nonzero, full tracing.
@end deftypemethod
@deftypemethod {parser} {void} error (const location_type& @var{l}, const
std::string& @var{m})
@@ -10741,9 +10753,9 @@ parser uses it to report a parser error occurring at
@var{l}, described by
@c - Printer and destructor
Bison supports two different means to handle semantic values in C++. One is
-alike the C interface, and relies on unions (@pxref{C++ Unions}). As C++
-practitioners know, unions are inconvenient in C++, therefore another
-approach is provided, based on variants (@pxref{C++ Variants}).
+alike the C interface, and relies on unions. As C++ practitioners know,
+unions are inconvenient in C++, therefore another approach is provided,
+based on variants.
@menu
* C++ Unions:: Semantic values cannot be objects
@@ -10753,18 +10765,18 @@ approach is provided, based on variants (@pxref{C++
Variants}).
@node C++ Unions
@subsubsection C++ Unions
-The @code{%union} directive works as for C, see @ref{Union Decl, ,The
-Union Declaration}. In particular it produces a genuine
address@hidden, which have a few specific features in C++.
+The @code{%union} directive works as for C, see @ref{Union Decl, ,The Union
+Declaration}. In particular it produces a genuine @code{union}, which have
+a few specific features in C++.
@itemize @minus
@item
The type @code{YYSTYPE} is defined but its use is discouraged: rather
you should refer to the parser's encapsulated type
@code{yy::parser::semantic_type}.
@item
-Non POD (Plain Old Data) types cannot be used. C++ forbids any
-instance of classes with constructors in unions: only @emph{pointers}
-to such objects are allowed.
+Non POD (Plain Old Data) types cannot be used. C++98 forbids any instance
+of classes with constructors in unions: only @emph{pointers} to such objects
+are allowed. C++11 relaxed this constraints, but at the cost of safety.
@end itemize
Because objects have to be stored via pointers, memory is not
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- doc: improve the C++ section,
Akim Demaille <=