From 413d318940b4c12d37bd3ff5e728bae2f7a100f0 Mon Sep 17 00:00:00 2001
From: Akim Demaille <akim.demaille@gmail.com>
Date: Wed, 4 Aug 2021 09:06:56 +0200
Subject: [PATCH] doc: glr: document typed mergers

See <https://lists.gnu.org/r/help-bison/2020-12/msg00016.html>.

* doc/bison.texi (Merging GLR Parses): document typed mergers.
And avoid #define YYSTYPE.
---
 TODO           |  9 ---------
 doc/bison.texi | 46 ++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 44 insertions(+), 11 deletions(-)

diff --git a/TODO b/TODO
index 52c595dd..2e66eeec 100644
--- a/TODO
+++ b/TODO
@@ -28,15 +28,6 @@ the out-of-range new values, we need something like doubling the size.
 ** glr
 There is no test with "Parse on stack %ld rejected by rule %d" in it.
 
-** %merge
-Tests with typed %merge: 716 717 718 740 741 742 746 747 748
-
-716: Duplicate representation of merged trees: glr.c FAILED (glr-regression.at:517)
-740: Leaked semantic values if user action cuts parse: glr.c FAILED (glr-regression.at:1230)
-746: Incorrect lookahead during nondeterministic GLR: glr.c FAILED (glr-regression.at:1610)
-
-Document typed merges.
-
 ** yyrline etc.
 Clarify that rule numbers in the skeletons are 1-based.
 
diff --git a/doc/bison.texi b/doc/bison.texi
index e2cd1525..f73cc819 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -1167,11 +1167,12 @@ Let's consider an example, vastly simplified from a C++ grammar.
 @example
 %@{
   #include <stdio.h>
-  #define YYSTYPE char const *
   int yylex (void);
   void yyerror (char const *);
 %@}
 
+%define api.value.type @{char const *@}
+
 %token TYPENAME ID
 
 %right '='
@@ -1302,7 +1303,6 @@ in the C declarations at the beginning of the file:
 
 @example
 %@{
-  #define YYSTYPE char const *
   static YYSTYPE stmtMerge (YYSTYPE x0, YYSTYPE x1);
 %@}
 @end example
@@ -1321,6 +1321,48 @@ productions that participate in any particular merge have identical
 and the parser will report an error during any parse that results in
 the offending merge.
 
+@sp 1
+
+The signature of the merger depends on the type of the symbol.  In the
+previous example, the merged-to symbol (@code{stmt}) does not have a
+specific type, and the merger is
+
+@example
+YYSTYPE stmtMerge (YYSTYPE x0, YYSTYPE x1);
+@end example
+
+@noindent
+However, if @code{stmt} had a declared type, e.g.,
+
+@example
+%type <Node *> stmt;
+@end example
+
+@noindent
+or
+
+@example
+@group
+%union @{
+  Node *node;
+  ...
+@};
+@end group
+%type <node> stmt;
+@end example
+
+@noindent
+then the prototype of the merger must be:
+
+@example
+Node *stmtMerge (YYSTYPE x0, YYSTYPE x1);
+@end example
+
+@noindent
+(This signature might be a mistake originally, and maybe it should have been
+@samp{Node *stmtMerge (Node *x0, Node *x1)}.  If you have an opinion about
+it, please let us know.)
+
 @node GLR Semantic Actions
 @subsection GLR Semantic Actions