[PATCH 6/6] doc: api.value.type union.

[Akim Demaille]

* doc/bison.texi (Type Generation): New section.
---
 doc/bison.texi | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/doc/bison.texi b/doc/bison.texi
index aa49ce7..04cb773 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -211,6 +211,7 @@ Defining Language Semantics
 
 * Value Type::        Specifying one data type for all semantic values.
 * Multiple Types::    Specifying several alternative data types.
+* Type Generation::   Generating the semantic value type.
 * Union Decl::        Declaring the set of all semantic value types.
 * Structured Value Type::  Providing a structured semantic value type.
 * Actions::           An action is the semantic definition of a grammar rule.
@@ -3639,6 +3640,7 @@ the numbers associated with @var{x} and @var{y}.
 @menu
 * Value Type::        Specifying one data type for all semantic values.
 * Multiple Types::    Specifying several alternative data types.
+* Type Generation::   Generating the semantic value type.
 * Union Decl::        Declaring the set of all semantic value types.
 * Structured Value Type::  Providing a structured semantic value type.
 * Actions::           An action is the semantic definition of a grammar rule.
@@ -3713,6 +3715,9 @@ Specify the entire collection of possible data types.  
There are several
 options:
 @itemize @bullet
 @item
+let Bison compute the union type from the tags you assign to symbols;
+
address@hidden
 use the @code{%union} Bison declaration (@pxref{Union Decl, ,The Union
 Declaration});
 
@@ -3734,6 +3739,56 @@ and for groupings with the @code{%type} Bison 
declaration (@pxref{Type
 Decl, ,Nonterminal Symbols}).
 @end itemize
 
address@hidden Type Generation
address@hidden Generating the Semantic Value Type
address@hidden declaring value types
address@hidden value types, declaring
address@hidden %define api.value.type union
+
+The special value @code{union} of the @code{%define} variable
address@hidden instructs Bison that the tags used with the
address@hidden and @code{%type} directives are genuine types, not names of
+members of @code{YYSTYPE}.
+
+For example:
+
address@hidden
+%define api.value.type union
+%token <int> INT "integer"
+%token <int> 'n'
+%type <int> expr
+%token <char const *> ID "identifier"
address@hidden example
+
address@hidden
+generates an appropriate value of @code{YYSTYPE} to support each symbol
+type.  The name of the member of @code{YYSTYPE} for tokens than have a
+declared identifier @var{id} (such as @code{INT} and @code{ID} above, but
+not @code{'n'}) is @address@hidden  The other symbols have
+unspecified names on which you should not depend; instead, relying on C
+casts to access the semantic value with the appropriate type:
+
address@hidden
+/* For an "integer".  */
+yylval.yytype_INT = 42;
+return INT;
+
+/* For an 'n', also declared as int.  */
+*((int*)&yylval) = 42;
+return 'n';
+
+/* For an "identifier".  */
+yylval.yytype_ID = "42";
+return IDENTIFIER;
address@hidden example
+
+
+This feature is new, and user feedback would be most welcome.
+
+A similar feature is provided for C++ that in addition overcomes C++
+limitations (that forbid non-trivial objects to be part of a @code{union}):
address@hidden api.value.type variant}, see @ref{C++ Variants}.
+
 @node Union Decl
 @subsection The Union Declaration
 @cindex declaring value types
-- 
1.8.1.3