I pushed these to master and something similar to branch-2.5. >From f1b238df182101b9c9d3808bf2d5e2333e27c50f Mon Sep 17 00:00:00 2001 From: Joel E. Denny <[email protected]> Date: Sun, 19 Dec 2010 22:14:08 -0500 Subject: [PATCH 1/2] doc: cleanup.
* NEWS (2.5): Make some minor improvements to wording, and format entries more consistently. * doc/bison.texinfo (Language and Grammar): Point out that IELR and canonical LR are experimental features. (Decl Summary): In list of %define variables, make wording more consistent. Improve discussion of using LALR for GLR. --- ChangeLog | 10 ++++++++++ NEWS | 44 ++++++++++++++++++++++---------------------- doc/bison.texinfo | 20 ++++++++++++-------- 3 files changed, 44 insertions(+), 30 deletions(-) diff --git a/ChangeLog b/ChangeLog index aac9e77..488b280 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,15 @@ 2010-12-19 Joel E. Denny <[email protected]> + doc: cleanup. + * NEWS (2.5): Make some minor improvements to wording, and format + entries more consistently. + * doc/bison.texinfo (Language and Grammar): Point out that IELR + and canonical LR are experimental features. + (Decl Summary): In list of %define variables, make wording more + consistent. Improve discussion of using LALR for GLR. + +2010-12-19 Joel E. Denny <[email protected]> + parse.lac: document. * NEWS (2.5): Add entry for LAC, and mention LAC in entry for other corrections to verbose syntax error messages. diff --git a/NEWS b/NEWS index 5b763b9..9981400 100644 --- a/NEWS +++ b/NEWS @@ -62,7 +62,7 @@ Bison News * Changes in version 2.5 (????-??-??): -** Named References Support +** Named references: Historically, Yacc and Bison have supported positional references ($n, $$) to allow access to symbol values from inside of semantic @@ -87,13 +87,13 @@ Bison News These features are experimental in this version. More user feedback will help to stabilize them. -** IELR(1) and Canonical LR(1) Support +** IELR(1) and canonical LR(1): IELR(1) is a minimal LR(1) parser table generation algorithm. That is, given any context-free grammar, IELR(1) generates parser tables with the full language recognition power of canonical LR(1) but with - nearly the same number of parser states as LALR(1). This reduction in - parser states is often an order of magnitude. More importantly, + nearly the same number of parser states as LALR(1). This reduction + in parser states is often an order of magnitude. More importantly, because canonical LR(1)'s extra parser states may contain duplicate conflicts in the case of non-LR(1) grammars, the number of conflicts for IELR(1) is often an order of magnitude less as well. This can @@ -157,15 +157,15 @@ Bison News LAC is an experimental feature. More user feedback will help to stabilize it. -** Unrecognized %code qualifiers are now an error not a warning. +** Unrecognized %code qualifiers are now errors not warnings. -** %define improvements. +** %define improvements: -*** Unrecognized variables are now an error not a warning. +*** Unrecognized variables are now errors not warnings. *** Multiple invocations for any variable is now an error not a warning. -*** Can now be invoked via the command line. +*** Can now be invoked via the command line: Each of these command-line options @@ -184,7 +184,7 @@ Bison News quietly override %define, but -D and --define do not. For further details, see the section "Bison Options" in the Bison manual. -*** Variables renamed. +*** Variables renamed: The following %define variables @@ -199,7 +199,7 @@ Bison News The old names are now deprecated but will be maintained indefinitely for backward compatibility. -*** Values no longer need to be quoted in grammar file. +*** Values no longer need to be quoted in grammar file: If a %define value is an identifier, it no longer needs to be placed within quotations marks. For example, @@ -210,15 +210,15 @@ Bison News %define api.push-pull push -** Symbol names. +** Grammar symbol names can now contain dashes: Consistently with directives (such as %error-verbose) and variables - (e.g. push-pull), symbol names may include dashes in any position, - similarly to periods and underscores. This is GNU extension over - POSIX Yacc whose use is reported by -Wyacc, and rejected in Yacc - mode (--yacc). + (e.g. push-pull), grammar symbol names may include dashes in any + position, similarly to periods and underscores. This is GNU + extension over POSIX Yacc whose use is reported by -Wyacc, and + rejected in Yacc mode (--yacc). -** YYFAIL now produces warnings and Java parsers no longer implement it. +** YYFAIL now produces warnings and Java parsers no longer implement it: YYFAIL has existed for many years as an undocumented feature of deterministic parsers in C generated by Bison. More recently, it was @@ -229,7 +229,7 @@ Bison News discussion of how to suppress C preprocessor warnings about YYFAIL being unused, see the Bison 2.4.2 NEWS entry. -** Temporary hack for adding a semicolon to the user action. +** Temporary hack for adding a semicolon to the user action: Previously, Bison appended a semicolon to every user action for reductions when the output language defaulted to C (specifically, when @@ -250,7 +250,7 @@ Bison News about a missing semicolon where it did not before. Future releases of Bison will cease to append semicolons entirely. -** Character literals not of length one. +** Character literals not of length one: Previously, Bison quietly converted all character literals to length one. For example, without warning, Bison interpreted the operators in @@ -261,7 +261,7 @@ Bison News ; Bison now warns when a character literal is not of length one. In - some future release, Bison will report an error instead. + some future release, Bison will start reporting an error instead. ** Verbose syntax error message fixes: @@ -301,14 +301,14 @@ Bison News canonical LR. However, LAC is still experimental and is disabled by default. -** Destructor calls fixed for lookaheads altered in semantic actions. +** Destructor calls fixed for lookaheads altered in semantic actions: Previously for deterministic parsers in C, if a user semantic action altered yychar, the parser in some cases used the old yychar value to determine which destructor to call for the lookahead upon a syntax error or upon parser return. This bug has been fixed. -** C++ parsers use YYRHSLOC +** C++ parsers use YYRHSLOC: Similarly to the C parsers, the C++ parsers now define the YYRHSLOC macro and use it in the default YYLLOC_DEFAULT. You are encouraged @@ -343,7 +343,7 @@ Bison News } \ while (false) -** YYLLOC_DEFAULT in C++ +** YYLLOC_DEFAULT in C++: The default implementation of YYLLOC_DEFAULT used to be issued in the header file. It is now output in the implementation file, after diff --git a/doc/bison.texinfo b/doc/bison.texinfo index 2d96352..43ab12b 100644 --- a/doc/bison.texinfo +++ b/doc/bison.texinfo @@ -477,8 +477,8 @@ For historical reasons, Bison by default is limited by the additional restrictions of @acronym{LALR}(1), which is hard to explain simply. @xref{Mystery Conflicts, ,Mysterious Reduce/Reduce Conflicts}, for more information on this. -To escape these additional restrictions, you can request -...@acronym{ielr}(1) or canonical @acronym{LR}(1) parser tables. +As an experimental feature, you can escape these additional restrictions by +requesting @acronym{IELR}(1) or canonical @acronym{LR}(1) parser tables. @xref{Decl Summary,,lr.type}, to learn how. @cindex @acronym{GLR} parsing @@ -5077,7 +5077,7 @@ Some of the accepted @var{variable}s are: @itemize @item Languages(s): C++ -...@item Purpose: Specifies the namespace for the parser class. +...@item Purpose: Specify the namespace for the parser class. For example, if you specify: @smallexample @@ -5150,7 +5150,7 @@ The parser namespace is @code{foo} and @code{yylex} is referenced as @itemize @bullet @item Language(s): C (deterministic parsers only) -...@item Purpose: Requests a pull parser, a push parser, or both. +...@item Purpose: Request a pull parser, a push parser, or both. @xref{Push Decl, ,A Push Parser}. (The current push parsing interface is experimental and may evolve. More user feedback will help to stabilize it.) @@ -5302,8 +5302,8 @@ That is, it does not perform any extra reductions. @itemize @bullet @item Language(s): all -...@item Purpose: Requests that Bison allow unreachable parser states to remain in -the parser tables. +...@item Purpose: Request that Bison allow unreachable parser states to +remain in the parser tables. Bison considers a state to be unreachable if there exists no sequence of transitions from the start state to that state. A state can become unreachable during conflict resolution if Bison disables a @@ -5351,7 +5351,7 @@ However, Bison does not compute which goto actions are useless. @itemize @bullet @item Language(s): all -...@item Purpose: Specifies the type of parser tables within the +...@item Purpose: Specify the type of parser tables within the @acronym{LR}(1) family. (This feature is experimental. More user feedback will help to stabilize it.) @@ -5378,6 +5378,10 @@ In this case, the use of @acronym{LALR} parser tables is guaranteed not to alter the language accepted by the parser. @acronym{LALR} parser tables are the smallest parser tables Bison can currently generate, so they may be preferable. +Nevertheless, once you begin to resolve conflicts statically, +...@acronym{glr} begins to behave more like a deterministic parser, and so +...@acronym{ielr} and canonical @acronym{LR} can be helpful to avoid +...@acronym{lalr}'s mysterious behavior. @item Occasionally during development, an especially malformed grammar with a major recurring flaw may severely impede the @acronym{IELR} or @@ -5590,7 +5594,7 @@ is not already defined, so that the debugging facilities are compiled. C++ @item Purpose: -Requests variant-based semantic values. +Request variant-based semantic values. @xref{C++ Variants}. @item Accepted Values: -- 1.7.0.4 >From d397d9f08cc963c5b90ce62549498b82bf499cc1 Mon Sep 17 00:00:00 2001 From: Joel E. Denny <[email protected]> Date: Sun, 19 Dec 2010 22:15:57 -0500 Subject: [PATCH 2/2] doc: cleanup. * NEWS (2.5): Try to sort entries according to how interesting users might find them. --- ChangeLog | 6 +++ NEWS | 146 ++++++++++++++++++++++++++++++------------------------------ 2 files changed, 79 insertions(+), 73 deletions(-) diff --git a/ChangeLog b/ChangeLog index 488b280..ba2b3af 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,6 +1,12 @@ 2010-12-19 Joel E. Denny <[email protected]> doc: cleanup. + * NEWS (2.5): Try to sort entries according to how interesting + users might find them. + +2010-12-19 Joel E. Denny <[email protected]> + + doc: cleanup. * NEWS (2.5): Make some minor improvements to wording, and format entries more consistently. * doc/bison.texinfo (Language and Grammar): Point out that IELR diff --git a/NEWS b/NEWS index 9981400..576d8cd 100644 --- a/NEWS +++ b/NEWS @@ -157,13 +157,15 @@ Bison News LAC is an experimental feature. More user feedback will help to stabilize it. -** Unrecognized %code qualifiers are now errors not warnings. - -** %define improvements: +** Grammar symbol names can now contain dashes: -*** Unrecognized variables are now errors not warnings. + Consistently with directives (such as %error-verbose) and variables + (e.g. push-pull), grammar symbol names may include dashes in any + position, similarly to periods and underscores. This is GNU + extension over POSIX Yacc whose use is reported by -Wyacc, and + rejected in Yacc mode (--yacc). -*** Multiple invocations for any variable is now an error not a warning. +** %define improvements: *** Can now be invoked via the command line: @@ -210,13 +212,73 @@ Bison News %define api.push-pull push -** Grammar symbol names can now contain dashes: +*** Unrecognized variables are now errors not warnings. - Consistently with directives (such as %error-verbose) and variables - (e.g. push-pull), grammar symbol names may include dashes in any - position, similarly to periods and underscores. This is GNU - extension over POSIX Yacc whose use is reported by -Wyacc, and - rejected in Yacc mode (--yacc). +*** Multiple invocations for any variable is now an error not a warning. + +** Unrecognized %code qualifiers are now errors not warnings. + +** Character literals not of length one: + + Previously, Bison quietly converted all character literals to length + one. For example, without warning, Bison interpreted the operators in + the following grammar to be the same token: + + exp: exp '++' + | exp '+' exp + ; + + Bison now warns when a character literal is not of length one. In + some future release, Bison will start reporting an error instead. + +** Destructor calls fixed for lookaheads altered in semantic actions: + + Previously for deterministic parsers in C, if a user semantic action + altered yychar, the parser in some cases used the old yychar value to + determine which destructor to call for the lookahead upon a syntax + error or upon parser return. This bug has been fixed. + +** C++ parsers use YYRHSLOC: + + Similarly to the C parsers, the C++ parsers now define the YYRHSLOC + macro and use it in the default YYLLOC_DEFAULT. You are encouraged + to use it. If, for instance, your location structure has "first" + and "last" members, instead of + + # define YYLLOC_DEFAULT(Current, Rhs, N) \ + do \ + if (N) \ + { \ + (Current).first = (Rhs)[1].location.first; \ + (Current).last = (Rhs)[N].location.last; \ + } \ + else \ + { \ + (Current).first = (Current).last = (Rhs)[0].location.last; \ + } \ + while (false) + + use: + + # define YYLLOC_DEFAULT(Current, Rhs, N) \ + do \ + if (N) \ + { \ + (Current).first = YYRHSLOC (Rhs, 1).first; \ + (Current).last = YYRHSLOC (Rhs, N).last; \ + } \ + else \ + { \ + (Current).first = (Current).last = YYRHSLOC (Rhs, 0).last; \ + } \ + while (false) + +** YYLLOC_DEFAULT in C++: + + The default implementation of YYLLOC_DEFAULT used to be issued in + the header file. It is now output in the implementation file, after + the user %code sections so that its #ifndef guard does not try to + override the user's YYLLOC_DEFAULT if provided. ** YYFAIL now produces warnings and Java parsers no longer implement it: @@ -250,19 +312,6 @@ Bison News about a missing semicolon where it did not before. Future releases of Bison will cease to append semicolons entirely. -** Character literals not of length one: - - Previously, Bison quietly converted all character literals to length - one. For example, without warning, Bison interpreted the operators in - the following grammar to be the same token: - - exp: exp '++' - | exp '+' exp - ; - - Bison now warns when a character literal is not of length one. In - some future release, Bison will start reporting an error instead. - ** Verbose syntax error message fixes: When %error-verbose or `#define YYERROR_VERBOSE' is specified, @@ -301,55 +350,6 @@ Bison News canonical LR. However, LAC is still experimental and is disabled by default. -** Destructor calls fixed for lookaheads altered in semantic actions: - - Previously for deterministic parsers in C, if a user semantic action - altered yychar, the parser in some cases used the old yychar value to - determine which destructor to call for the lookahead upon a syntax - error or upon parser return. This bug has been fixed. - -** C++ parsers use YYRHSLOC: - - Similarly to the C parsers, the C++ parsers now define the YYRHSLOC - macro and use it in the default YYLLOC_DEFAULT. You are encouraged - to use it. If, for instance, your location structure has "first" - and "last" members, instead of - - # define YYLLOC_DEFAULT(Current, Rhs, N) \ - do \ - if (N) \ - { \ - (Current).first = (Rhs)[1].location.first; \ - (Current).last = (Rhs)[N].location.last; \ - } \ - else \ - { \ - (Current).first = (Current).last = (Rhs)[0].location.last; \ - } \ - while (false) - - use: - - # define YYLLOC_DEFAULT(Current, Rhs, N) \ - do \ - if (N) \ - { \ - (Current).first = YYRHSLOC (Rhs, 1).first; \ - (Current).last = YYRHSLOC (Rhs, N).last; \ - } \ - else \ - { \ - (Current).first = (Current).last = YYRHSLOC (Rhs, 0).last; \ - } \ - while (false) - -** YYLLOC_DEFAULT in C++: - - The default implementation of YYLLOC_DEFAULT used to be issued in - the header file. It is now output in the implementation file, after - the user %code sections so that its #ifndef guard does not try to - override the user's YYLLOC_DEFAULT if provided. - * Changes in version 2.4.3 (2010-08-05): ** Bison now obeys -Werror and --warnings=error for warnings about -- 1.7.0.4
