Don't apply the default %destructor/%printer to an unreferenced midrule

[bison.git] / NEWS

diff --git a/NEWS b/NEWS
index d841db6f6fa6205e4b8cc1d648fe25f61c7ef180..75e0284ffaae4a4095637ee216f8147ef9a0d667 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -1,7 +1,113 @@
 Bison News
 ----------
 
 Bison News
 ----------
 

-Changes in version 2.3+:
+Changes in version 2.3a+ (????-??-??):
+
+* The -g and --graph options now output graphs in Graphviz DOT format,
+  not VCG format.
+
+* The Yacc prologue alternatives from Bison 2.3a have been rewritten as the
+  following directives:
+
+    1. %code {CODE}
+
+       Other than semantic actions, this is probably the most common place you
+       should write verbatim code for the parser implementation.  For C/C++, it
+       replaces the traditional Yacc prologue, `%{CODE%}', for most purposes.
+       For Java, it inserts your CODE into the parser class.  Compare with:
+
+         - `%{CODE%}' appearing after the first `%union {CODE}' in a C/C++
+           based grammar file.  While Bison will continue to support `%{CODE%}'
+           for backward compatibility, `%code {CODE}' is cleaner as its
+           functionality does not depend on its position in the grammar file
+           relative to any `%union {CODE}'.  Specifically, `%code {CODE}'
+           always inserts your CODE into the parser code file after the usual
+           contents of the parser header file.
+         - `%after-header {CODE}', which only Bison 2.3a supported.
+
+    2. %requires {CODE}
+
+       This is the right place to write dependency code for externally exposed
+       definitions required by Bison.  For C/C++, such exposed definitions are
+       those usually appearing in the parser header file.  Thus, this is the
+       right place to define types referenced in `%union {CODE}' directives,
+       and it is the right place to override Bison's default YYSTYPE and
+       YYLTYPE definitions.  For Java, this is the right place to write import
+       directives.  Compare with:
+
+         - `%{CODE%}' appearing before the first `%union {CODE}' in a C/C++
+           based grammar file.  Unlike `%{CODE%}', `%requires {CODE}' inserts
+           your CODE both into the parser code file and into the parser header
+           file since Bison's required definitions should depend on it in both
+           places.
+         - `%start-header {CODE}', which only Bison 2.3a supported.
+
+    3. %provides {CODE}
+    
+       This is the right place to write additional definitions you would like
+       Bison to expose externally.  For C/C++, this directive inserts your CODE
+       both into the parser header file and into the parser code file after
+       Bison's required definitions.  For Java, it inserts your CODE into the
+       parser java file after the parser class.  Compare with:
+
+         - `%end-header {CODE}', which only Bison 2.3a supported.
+
+    4. %code-top {CODE}
+
+       Occasionally for C/C++ it is desirable to insert code near the top of
+       the parser code file.  For example:
+
+         %code-top {
+           #define _GNU_SOURCE
+           #include <stdio.h>
+         }
+
+       For Java, `%code-top {CODE}' is currently unused.  Compare with:
+
+         - `%{CODE%}' appearing before the first `%union {CODE}' in a C/C++
+           based grammar file.  `%code-top {CODE}' is cleaner as its
+           functionality does not depend on its position in the grammar file
+           relative to any `%union {CODE}'.
+         - `%before-header {CODE}', which only Bison 2.3a supported.
+
+  If you have multiple occurrences of any one of the above four directives,
+  Bison will concatenate the contents in the order they appear in the grammar
+  file.
+
+  Also see the new section `Prologue Alternatives' in the Bison manual.
+
+Changes in version 2.3a, 2006-09-13:
+
+* Instead of %union, you can define and use your own union type
+  YYSTYPE if your grammar contains at least one <type> tag.
+  Your YYSTYPE need not be a macro; it can be a typedef.
+  This change is for compatibility with other Yacc implementations,
+  and is required by POSIX.
+
+* Locations columns and lines start at 1.
+  In accordance with the GNU Coding Standards and Emacs.
+
+* You may now declare per-type and default %destructor's and %printer's:
+
+  For example:
+
+    %union { char *string; }
+    %token <string> STRING1
+    %token <string> STRING2
+    %type  <string> string1
+    %type  <string> string2
+    %union { char character; }
+    %token <character> CHR
+    %type  <character> chr
+    %destructor { free ($$); } %symbol-default
+    %destructor { free ($$); printf ("%d", @$.first_line); } STRING1 string1
+    %destructor { } <character>
+
+  guarantees that, when the parser discards any user-defined symbol that has a
+  semantic type tag other than `<character>', it passes its semantic value to
+  `free'.  However, when the parser discards a `STRING1' or a `string1', it
+  also prints its line number to `stdout'.  It performs only the second
+  `%destructor' in this case, so it invokes `free' only once.

 
 * Except for LALR(1) parsers in C with POSIX Yacc emulation enabled (with `-y',
   `--yacc', or `%yacc'), Bison no longer generates #define statements for
 
 * Except for LALR(1) parsers in C with POSIX Yacc emulation enabled (with `-y',
   `--yacc', or `%yacc'), Bison no longer generates #define statements for


@@ -9,18 +115,16 @@ Changes in version 2.3+:
   helps to sanitize the global namespace during preprocessing, but POSIX Yacc
   requires them.  Bison still generates an enum for token names in all cases.
 
   helps to sanitize the global namespace during preprocessing, but POSIX Yacc
   requires them.  Bison still generates an enum for token names in all cases.
 

-* Handling of prologue blocks is now more consistent but potentially backward
-  incompatible.
+* Handling of traditional Yacc prologue blocks is now more consistent but
+  potentially incompatible with previous releases of Bison.

 
   As before, you declare prologue blocks in your grammar file with the
   `%{ ... %}' syntax.  To generate the pre-prologue, Bison concatenates all
 
   As before, you declare prologue blocks in your grammar file with the
   `%{ ... %}' syntax.  To generate the pre-prologue, Bison concatenates all

-  prologue blocks that you've declared before any %union.  If you've declared a
-  %union, Bison concatenates all prologue blocks that you've declared after it
-  to generate the post-prologue.  (The new %before-definitions and
-  %after-definitions have a similar effect as %union on the prologues.  See
-  below.)
+  prologue blocks that you've declared before the first %union.  To generate
+  the post-prologue, Bison concatenates all prologue blocks that you've
+  declared after the first %union.

 
 

-  Previous versions of Bison inserted the pre-prologue into both the header
+  Previous releases of Bison inserted the pre-prologue into both the header

   file and the code file in all cases except for LALR(1) parsers in C.  In the
   latter case, Bison inserted it only into the code file.  For parsers in C++,
   the point of insertion was before any token definitions (which associate
   file and the code file in all cases except for LALR(1) parsers in C.  In the
   latter case, Bison inserted it only into the code file.  For parsers in C++,
   the point of insertion was before any token definitions (which associate


@@ -30,38 +134,50 @@ Changes in version 2.3+:
   Now, Bison never inserts the pre-prologue into the header file.  In the code
   file, it always inserts it before the token definitions.
 
   Now, Bison never inserts the pre-prologue into the header file.  In the code
   file, it always inserts it before the token definitions.
 

-* Bison now provides the %before-definitions and %after-definitions directives.
-
-  For example, in your grammar file:
-
-    %{
-      /* A pre-prologue block.  For Yacc portability, Bison no longer puts this
-       * in the header file.  In the code file, Bison inserts it before any
-       * %before-definitions blocks.  */
-    %}
-    %before-definitions {
-      /* Bison inserts this into both the header file and code file.  In both
-       * files, the point of insertion is before any Bison-generated token,
-       * semantic type, location type, and class definitions.  This is a good
-       * place to define %union dependencies, for example.  */
+* Bison now provides a more flexible alternative to the traditional Yacc
+  prologue blocks: %before-header, %start-header, %end-header, and
+  %after-header.
+
+  For example, the following declaration order in the grammar file reflects the
+  order in which Bison will output these code blocks.  However, you are free to
+  declare these code blocks in your grammar file in whatever order is most
+  convenient for you:
+
+    %before-header {
+      /* Bison treats this block like a pre-prologue block: it inserts it into
+       * the code file before the contents of the header file.  It does *not*
+       * insert it into the header file.  This is a good place to put
+       * #include's that you want at the top of your code file.  A common
+       * example is `#include "system.h"'.  */
+    }
+    %start-header {
+      /* Bison inserts this block into both the header file and the code file.
+       * In both files, the point of insertion is before any Bison-generated
+       * token, semantic type, location type, and class definitions.  This is a
+       * good place to define %union dependencies, for example.  */

     }
     %union {
     }
     %union {

-      /* With previous versions of Bison, the first %union in your grammar file
-       * separated the pre-prologue blocks from the post-prologue blocks.  Now,
-       * the first %union, %before-definitions, or %after-definitions does
-       * that.  */
+      /* Unlike the traditional Yacc prologue blocks, the output order for the
+       * new %*-header blocks is not affected by their declaration position
+       * relative to any %union in the grammar file.  */

     }
     }

-    %after-definitions {
-      /* If you want something in the header file and in the code file and it
-       * depends on any of the Bison-generated definitions in the header file,
-       * put it here.  */
+    %end-header {
+      /* Bison inserts this block into both the header file and the code file.
+       * In both files, the point of insertion is after the Bison-generated
+       * definitions.  This is a good place to declare or define public
+       * functions or data structures that depend on the Bison-generated
+       * definitions.  */

     }
     }

-    %{
-      /* A post-prologue block.  If you want something in the code file but not
-       * in the header file and it depends on Bison-generated definitions, put
-       * it here.  In the code file, Bison inserts it after any
-       * %after-definitions blocks.  */
-    %}
+    %after-header {
+      /* Bison treats this block like a post-prologue block: it inserts it into
+       * the code file after the contents of the header file.  It does *not*
+       * insert it into the header file.  This is a good place to declare or
+       * define internal functions or data structures that depend on the
+       * Bison-generated definitions.  */
+    }
+
+  If you have multiple occurrences of any one of the above declarations, Bison
+  will concatenate the contents in declaration order.

 
 * The option `--report=look-ahead' has been changed to `--report=lookahead'.
   The old spelling still works, but is not documented and may be removed
 
 * The option `--report=look-ahead' has been changed to `--report=lookahead'.
   The old spelling still works, but is not documented and may be removed