From: Akim Demaille <akim@lrde.epita.fr>
Date: Mon, 22 Oct 2012 14:04:12 +0000 (+0200)
Subject: Merge branch '2.6.3' into maint
X-Git-Tag: v2.6.90~54
X-Git-Url: https://git.saurik.com/bison.git/commitdiff_plain/b7226022b07fac385defbf2297892d8c3dc3cd18?hp=-c

Merge branch '2.6.3' into maint

* 2.6.3: (22 commits)
  maint: post-release administrivia
  version 2.6.3
  gnulib: update
  tests: check %no-lines
  NEWS: warnings with clang
  warnings: avoid warnings from clang
  tests: no longer disable -O compiler options
  yacc.c: initialize yylval in pure-parser mode
  skeletons: style changes
  tests: minor improvements
  tests: use $PERL instead of perl
  build: look for Perl in configure.
  tests: fix sed portability issues
  tests: diff -u is not portable
  maint: word changes
  lalr1.cc: fix test suite portability
  maint: fix an erroneous include
  tests: check that headers are self contained
  doc: add missing documentation for --report
  headers: move CPP guards into YY_*_INCLUDED to avoid collisions
  ...

Conflicts:
	NEWS
	doc/bison.texi
	tests/headers.at
---

b7226022b07fac385defbf2297892d8c3dc3cd18
diff --combined NEWS
index d1b66564,083d90a9..0f2446bc
--- a/NEWS
+++ b/NEWS
@@@ -2,97 -2,51 +2,99 @@@ GNU Bison NEW
  
  * Noteworthy changes in release ?.? (????-??-??) [?]
  
- ** Bug fixes
- 
-   Bugs and portability issues in the test suite have been fixed.
- 
-   Some errors in translations have been addressed, and --help now directs
-   users to the appropriate place to report them.
- 
-   Stray Info files shipped by accident are removed.
- 
-   Incorrect definitions of YY_, issued by yacc.c when no parser header is
-   generated, are removed.
- 
-   All the generated headers are self-contained.
- 
 +** Changes in the format of error messages
 +
 +  This used to be the format of many error reports:
 +
 +    foo.y:5.10-24: result type clash on merge function 'merge': <t3> != <t2>
 +    foo.y:4.13-27: previous declaration
 +
 +  It is now:
 +
 +    foo.y:5.10-25: result type clash on merge function 'merge': <t3> != <t2>
 +    foo.y:4.13-27:     previous declaration
 +
- ** Header guards (yacc.c, glr.c, glr.cc)
- 
-   In order to avoid collisions, the header guards are now
-   YY_<PREFIX>_<FILE>_INCLUDED, instead of merely <PREFIX>_<FILE>.
-   For instance the header generated from
- 
-     %define api.prefix "calc"
-     %defines "lib/parse.h"
- 
-   will use YY_CALC_LIB_PARSE_H_INCLUDED as guard.
- 
 +** Exception safety (lalr1.cc)
 +
 +  The parse function now catches exceptions, uses the %destructors to
 +  release memory (the lookahead symbol and the symbols pushed on the stack)
 +  before re-throwing the exception.
 +
 +  This feature is somewhat experimental.  User feedback would be
 +  appreciated.
 +
- ** Fix compiler warnings in the generated parser (yacc.c, glr.c)
- 
-   The compilation of pure parsers (%define api.pure) can trigger GCC
-   warnings such as:
- 
-     input.c: In function 'yyparse':
-     input.c:1503:12: warning: 'yylval' may be used uninitialized in this
-                               function [-Wmaybe-uninitialized]
-        *++yyvsp = yylval;
-                 ^
- 
-   This is now fixed; pragmas to avoid these warnings are no longer needed.
- 
-   Warnings from clang ("equality comparison with extraneous parentheses" and
-   "function declared 'noreturn' should not return") have also been
-   addressed.
- 
 +** New %define variable: api.location.type (glr.cc, lalr1.cc, lalr1.java)
 +
 +  The %define variable api.location.type defines the name of the type to use
 +  for locations.  When defined, Bison no longer generates the position.hh
 +  and location.hh files, nor does the parser will include them: the user is
 +  then responsible to define her type.
 +
 +  This can be used in programs with several parsers to factor their location
 +  and position files: let one of them generate them, and the others just use
 +  them.
 +
 +  This feature was actually introduced, but not documented, in Bison 2.5,
 +  under the name "location_type" (which is maintained for backward
 +  compatibility).
 +
 +  For consistency, lalr1.java's %define variables location_type and
 +  position_type are deprecated in favor of api.location.type and
 +  api.position.type.
 +
 +** Graphviz improvements
 +
 +  The graphical presentation of the states is more readable: their shape is
 +  now rectangular, the state number is clearly displayed, and the items are
 +  numbered and left-justified.
 +
 +  The reductions are now explicitly represented as transitions to other
 +  diamond shaped nodes.
  
+ * Noteworthy changes in release 2.6.3 (2012-10-22) [stable]
+ 
+ ** Bug fixes
+ 
+   Bugs and portability issues in the test suite have been fixed.
+ 
+   Some errors in translations have been addressed, and --help now directs
+   users to the appropriate place to report them.
+ 
+   Stray Info files shipped by accident are removed.
+ 
+   Incorrect definitions of YY_, issued by yacc.c when no parser header is
+   generated, are removed.
+ 
+   All the generated headers are self-contained.
+ 
+ ** Header guards (yacc.c, glr.c, glr.cc)
+ 
+   In order to avoid collisions, the header guards are now
+   YY_<PREFIX>_<FILE>_INCLUDED, instead of merely <PREFIX>_<FILE>.
+   For instance the header generated from
+ 
+     %define api.prefix "calc"
+     %defines "lib/parse.h"
+ 
+   will use YY_CALC_LIB_PARSE_H_INCLUDED as guard.
+ 
+ ** Fix compiler warnings in the generated parser (yacc.c, glr.c)
+ 
+   The compilation of pure parsers (%define api.pure) can trigger GCC
+   warnings such as:
+ 
+     input.c: In function 'yyparse':
+     input.c:1503:12: warning: 'yylval' may be used uninitialized in this
+                               function [-Wmaybe-uninitialized]
+        *++yyvsp = yylval;
+                 ^
+ 
+   This is now fixed; pragmas to avoid these warnings are no longer needed.
+ 
+   Warnings from clang ("equality comparison with extraneous parentheses" and
+   "function declared 'noreturn' should not return") have also been
+   addressed.
+ 
  * Noteworthy changes in release 2.6.2 (2012-08-03) [stable]
  
  ** Bug fixes
@@@ -111,7 -65,7 +113,7 @@@
  
  * Noteworthy changes in release 2.6.1 (2012-07-30) [stable]
  
 - Bison no longer executes user-specified M4 code when processing a grammar.
 +  Bison no longer executes user-specified M4 code when processing a grammar.
  
  ** Future Changes
  
@@@ -1950,8 -1904,7 +1952,8 @@@ along with this program.  If not, see <
   LocalWords:  namespaces strerror const autoconfiguration Dconst Autoconf's FDL
   LocalWords:  Automake TMPDIR LESSEQ ylwrap endif yydebug YYTOKEN YYLSP ival hh
   LocalWords:  extern YYTOKENTYPE TOKENTYPE yytokentype tokentype STYPE lval pdf
 - LocalWords:  lang yyoutput dvi html ps POSIX lvalp llocp calc yyo fval
 + LocalWords:  lang yyoutput dvi html ps POSIX lvalp llocp calc yyo fval Wmaybe
 + LocalWords:  yyvsp pragmas noreturn java's
  
  Local Variables:
  mode: outline
diff --combined doc/bison.texi
index 4cca4636,ba18d9a9..8f98aa5e
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@@ -294,7 -294,6 +294,7 @@@ Handling Context Dependencie
  Debugging Your Parser
  
  * Understanding::     Understanding the structure of your parser.
 +* Graphviz::          Getting a visual representation of the parser.
  * Tracing::           Tracing the execution of your parser.
  
  Tracing Your Parser
@@@ -328,7 -327,6 +328,7 @@@ C++ Location Value
  
  * C++ position::                One point in the source file
  * C++ location::                Two points in the source file
 +* User Defined Location Type::  Required interface for locations
  
  A Complete C++ Example
  
@@@ -4703,10 -4701,6 +4703,10 @@@ incoming terminals during the second ph
  the current lookahead and the entire stack (except the current
  right-hand side symbols) when the parser returns immediately, and
  @item
 +the current lookahead and the entire stack (including the current right-hand
 +side symbols) when the C++ parser (@file{lalr1.cc}) catches an exception in
 +@code{parse},
 +@item
  the start symbol, when the parser succeeds.
  @end itemize
  
@@@ -5327,23 -5321,6 +5327,23 @@@ Unaccepted @var{variable}s produce an e
  Some of the accepted @var{variable}s are:
  
  @itemize @bullet
 +@c ================================================== api.location.type
 +@item @code{api.location.type}
 +@findex %define api.location.type
 +
 +@itemize @bullet
 +@item Language(s): C++, Java
 +
 +@item Purpose: Define the location type.
 +@xref{User Defined Location Type}.
 +
 +@item Accepted Values: String
 +
 +@item Default Value: none
 +
 +@item History: introduced in Bison 2.7
 +@end itemize
 +
  @c ================================================== api.prefix
  @item @code{api.prefix}
  @findex %define api.prefix
@@@ -5351,7 -5328,7 +5351,7 @@@
  @itemize @bullet
  @item Language(s): All
  
 -@item Purpose: Rename exported symbols
 +@item Purpose: Rename exported symbols.
  @xref{Multiple Parsers, ,Multiple Parsers in the Same Program}.
  
  @item Accepted Values: String
@@@ -8094,7 -8071,6 +8094,7 @@@ automaton, and how to enable and unders
  
  @menu
  * Understanding::     Understanding the structure of your parser.
 +* Graphviz::          Getting a visual representation of the parser.
  * Tracing::           Tracing the execution of your parser.
  @end menu
  
@@@ -8511,114 -8487,6 +8511,114 @@@ precedence of @samp{/} with respect to 
  @samp{*}, but also because the
  associativity of @samp{/} is not specified.
  
 +@c ================================================= Graphical Representation
 +
 +@node Graphviz
 +@section Visualizing Your Parser
 +@cindex dot
 +
 +As another means to gain better understanding of the shift/reduce
 +automaton corresponding to the Bison parser, a DOT file can be generated. Note
 +that debugging a real grammar with this is tedious at best, and impractical
 +most of the times, because the generated files are huge (the generation of
 +a PDF or PNG file from it will take very long, and more often than not it will
 +fail due to memory exhaustion). This option was rather designed for beginners,
 +to help them understand LR parsers.
 +
 +This file is generated when the @option{--graph} option is specified (see
 +@pxref{Invocation, , Invoking Bison}).  Its name is made by removing
 +@samp{.tab.c} or @samp{.c} from the parser implementation file name, and
 +adding @samp{.dot} instead.  If the grammar file is @file{foo.y}, the
 +Graphviz output file is called @file{foo.dot}.
 +
 +The following grammar file, @file{rr.y}, will be used in the sequel:
 +
 +@example
 +%%
 +@group
 +exp: a ";" | b ".";
 +a: "0";
 +b: "0";
 +@end group
 +@end example
 +
 +The graphical output is very similar to the textual one, and as such it is
 +easier understood by making direct comparisons between them. See
 +@ref{Debugging, , Debugging Your Parser} for a detailled analysis of the
 +textual report.
 +
 +@subheading Graphical Representation of States
 +
 +The items (pointed rules) for each state are grouped together in graph nodes.
 +Their numbering is the same as in the verbose file. See the following points,
 +about transitions, for examples
 +
 +When invoked with @option{--report=lookaheads}, the lookahead tokens, when
 +needed, are shown next to the relevant rule between square brackets as a
 +comma separated list. This is the case in the figure for the representation of
 +reductions, below.
 +
 +@sp 1
 +
 +The transitions are represented as directed edges between the current and
 +the target states.
 +
 +@subheading Graphical Representation of Shifts
 +
 +Shifts are shown as solid arrows, labelled with the lookahead token for that
 +shift. The following describes a reduction in the @file{rr.output} file:
 +
 +@example
 +@group
 +state 3
 +
 +    1 exp: a . ";"
 +
 +    ";"  shift, and go to state 6
 +@end group
 +@end example
 +
 +A Graphviz rendering of this portion of the graph could be:
 +
 +@center @image{figs/example-shift, 100pt}
 +
 +@subheading Graphical Representation of Reductions
 +
 +Reductions are shown as solid arrows, leading to a diamond-shaped node
 +bearing the number of the reduction rule. The arrow is labelled with the
 +appropriate comma separated lookahead tokens. If the reduction is the default
 +action for the given state, there is no such label.
 +
 +This is how reductions are represented in the verbose file @file{rr.output}:
 +@example
 +state 1
 +
 +    3 a: "0" .  [";"]
 +    4 b: "0" .  ["."]
 +
 +    "."       reduce using rule 4 (b)
 +    $default  reduce using rule 3 (a)
 +@end example
 +
 +A Graphviz rendering of this portion of the graph could be:
 +
 +@center @image{figs/example-reduce, 120pt}
 +
 +When unresolved conflicts are present, because in deterministic parsing
 +a single decision can be made, Bison can arbitrarily choose to disable a
 +reduction, see @ref{Shift/Reduce, , Shift/Reduce Conflicts}.  Discarded actions
 +are distinguished by a red filling color on these nodes, just like how they are
 +reported between square brackets in the verbose file.
 +
 +The reduction corresponding to the rule number 0 is the acceptation state. It
 +is shown as a blue diamond, labelled "Acc".
 +
 +@subheading Graphical representation of go tos
 +
 +The @samp{go to} jump transitions are represented as dotted lines bearing
 +the name of the rule being jumped to.
 +
 +@c ================================================= Tracing
  
  @node Tracing
  @section Tracing Your Parser
@@@ -9338,9 -9206,8 +9338,9 @@@ generated in the following files
  @table @file
  @item position.hh
  @itemx location.hh
 -The definition of the classes @code{position} and @code{location},
 -used for location tracking.  @xref{C++ Location Values}.
 +The definition of the classes @code{position} and @code{location}, used for
 +location tracking.  These files are not generated if the @code{%define}
 +variable @code{api.location.type} is defined.  @xref{C++ Location Values}.
  
  @item stack.hh
  An auxiliary class @code{stack} used by the parser.
@@@ -9396,22 -9263,18 +9396,22 @@@ Symbols}
  @c - %define filename_type "const symbol::Symbol"
  
  When the directive @code{%locations} is used, the C++ parser supports
 -location tracking, see @ref{Tracking Locations}.  Two auxiliary classes
 -define a @code{position}, a single point in a file, and a @code{location}, a
 -range composed of a pair of @code{position}s (possibly spanning several
 -files).
 +location tracking, see @ref{Tracking Locations}.
 +
 +By default, two auxiliary classes define a @code{position}, a single point
 +in a file, and a @code{location}, a range composed of a pair of
 +@code{position}s (possibly spanning several files).  But if the
 +@code{%define} variable @code{api.location.type} is defined, then these
 +classes will not be generated, and the user defined type will be used.
  
  @tindex uint
  In this section @code{uint} is an abbreviation for @code{unsigned int}: in
  genuine code only the latter is used.
  
  @menu
 -* C++ position::         One point in the source file
 -* C++ location::         Two points in the source file
 +* C++ position::                One point in the source file
 +* C++ location::                Two points in the source file
 +* User Defined Location Type::  Required interface for locations
  @end menu
  
  @node C++ position
@@@ -9515,63 -9378,6 +9515,63 @@@ Report @var{p} on @var{o}, taking care 
  @code{filename} defined, or equal filename/line or column.
  @end deftypefun
  
 +@node User Defined Location Type
 +@subsubsection User Defined Location Type
 +@findex %define api.location.type
 +
 +Instead of using the built-in types you may use the @code{%define} variable
 +@code{api.location.type} to specify your own type:
 +
 +@example
 +%define api.location.type @var{LocationType}
 +@end example
 +
 +The requirements over your @var{LocationType} are:
 +@itemize
 +@item
 +it must be copyable;
 +
 +@item
 +in order to compute the (default) value of @code{@@$} in a reduction, the
 +parser basically runs
 +@example
 +@@$.begin = @@$1.begin;
 +@@$.end   = @@$@var{N}.end; // The location of last right-hand side symbol.
 +@end example
 +@noindent
 +so there must be copyable @code{begin} and @code{end} members;
 +
 +@item
 +alternatively you may redefine the computation of the default location, in
 +which case these members are not required (@pxref{Location Default Action});
 +
 +@item
 +if traces are enabled, then there must exist an @samp{std::ostream&
 +  operator<< (std::ostream& o, const @var{LocationType}& s)} function.
 +@end itemize
 +
 +@sp 1
 +
 +In programs with several C++ parsers, you may also use the @code{%define}
 +variable @code{api.location.type} to share a common set of built-in
 +definitions for @code{position} and @code{location}.  For instance, one
 +parser @file{master/parser.yy} might use:
 +
 +@example
 +%defines
 +%locations
 +%define namespace "master::"
 +@end example
 +
 +@noindent
 +to generate the @file{master/position.hh} and @file{master/location.hh}
 +files, reused by other parsers as follows:
 +
 +@example
 +%define api.location.type "master::location"
 +%code requires @{ #include <master/location.hh> @}
 +@end example
 +
  @node C++ Parser Interface
  @subsection C++ Parser Interface
  @c - define parser_class_name
@@@ -9609,11 -9415,6 +9609,11 @@@ Build a new parser object.  There are n
  
  @deftypemethod {parser} {int} parse ()
  Run the syntactic analysis, and return 0 on success, 1 otherwise.
 +
 +@cindex exceptions
 +The whole function is wrapped in a @code{try}/@code{catch} block, so that
 +when an exception is thrown, the @code{%destructor}s are called to release
 +the lookahead symbol, and the symbols pushed on the stack.
  @end deftypemethod
  
  @deftypemethod {parser} {std::ostream&} debug_stream ()
@@@ -10285,11 -10086,11 +10285,11 @@@ class defines a @dfn{position}, a singl
  defines a class representing a @dfn{location}, a range composed of a pair of
  positions (possibly spanning several files).  The location class is an inner
  class of the parser; the name is @code{Location} by default, and may also be
 -renamed using @code{%define location_type "@var{class-name}"}.
 +renamed using @code{%define api.location.type "@var{class-name}"}.
  
  The location class treats the position as a completely opaque value.
  By default, the class name is @code{Position}, but this can be changed
 -with @code{%define position_type "@var{class-name}"}.  This class must
 +with @code{%define api.position.type "@var{class-name}"}.  This class must
  be supplied by the user.
  
  
@@@ -10424,7 -10225,7 +10424,7 @@@ In both cases, the scanner has to imple
  @deftypemethod {Lexer} {void} yyerror (Location @var{loc}, String @var{msg})
  This method is defined by the user to emit an error message.  The first
  parameter is omitted if location tracking is not active.  Its type can be
 -changed using @code{%define location_type "@var{class-name}".}
 +changed using @code{%define api.location.type "@var{class-name}".}
  @end deftypemethod
  
  @deftypemethod {Lexer} {int} yylex ()
@@@ -10442,7 -10243,7 +10442,7 @@@ Return respectively the first position 
  @code{yylex} returned, and the first position beyond it.  These
  methods are not needed unless location tracking is active.
  
 -The return type can be changed using @code{%define position_type
 +The return type can be changed using @code{%define api.position.type
  "@var{class-name}".}
  @end deftypemethod
  
@@@ -10687,11 -10488,10 +10687,11 @@@ comma-separated list.  Default is @code
  @xref{Java Scanner Interface}.
  @end deffn
  
 -@deffn {Directive} {%define location_type} "@var{class}"
 +@deffn {Directive} {%define api.location.type} "@var{class}"
  The name of the class used for locations (a range between two
  positions).  This class is generated as an inner class of the parser
  class by @command{bison}.  Default is @code{Location}.
 +Formerly named @code{location_type}.
  @xref{Java Location Values}.
  @end deffn
  
@@@ -10706,10 -10506,9 +10706,10 @@@ The name of the parser class.  Default 
  @xref{Java Bison Interface}.
  @end deffn
  
 -@deffn {Directive} {%define position_type} "@var{class}"
 +@deffn {Directive} {%define api.position.type} "@var{class}"
  The name of the class used for positions. This class must be supplied by
  the user.  Default is @code{Position}.
 +Formerly named @code{position_type}.
  @xref{Java Location Values}.
  @end deffn
  
@@@ -11993,10 -11792,9 +11993,10 @@@ London, Department of Computer Science
  @c LocalWords: getLVal defvar deftypefn deftypefnx gotos msgfmt Corbett LALR's
  @c LocalWords: subdirectory Solaris nonassociativity perror schemas Malloy ints
  @c LocalWords: Scannerless ispell american ChangeLog smallexample CSTYPE CLTYPE
 -@c LocalWords: clval CDEBUG cdebug deftypeopx yyterminate
 +@c LocalWords: clval CDEBUG cdebug deftypeopx yyterminate LocationType
++@c LocalWords: errorVerbose
  
  @c Local Variables:
  @c ispell-dictionary: "american"
  @c fill-column: 76
  @c End:
- @c  LocalWords:  errorVerbose