[PATCH 3/3] api.location.type.

[Akim Demaille]

This feature was introduced in 95a2de5695670ae0df98cb3c42141cad549f0204
(which is part of 2.5), but not documented.  Give it a proper name, and
make it public.

* data/c++.m4, data/lalr1.cc, data/glr.cc, data/java.m4: Use
api.location.type instead of location_type.
* src/muscle-tab.c (muscle_percent_variable_update): Map the latter to
the former.
* tests/local.at: Adjust.
* tests/calc.at: Use api.location.type.
Leave tests/java.at with location_type, at least for the time being,
to cover both names.
* doc/bison.texi: Document api.location.type.
(User Defined Location Type): New.
* NEWS: Update.
---
 NEWS             | 15 +++++++++
 data/c++.m4      |  2 +-
 data/glr.cc      |  6 ++--
 data/java.m4     |  4 +--
 data/lalr1.cc    |  6 ++--
 doc/bison.texi   | 98 ++++++++++++++++++++++++++++++++++++++++++++++++++------
 src/muscle-tab.c |  1 +
 tests/calc.at    |  4 +--
 tests/local.at   |  2 +-
 9 files changed, 117 insertions(+), 21 deletions(-)

diff --git a/NEWS b/NEWS
index 1fe419f..a20898f 100644
--- a/NEWS
+++ b/NEWS
@@ -65,6 +65,21 @@ GNU Bison NEWS
   "function declared 'noreturn' should not return") have also been
   addressed.
 
+** New %define variable: api.location.type (glr.cc, lalr1.cc)
+
+  The %define variable api.location.type defines the name of the type to use
+  for locations.  When defined, Bison no longer generates the position.hh
+  and location.hh files, nor does the parser will include them: the user is
+  then responsible to define her type.
+
+  This can be used in programs with several parsers to factor their location
+  and position files: let one of them generate them, and let the others
+  simply resue these types and files.
+
+  This feature was actually introduced, but not documented, in Bison 2.5,
+  under the name "location_type" (which is maintained for backward
+  compatibility).
+
 * Noteworthy changes in release 2.6.2 (2012-08-03) [stable]
 
 ** Bug fixes
diff --git a/data/c++.m4 b/data/c++.m4
index 45c4dda..8b98b8c 100644
--- a/data/c++.m4
+++ b/data/c++.m4
@@ -29,7 +29,7 @@ b4_percent_define_default([[parser_class_name]], [[parser]])
 # Don't do that so that we remember whether we're using a user
 # request, or the default value.
 #
-# b4_percent_define_default([[location_type]], [[location]])
+# b4_percent_define_default([[api.location.type]], [[location]])
 
 b4_percent_define_default([[filename_type]], [[std::string]])
 b4_percent_define_default([[namespace]], m4_defn([b4_prefix]))
diff --git a/data/glr.cc b/data/glr.cc
index 826bc80..6527b0a 100644
--- a/data/glr.cc
+++ b/data/glr.cc
@@ -54,7 +54,7 @@ b4_defines_if([],
               [b4_fatal([b4_skeleton[: using %%defines is mandatory]])])
 
 m4_include(b4_pkgdatadir/[c++.m4])
-b4_percent_define_ifdef([[location_type]], [],
+b4_percent_define_ifdef([[api.location.type]], [],
                         [m4_include(b4_pkgdatadir/[location.cc])])
 
 m4_define([b4_parser_class_name],
@@ -238,7 +238,7 @@ b4_copyright([Skeleton interface for Bison GLR parsers in 
C++],
 
 # include <string>
 # include <iostream>
-]b4_percent_define_ifdef([[location_type]], [],
+]b4_percent_define_ifdef([[api.location.type]], [],
                          [[# include "location.hh"]])[
 
 ]b4_YYDEBUG_define[
@@ -262,7 +262,7 @@ b4_user_stype
     typedef ]b4_api_PREFIX[STYPE semantic_type;
 # endif
     /// Symbol locations.
-    typedef ]b4_percent_define_get([[location_type]],
+    typedef ]b4_percent_define_get([[api.location.type]],
                                    [[location]])[ location_type;
     /// Tokens.
     struct token
diff --git a/data/java.m4 b/data/java.m4
index 18ea30b..351f0f0 100644
--- a/data/java.m4
+++ b/data/java.m4
@@ -169,8 +169,8 @@ m4_define([b4_lex_throws], 
[b4_percent_define_get([[lex_throws]])])
 b4_percent_define_default([[throws]], [])])
 m4_define([b4_throws], [b4_percent_define_get([[throws]])])
 
-b4_percent_define_default([[location_type]], [Location])])
-m4_define([b4_location_type], [b4_percent_define_get([[location_type]])])
+b4_percent_define_default([[api.location.type]], [Location])])
+m4_define([b4_location_type], [b4_percent_define_get([[api.location.type]])])
 
 b4_percent_define_default([[position_type]], [Position])])
 m4_define([b4_position_type], [b4_percent_define_get([[position_type]])])
diff --git a/data/lalr1.cc b/data/lalr1.cc
index 3b8c921..46e58ae 100644
--- a/data/lalr1.cc
+++ b/data/lalr1.cc
@@ -24,7 +24,7 @@ m4_define([b4_parser_class_name],
 b4_defines_if([],
               [b4_fatal([b4_skeleton[: using %%defines is mandatory]])])
 
-b4_percent_define_ifdef([[location_type]], [],
+b4_percent_define_ifdef([[api.location.type]], [],
   [# Backward compatibility.
   m4_define([b4_location_constructors])
   m4_include(b4_pkgdatadir/[location.cc])])
@@ -52,7 +52,7 @@ b4_copyright([Skeleton interface for Bison LALR(1) parsers in 
C++],
 #include <string>
 #include <iostream>
 #include "stack.hh"
-]b4_percent_define_ifdef([[location_type]], [],
+]b4_percent_define_ifdef([[api.location.type]], [],
                          [[#include "location.hh"]])[
 
 ]b4_YYDEBUG_define[
@@ -77,7 +77,7 @@ b4_user_stype
     typedef ]b4_api_PREFIX[STYPE semantic_type;
 #endif
     /// Symbol locations.
-    typedef ]b4_percent_define_get([[location_type]],
+    typedef ]b4_percent_define_get([[api.location.type]],
                                    [[location]])[ location_type;
     /// Tokens.
     struct token
diff --git a/doc/bison.texi b/doc/bison.texi
index ce1ebd1..75e8018 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -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
 
@@ -5325,6 +5326,23 @@ Unaccepted @var{variable}s produce an error.
 Some of the accepted @var{variable}s are:
 
 @itemize @bullet
address@hidden ================================================== 
api.location.type
address@hidden @code{api.location.type}
address@hidden %define api.location.type
+
address@hidden @bullet
address@hidden Language(s): C++
+
address@hidden Purpose: Define the location type.
address@hidden Defined Location Type}.
+
address@hidden Accepted Values: String
+
address@hidden Default Value: none
+
address@hidden History: introduced in Bison 2.7
address@hidden itemize
+
 @c ================================================== api.prefix
 @item @code{api.prefix}
 @findex %define api.prefix
@@ -5332,7 +5350,7 @@ Some of the accepted @var{variable}s are:
 @itemize @bullet
 @item Language(s): All
 
address@hidden Purpose: Rename exported symbols
address@hidden Purpose: Rename exported symbols.
 @xref{Multiple Parsers, ,Multiple Parsers in the Same Program}.
 
 @item Accepted Values: String
@@ -9210,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.
@@ -9267,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
address@hidden (possibly spanning several files).  But if the
address@hidden 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
@@ -9382,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
 
address@hidden User Defined Location Type
address@hidden User Defined Location Type
address@hidden %define api.location.type
+
+Instead of using the built-in types you may use the @code{%define} variable
address@hidden to specify your own type:
+
address@hidden
+%define api.location.type @var{LocationType}
address@hidden example
+
+The requirements over your @var{LocationType} are:
address@hidden
address@hidden
+it must be copyable;
+
address@hidden
+in order to compute the (default) value of @code{@@$} in a reduction, the
+parser basically runs
address@hidden
+@@$.begin = @@$1.begin;
+@@$.end   = @@address@hidden; // The location of last right-hand side symbol.
address@hidden example
address@hidden
+so there must be copyable @code{begin} and @code{end} members;
+
address@hidden
+alternatively you may redefine the computation of the default location, in
+which case these members are not required (@pxref{Location Default Action});
+
address@hidden
+if traces are enabled, then there must exist an @samp{std::ostream&
+  operator<< (std::ostream& o, const @var{LocationType}& s)} function.
address@hidden itemize
+
address@hidden 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:
+
address@hidden
+%defines
+%locations
+%define namespace "master::"
address@hidden example
+
address@hidden
+to generate the @file{master/position.hh} and @file{master/location.hh}
+files, reused by other parsers as follows:
+
address@hidden
+%define location_type "master::location"
+%code requires @{ #include <master/location.hh> @}
address@hidden example
+
 @node C++ Parser Interface
 @subsection C++ Parser Interface
 @c - define parser_class_name
diff --git a/src/muscle-tab.c b/src/muscle-tab.c
index c203b37..2be29a4 100644
--- a/src/muscle-tab.c
+++ b/src/muscle-tab.c
@@ -410,6 +410,7 @@ muscle_percent_variable_update (char const *variable)
   const conversion_type conversion[] =
     {
       { "api.push_pull", "api.push-pull", },
+      { "location_type", "api.location.type", },
       { "lr.keep_unreachable_states", "lr.keep-unreachable-states", },
     };
   char const *res = variable;
diff --git a/tests/calc.at b/tests/calc.at
index 9518c3c..647d658 100644
--- a/tests/calc.at
+++ b/tests/calc.at
@@ -713,7 +713,7 @@ m4_define([AT_CHECK_CALC_LALR1_CC],
 [AT_CHECK_CALC([%language "C++" %defines %locations] $@)])
 
 AT_CHECK_CALC_LALR1_CC([])
-AT_CHECK_CALC_LALR1_CC([%define location_type Span])
+AT_CHECK_CALC_LALR1_CC([%define api.location.type Span])
 AT_CHECK_CALC_LALR1_CC([%error-verbose %name-prefix "calc" %verbose %yacc])
 AT_CHECK_CALC_LALR1_CC([%error-verbose %define api.prefix "calc" %verbose 
%yacc])
 AT_CHECK_CALC_LALR1_CC([%error-verbose %debug %name-prefix "calc" %verbose 
%yacc])
@@ -742,7 +742,7 @@ m4_define([AT_CHECK_CALC_GLR_CC],
 [AT_CHECK_CALC([%language "C++" %glr-parser %defines %locations] $@)])
 
 AT_CHECK_CALC_GLR_CC([])
-AT_CHECK_CALC_GLR_CC([%define location_type Span])
+AT_CHECK_CALC_GLR_CC([%define api.location.type Span])
 AT_CHECK_CALC_GLR_CC([%error-verbose %name-prefix "calc" %verbose %yacc])
 AT_CHECK_CALC_GLR_CC([%error-verbose %define api.prefix "calc" %verbose %yacc])
 
diff --git a/tests/local.at b/tests/local.at
index 036b0a1..65ff887 100644
--- a/tests/local.at
+++ b/tests/local.at
@@ -137,7 +137,7 @@ m4_pushdef([AT_LEXPARAM_IF],
 m4_pushdef([AT_LOCATION_IF],
 [m4_bmatch([$3], [%locations], [$1], [$2])])
 m4_pushdef([AT_LOCATION_TYPE_IF],
-[m4_bmatch([$3], [%define location_type], [$1], [$2])])
+[m4_bmatch([$3], [%define \(api\.location\.type\|location_type\)], [$1], 
[$2])])
 m4_pushdef([AT_PARAM_IF],
 [m4_bmatch([$3], [%parse-param], [$1], [$2])])
 m4_pushdef([AT_PURE_IF],
-- 
1.7.12.2