[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
RFC: doc: document api.*.file and the like
From: |
Akim Demaille |
Subject: |
RFC: doc: document api.*.file and the like |
Date: |
Tue, 9 Oct 2018 08:22:17 +0200 |
Hi all,
This is my proposal to document the new variables that provide
control over the file we use in C++. I’m sure there are better
ways to document this, I’m not sure I’m the right person to do
it. Contributions and critiques are most welcome.
commit 2a0072928e6e1ec567fea5c512c4cfc3dd798e3c
Author: Akim Demaille <address@hidden>
Date: Mon Oct 8 08:24:34 2018 +0200
doc: document api.*.file and the like
* doc/bison.texi (Exposing the Location Classes): New.
(%define Summary): Document api.location.file, api.location.include,
api.stack.file and api.position.file.
(C++ Bison Interface): stack.hh and position.hh are deprecated.
diff --git a/doc/bison.texi b/doc/bison.texi
index 5b6791f2..fbc4cc8e 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -347,9 +347,11 @@ C++ Parsers
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
+* C++ position:: One point in the source file
+* C++ location:: Two points in the source file
+* Exposing the Location Classes:: Using the Bison location class in your
+ project
+* User Defined Location Type:: Required interface for locations
A Complete C++ Example
@@ -5808,6 +5810,70 @@ The parser namespace is @code{foo} and @code{yylex} is
referenced as
@end deffn
@c api.namespace
address@hidden ==================================================
api.location.file
address@hidden {Directive} {%define api.location.file} "@var{file}"
address@hidden {Directive} {%define api.location.file} @code{none}
+
address@hidden @bullet
address@hidden Language(s): C++
+
address@hidden Purpose:
+Define the name of the file in which Bison's default location and position
+types are generated. @xref{Exposing the Location Classes}.
+
address@hidden Accepted Values:
address@hidden @asis
address@hidden @code{none}
+If locations are enabled, generate the definition of the @code{position} and
address@hidden classes in the header file if @code{%defines}, otherwise in
+the parser implementation.
+
address@hidden "@var{file}"
+Generate the definition of the @code{position} and @code{location} classes
+in @var{file}. This file name can be relative (to where the parser file is
+output) or absolute.
address@hidden table
+
+Defining it imples @samp{%define api.position.file none} and @samp{%define
+api.stack.file none}.
+
address@hidden Default Value:
+Not applicable if locations are not enabled, or if a user location type is
+specified (see @code{api.location.type}). Otherwise, Bison's
address@hidden is generated in @file{location.hh} (@pxref{C++ location}).
+
address@hidden History:
+Introduced in Bison 3.2.
address@hidden itemize
address@hidden deffn
+
address@hidden ==================================================
api.location.file
address@hidden {Directive} {%define api.location.include} @{"@var{file}"@}
address@hidden {Directive} {%define api.location.include} @{<@var{file}>@}
+
address@hidden @bullet
address@hidden Language(s): C++
+
address@hidden Purpose:
+Specify how the generated file that defines the @code{position} and
address@hidden classes is included. This makes sense when the
address@hidden class is exposed to the rest of your application/library in
+another directory. @xref{Exposing the Location Classes}.
+
address@hidden Accepted Values: Argument for @code{#include}.
+
address@hidden Default Value:
address@hidden"@var{dir}/location.hh"} where @var{dir} is the directory part of
the
+output. For instance @file{src/parse} if
address@hidden/parse/parser.cc} was given.
+
address@hidden History:
+Introduced in Bison 3.2.
address@hidden itemize
+
address@hidden deffn
+
+
@c ================================================== api.location.type
@deffn {Directive} {%define api.location.type} @address@hidden@}
@@ -5827,6 +5893,28 @@ Introduced in Bison 2.7 for C, C++ and Java. Introduced
under the name
@end itemize
@end deffn
address@hidden ==================================================
api.position.file
address@hidden {Directive} {%define api.position.file} @code{none}
+
address@hidden @bullet
address@hidden Language(s): C++
+
address@hidden Purpose:
+Disable the generation of the legacy file @file{position.hh}. The class
address@hidden is now defined where the class @code{location} is.
+
address@hidden Accepted Values: @code{none}
+
address@hidden Default Value:
address@hidden if @code{api.location.file} is defined, otherwise a useless
address@hidden is generated for backward compatibility.
+
address@hidden History:
+Introduced in Bison 3.2.
address@hidden itemize
address@hidden deffn
+
+
@c ================================================== api.prefix
@deffn {Directive} {%define api.prefix} @address@hidden@}
@@ -5913,6 +6001,27 @@ the @code{full} value was introduced in Bison 2.7
address@hidden ================================================== api.stack.file
address@hidden {Directive} {%define api.stack.file} @code{none}
+
address@hidden @bullet
address@hidden Language(s): C++
+
address@hidden Purpose:
+Disable the generation of the legacy file @file{stack.hh}.
+
address@hidden Accepted Values: @code{none}
+
address@hidden Default Value:
address@hidden if @code{api.location.file} is defined, otherwise a useless
address@hidden is generated for backward compatibility.
+
address@hidden History:
+Introduced in Bison 3.2.
address@hidden itemize
address@hidden deffn
+
+
@c ================================================== api.token.constructor
@deffn Directive {%define api.token.constructor}
@@ -10559,15 +10668,11 @@ see @ref{%define Summary,,api.namespace}. The
various classes are generated
in the following files:
@table @file
address@hidden position.hh
address@hidden location.hh
address@hidden location.hh
The definition of the classes @code{position} and @code{location}, used for
-location tracking when enabled. These files are not generated if the
address@hidden variable @code{api.location.type} is defined. @xref{C++
-Location Values}.
-
address@hidden stack.hh
-An auxiliary class @code{stack} used by the parser.
+location tracking when enabled. This file is not generated if user defined
+locations are used, i.e., if the @code{%define} variable
address@hidden is defined. @xref{C++ Location Values}.
@item @var{file}.hh
@itemx @var{file}.cc
@@ -10575,6 +10680,14 @@ An auxiliary class @code{stack} used by the parser.
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}).
+
address@hidden position.hh
+A useless legacy file. To get rid of it, use @samp{%define api.stack.file
+none}, or define @code{api.location.file}.
+
address@hidden stack.hh
+A useless legacy file. To get rid of it, use @samp{%define
+api.position.file none}, or define @code{api.location.file}.
@end table
All these files are documented using Doxygen; run @command{doxygen} for a
@@ -10728,7 +10841,9 @@ classes will not be generated, and the user defined
type will be used.
@menu
* C++ position:: One point in the source file
* C++ location:: Two points in the source file
-* User Defined Location Type:: Required interface for locations
+* Exposing the Location Classes:: Using the Bison location class in your
+ project
+* User Defined Location Type:: Required interface for locations
@end menu
@node C++ position
@@ -10841,6 +10956,55 @@ 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
address@hidden Exposing the Location Classes
address@hidden Exposing the Location Classes
+
+When both @code{%defines} and @code{%locations} are enabled, Bison generates
+an additional file: @file{location.hh}. If you don't use locations outside
+of the parser, you may avoid its creation with @samp{%define
+api.location.file none}.
+
+However this file is useful if, for instance, your parser builds an abstract
+syntax tree decorated with locations: you may use Bison's @code{location}
+type independently of Bison's parser. You may name the file differently,
+e.g., @samp{%define api.location.file "include/ast/location.hh"}: this name
+can have directory components, or even be absolute. The way the location
+file is included is controlled by @code{api.location.include}.
+
+This way it is possible to have several parsers share the same location
+file.
+
+For instance, in @file{src/foo/parser.yy}, generate the
address@hidden/ast/loc.hh} file:
+
address@hidden
+// src/foo/parser.yy
+%locations
+%define api.namespace @address@hidden
+%define api.location.file "include/ast/loc.hh"
+%define api.location.include @{<ast/loc.hh>@}
address@hidden example
+
address@hidden
+and use it in @file{src/bar/parser.yy}:
+
address@hidden
+// src/bar/parser.yy
+%locations
+%define api.namespace @address@hidden
+%code requires @{#include <ast/loc.hh>@}
+%define api.location.type @{bar::address@hidden
address@hidden example
+
+Absolute file names are supported; it is safe in your @file{Makefile} to
+pass the flag
address@hidden'"$(top_srcdir)/include/ast/loc.hh"'} to
address@hidden for @file{src/foo/parser.yy}. The generated file will not
+have references to this absolute path, thanks to @samp{%define
+api.location.include @{<ast/loc.hh>@}}. Adding @samp{-I
+$(top_srcdir)/include} to your @code{CPPFLAGS} will suffice for the compiler
+to find @file{ast/loc.hh}.
+
@node User Defined Location Type
@subsubsection User Defined Location Type
@findex %define api.location.type
@@ -10898,6 +11062,7 @@ files, reused by other parsers as follows:
%code requires @{ #include <master/location.hh> @}
@end example
+
@node C++ Parser Interface
@subsection C++ Parser Interface
@c - define parser_class_name
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- RFC: doc: document api.*.file and the like,
Akim Demaille <=