all: display a clear warning about private macros

* data/bison.m4 (b4_disclaimer): New.
* data/glr.c, data/glr.cc, data/lalr1.cc, data/yacc.c: Use it.

NEWS

@@ -2,6 +2,17 @@ GNU Bison NEWS
 
 * Noteworthy changes in release ?.? (????-??-??) [?]
 
+** Implementation details
+
+  A comment in the generated code now emphasizes that users should not
+  depend upon non-documented implementation details, such as macros starting
+  with YY_.
+
+** Changes
+
+  %printers should use yyo rather than yyoutput to denote the output stream.
+
+  Variant-based symbols in C++ should use emplace() rather than build().
 
 * Noteworthy changes in release 3.1.91 (2018-10-18) [beta]
 

data/bison.m4

@@ -58,7 +58,18 @@ Bison output files to be licensed under the GNU General Public
 License without this special exception.
 
 This special exception was added by the Free Software Foundation in
-version 2.2 of Bison.])])
+version 2.2 of Bison.])
+])
+
+
+# b4_disclaimer
+# -------------
+# Issue a warning about private implementation details.
+m4_define([b4_disclaimer],
+[b4_comment([Undocumented macros, especially those whose name start with YY_,
+are private implementation details.  Do not rely on them.])
+])
+
 
 
 # b4_required_version_if(VERSION, IF_NEWER, IF_OLDER)

data/glr.c

@@ -199,7 +199,6 @@ m4_if(b4_skeleton, ["glr.c"],
 [b4_output_begin([b4_spec_defines_file])
 b4_copyright([Skeleton interface for Bison GLR parsers in C],
              [2002-2015, 2018])[
-
 ]b4_cpp_guard_open([b4_spec_defines_file])[
 ]b4_shared_declarations[
 ]b4_cpp_guard_close([b4_spec_defines_file])[
@@ -214,9 +213,9 @@ b4_copyright([Skeleton interface for Bison GLR parsers in C],
 b4_output_begin([b4_parser_file_name])
 b4_copyright([Skeleton implementation for Bison GLR parsers in C],
              [2002-2015, 2018])[
-
 /* C GLR parser skeleton written by Paul Hilfinger.  */
 
+]b4_disclaimer[
 ]b4_identification[
 
 ]b4_percent_code_get([[top]])[

data/glr.cc

@@ -333,9 +333,9 @@ b4_defines_if(
 [b4_output_begin([b4_spec_defines_file])
 b4_copyright([Skeleton interface for Bison GLR parsers in C++],
              [2002-2015, 2018])[
-
 // C++ GLR parser skeleton written by Akim Demaille.
 
+]b4_disclaimer[
 ]b4_cpp_guard_open([b4_spec_defines_file])[
 ]b4_shared_declarations[
 ]b4_cpp_guard_close([b4_spec_defines_file])[

data/lalr1.cc

@@ -392,6 +392,10 @@ m4_define([b4_shared_declarations],
 ]b4_percent_code_get([[provides]])[
 ]])
 
+## -------------- ##
+## Output files.  ##
+## -------------- ##
+
 b4_defines_if(
 [b4_output_begin([b4_spec_defines_file])
 b4_copyright([Skeleton interface for Bison LALR(1) parsers in C++])
@@ -403,6 +407,7 @@ b4_copyright([Skeleton interface for Bison LALR(1) parsers in C++])
 
 // C++ LALR(1) parser skeleton written by Akim Demaille.
 
+]b4_disclaimer[
 ]b4_cpp_guard_open([b4_spec_defines_file])[
 ]b4_shared_declarations(hh)[
 ]b4_cpp_guard_close([b4_spec_defines_file])
@@ -410,9 +415,10 @@ b4_output_end
 ])
 
 
-b4_output_begin([b4_parser_file_name])
+b4_output_begin([b4_parser_file_name])[
-b4_copyright([Skeleton implementation for Bison LALR(1) parsers in C++])
+]b4_copyright([Skeleton implementation for Bison LALR(1) parsers in C++])[
-b4_percent_code_get([[top]])[]dnl
+]b4_disclaimer[
+]b4_percent_code_get([[top]])[]dnl
 m4_if(b4_prefix, [yy], [],
 [
 // Take the name prefix into account.

data/lalr1.java

@@ -82,12 +82,11 @@ m4_define([b4_define_state],[[
     ]b4_yystype[ yylval = null;
 ]])
 
-b4_output_begin([b4_parser_file_name])
+b4_output_begin([b4_parser_file_name])[
-b4_copyright([Skeleton implementation for Bison LALR(1) parsers in Java],
+]b4_copyright([Skeleton implementation for Bison LALR(1) parsers in Java],
-             [2007-2015, 2018])
+             [2007-2015, 2018])[
-
+]b4_percent_define_ifdef([package], [package b4_percent_define_get([package]);[
-b4_percent_define_ifdef([package], [package b4_percent_define_get([package]);
+]])[
-])[
 ]b4_user_pre_prologue[
 ]b4_user_post_prologue[
 ]b4_percent_code_get([[imports]])

data/location.cc

@@ -338,7 +338,6 @@ m4_ifdef([b4_position_file], [[
 m4_ifdef([b4_location_file], [[
 ]b4_output_begin([b4_dir_prefix], [b4_location_file])[
 ]b4_copyright([Locations for Bison parsers in C++])[
-
 /**
  ** \file ]b4_location_path[
  ** Define the ]b4_namespace_ref[::location class.

data/yacc.c

@@ -299,9 +299,8 @@ m4_define([b4_shared_declarations],
 ## Output files.  ##
 ## -------------- ##
 
-b4_output_begin([b4_parser_file_name])
+b4_output_begin([b4_parser_file_name])[
-b4_copyright([Bison implementation for Yacc-like parsers in C])[
+]b4_copyright([Bison implementation for Yacc-like parsers in C])[
-
 /* C LALR(1) parser skeleton written by Richard Stallman, by
    simplifying the original so-called "semantic" parser.  */
 
@@ -312,8 +311,9 @@ b4_copyright([Bison implementation for Yacc-like parsers in C])[
    define necessary library symbols; they are noted "INFRINGES ON
    USER NAME SPACE" below.  */
 
-]b4_identification
+]b4_disclaimer[
-b4_percent_code_get([[top]])[]dnl
+]b4_identification[
+]b4_percent_code_get([[top]])[]dnl
 m4_if(b4_api_prefix, [yy], [],
 [[/* Substitute the type names.  */
 #define YYSTYPE         ]b4_api_PREFIX[STYPE]b4_locations_if([[
@@ -1906,10 +1906,10 @@ yypushreturn:]])[
 ]b4_epilogue[]dnl
 b4_output_end
 
-b4_defines_if(
+b4_defines_if([[
-[b4_output_begin([b4_spec_defines_file])[
+]b4_output_begin([b4_spec_defines_file])[
 ]b4_copyright([Bison interface for Yacc-like parsers in C])[
-
+]b4_disclaimer[
 ]b4_shared_declarations[
-]b4_output_end
+]b4_output_end[
-])# b4_defines_if
+]])# b4_defines_if