Re: [PATCH 0/5] Revamp the parsing of symbol declarations

[Akim Demaille]

> Le 16 déc. 2018 à 10:45, Akim Demaille <address@hidden> a écrit :
> 
> Hi Rici,
> 
> I'm almost done with this issue (there remains to update the doc and
> NEWS, more -Wyacc warnings).

commit 1099b8dc2601358b0469b964d64ccf48e8f36fdf
Author: Akim Demaille <address@hidden>
Date:   Sun Dec 16 17:02:49 2018 +0100

    symbols: document the overhaul of symbol declarations
    
    * doc/bison.texi (Symbol Decls): New.

diff --git a/NEWS b/NEWS
index b62141f1..bb06934f 100644
--- a/NEWS
+++ b/NEWS
@@ -159,8 +159,30 @@ GNU Bison NEWS
 
 ** Changes
 
-  The C++ output now use noexcept and constexpr.  Please, report missing
-  annotations.
+*** Parsers in C++
+
+  They now use noexcept and constexpr.  Please, report missing annotations.
+
+*** Symbol Declarations
+
+  The syntax of the variation directives to declare symbols was overhauled
+  for more consistency, and also better POSIX Yacc compliance (which, for
+  instance, allows "%type" without actually providing a type).  The %nterm
+  directive, supported by Bison since its inception, is now documented and
+  officially supported.
+
+  The syntax is now as follows:
+
+    %token TAG? ( ID NUMBER? STRING? )+ ( TAG ( ID NUMBER? STRING? )+ )*
+    %left  TAG? ( ID NUMBER?)+ ( TAG ( ID NUMBER? )+ )*
+    %type  TAG? ( ID | CHAR | STRING )+ ( TAG ( ID | CHAR | STRING )+ )*
+    %nterm TAG? ID+ ( TAG ID+ )*
+
+  where TAG denotes a type tag such as ‘<ival>’, ID denotes an identifier
+  such as ‘NUM’, NUMBER a decimal or hexadecimal integer such as ‘300’ or
+  ‘0x12d’, CHAR a character literal such as ‘'+'’, and STRING a string
+  literal such as ‘"number"’.  The postfix quantifiers are ‘?’ (zero or
+  one), ‘*’ (zero or more) and ‘+’ (one or more).
 
 * Noteworthy changes in release 3.2.2 (2018-11-21) [stable]
 
diff --git a/doc/bison.texi b/doc/bison.texi
index b8a62189..89283be7 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -239,6 +239,7 @@ Bison Declarations
 * Token Decl::        Declaring terminal symbols.
 * Precedence Decl::   Declaring terminals with precedence and associativity.
 * Type Decl::         Declaring the choice of type for a nonterminal symbol.
+* Symbol Decls::      Summary of the Syntax of Symbol Declarations.
 * Initial Action Decl::  Code run before parsing starts.
 * Destructor Decl::   Declaring how symbols are freed.
 * Printer Decl::      Declaring how symbol values are displayed.
@@ -4757,6 +4758,7 @@ and Context-Free Grammars}).
 * Token Decl::        Declaring terminal symbols.
 * Precedence Decl::   Declaring terminals with precedence and associativity.
 * Type Decl::         Declaring the choice of type for a nonterminal symbol.
+* Symbol Decls::      Summary of the Syntax of Symbol Declarations.
 * Initial Action Decl::  Code run before parsing starts.
 * Destructor Decl::   Declaring how symbols are freed.
 * Printer Decl::      Declaring how symbol values are displayed.
@@ -4804,7 +4806,7 @@ The basic way to declare a token type name (terminal 
symbol) is as follows:
 %token @var{name}
 @end example
 
-Bison will convert this into a @code{#define} directive in the parser, so
+Bison will convert this into a definition in the parser, so
 that the function @code{yylex} (if it is in this file) can use the name
 @var{name} to stand for this token type's code.
 
@@ -4945,6 +4947,7 @@ a separate token.  For example:
 @subsection Nonterminal Symbols
 @cindex declaring value types, nonterminals
 @cindex value types, nonterminals, declaring
address@hidden %nterm
 @findex %type
 
 @noindent
@@ -4963,9 +4966,40 @@ is the name given in the @code{%union} to the 
alternative that you want
 nonterminal symbols in the same @code{%type} declaration, if they have the
 same value type.  Use spaces to separate the symbol names.
 
-You can also declare the value type of a terminal symbol.  To do this, use
-the same @code{<@var{type}>} construction in a declaration for the terminal
-symbol.  All kinds of token declarations allow @code{<@var{type}>}.
+While POSIX Yacc allows @code{%type} only for nonterminals, Bison accepts
+that this directive be also applied to terminal symbols.  To declare
+exclusively nonterminal symbols, use @code{%nterm}:
+
address@hidden
+%nterm <@var{type}> @address@hidden
address@hidden example
+
address@hidden Symbol Decls
address@hidden Syntax of Symbol Declarations
address@hidden %left
address@hidden %nterm
address@hidden %token
address@hidden %type
+
+The syntax of the various directives to declare symbols is as follows.
+
address@hidden
+%token @var{tag}? ( @var{id} @var{number}? @var{string}? )+ ( @var{tag} ( 
@var{id} @var{number}? @var{string}? )+ )*
+%left  @var{tag}? ( @var{id} @var{number}?)+ ( @var{tag} ( @var{id} 
@var{number}? )+ )*
+%type  @var{tag}? ( @var{id} | @var{char} | @var{string} )+ ( @var{tag} ( 
@var{id} | @var{char} | @var{string} )+ )*
+%nterm @var{tag}? @var{id}+ ( @var{tag} @var{id}+ )*
address@hidden example
+
address@hidden
+where @var{tag} denotes a type tag such as @samp{<ival>}, @var{id} denotes
+an identifier such as @samp{NUM}, @var{number} a decimal or hexadecimal
+integer such as @samp{300} or @samp{0x12d}, @var{char} a character literal
+such as @samp{'+'}, and @var{string} a string literal such as
address@hidden"number"}.  The postfix quantifiers are @samp{?} (zero or one),
address@hidden (zero or more) and @samp{+} (one or more).
+
+The directives @code{%precedence}, @code{%right} and @code{%nonassoc} behave
+like @code{%left}.
 
 @node Initial Action Decl
 @subsection Performing Actions before Parsing
@@ -5522,9 +5556,14 @@ Assign a precedence to rules lacking an explicit 
@code{%prec} modifier
 @end deffn
 @end ifset
 
address@hidden {Directive} %nterm
+Declare the type of semantic values for a nonterminal symbol (@pxref{Type
+Decl, ,Nonterminal Symbols}).
address@hidden deffn
+
 @deffn {Directive} %type
-Declare the type of semantic values for a nonterminal symbol
-(@pxref{Type Decl, ,Nonterminal Symbols}).
+Declare the type of semantic values for a symbol (@pxref{Type Decl,
+,Nonterminal Symbols}).
 @end deffn
 
 @deffn {Directive} %start
@@ -13439,6 +13478,11 @@ Bison declaration to assign precedence and 
nonassociativity to token(s).
 @xref{Precedence Decl, ,Operator Precedence}.
 @end deffn
 
address@hidden {Directive} %nterm
+Bison declaration to declare nonterminals.  @xref{Type Decl, ,Nonterminal
+Symbols}.
address@hidden deffn
+
 @deffn {Directive} %output "@var{file}"
 Bison declaration to set the name of the parser implementation file.
 @xref{Decl Summary}.
@@ -13502,7 +13546,7 @@ implementation file.  @xref{Decl Summary}.
 @end deffn
 
 @deffn {Directive} %type
-Bison declaration to declare nonterminals.  @xref{Type Decl,
+Bison declaration to declare symbol value types.  @xref{Type Decl,
 ,Nonterminal Symbols}.
 @end deffn