X-Git-Url: https://git.saurik.com/bison.git/blobdiff_plain/966aba6583640869f5a0ab4a9ffc60dd40fd7406..628be6c97d9966201f0522c4ec1a4908df12ace5:/doc/bison.texinfo?ds=sidebyside

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index a02d0760..835dac35 100644
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -3048,8 +3048,8 @@ A @dfn{nonterminal symbol} stands for a class of syntactically
 equivalent groupings.  The symbol name is used in writing grammar rules.
 By convention, it should be all lower case.
 
-Symbol names can contain letters, underscores, period, and (not at the
-beginning) digits and dashes.  Dashes in symbol names are a GNU
+Symbol names can contain letters, underscores, periods, dashes, and (not
+at the beginning) digits.  Dashes in symbol names are a GNU
 extension, incompatible with @acronym{POSIX} Yacc.  Terminal symbols
 that contain periods or dashes make little sense: since they are not
 valid symbols (in most programming languages) they are not exported as
@@ -3804,8 +3804,11 @@ typedef struct YYLTYPE
 @} YYLTYPE;
 @end example
 
-At the beginning of the parsing, Bison initializes all these fields to 1
-for @code{yylloc}.
+When @code{YYLTYPE} is not defined, at the beginning of the parsing, Bison
+initializes all these fields to 1 for @code{yylloc}.  To initialize
+@code{yylloc} with a custom location type (or to chose a different
+initialization), use the @code{%initial-action} directive.  @xref{Initial
+Action Decl, , Performing Actions before Parsing}.
 
 @node Actions and Locations
 @subsection Actions and Locations
@@ -4577,7 +4580,7 @@ The following Bison declaration says that you want the parser to be a push
 parser (@pxref{Decl Summary,,%define api.push-pull}):
 
 @example
-%define api.push-pull "push"
+%define api.push-pull push
 @end example
 
 In almost all cases, you want to ensure that your push parser is also
@@ -4588,7 +4591,7 @@ what you are doing, your declarations should look like this:
 
 @example
 %define api.pure
-%define api.push-pull "push"
+%define api.push-pull push
 @end example
 
 There is a major notable functional difference between the pure push parser
@@ -4637,14 +4640,14 @@ for use by the next invocation of the @code{yypush_parse} function.
 
 Bison also supports both the push parser interface along with the pull parser
 interface in the same generated parser.  In order to get this functionality,
-you should replace the @code{%define api.push-pull "push"} declaration with the
-@code{%define api.push-pull "both"} declaration.  Doing this will create all of
+you should replace the @code{%define api.push-pull push} declaration with the
+@code{%define api.push-pull both} declaration.  Doing this will create all of
 the symbols mentioned earlier along with the two extra symbols, @code{yyparse}
 and @code{yypull_parse}.  @code{yyparse} can be used exactly as it normally
 would be used.  However, the user should note that it is implemented in the
 generated parser by calling @code{yypull_parse}.
 This makes the @code{yyparse} function that is generated with the
-@code{%define api.push-pull "both"} declaration slower than the normal
+@code{%define api.push-pull both} declaration slower than the normal
 @code{yyparse} function.  If the user
 calls the @code{yypull_parse} function it will parse the rest of the input
 stream.  It is possible to @code{yypush_parse} tokens to select a subgrammar
@@ -4661,8 +4664,8 @@ yypstate_delete (ps);
 @end example
 
 Adding the @code{%define api.pure} declaration does exactly the same thing to
-the generated parser with @code{%define api.push-pull "both"} as it did for
-@code{%define api.push-pull "push"}.
+the generated parser with @code{%define api.push-pull both} as it did for
+@code{%define api.push-pull push}.
 
 @node Decl Summary
 @subsection Bison Declaration Summary
@@ -4752,7 +4755,9 @@ use this form instead.
 
 @var{qualifier} identifies the purpose of @var{code} and thus the location(s)
 where Bison should generate it.
-Not all values of @var{qualifier} are available for all target languages:
+Not all @var{qualifier}s are accepted for all target languages.
+Unaccepted @var{qualifier}s produce an error.
+Some of the accepted @var{qualifier}s are:
 
 @itemize @bullet
 @item requires
@@ -4831,34 +4836,41 @@ already defined, so that the debugging facilities are compiled.
 @end deffn
 
 @deffn {Directive} %define @var{variable}
+@deffnx {Directive} %define @var{variable} @var{value}
 @deffnx {Directive} %define @var{variable} "@var{value}"
 Define a variable to adjust Bison's behavior.
-The possible choices for @var{variable}, as well as their meanings, depend on
-the selected target language and/or the parser skeleton (@pxref{Decl
-Summary,,%language}, @pxref{Decl Summary,,%skeleton}).
 
-Bison will warn if a @var{variable} is defined multiple times.
+It is an error if a @var{variable} is defined by @code{%define} multiple
+times, but see @ref{Bison Options,,-D @var{name}[=@var{value}]}.
 
-Omitting @code{"@var{value}"} is always equivalent to specifying it as
+@var{value} must be placed in quotation marks if it contains any
+character other than a letter, underscore, period, dash, or non-initial
+digit.
+
+Omitting @code{"@var{value}"} entirely is always equivalent to specifying
 @code{""}.
 
-Some @var{variable}s may be used as Booleans.
+Some @var{variable}s take Boolean values.
 In this case, Bison will complain if the variable definition does not meet one
 of the following four conditions:
 
 @enumerate
-@item @code{"@var{value}"} is @code{"true"}
+@item @code{@var{value}} is @code{true}
 
-@item @code{"@var{value}"} is omitted (or is @code{""}).
-This is equivalent to @code{"true"}.
+@item @code{@var{value}} is omitted (or @code{""} is specified).
+This is equivalent to @code{true}.
 
-@item @code{"@var{value}"} is @code{"false"}.
+@item @code{@var{value}} is @code{false}.
 
 @item @var{variable} is never defined.
-In this case, Bison selects a default value, which may depend on the selected
-target language and/or parser skeleton.
+In this case, Bison selects a default value.
 @end enumerate
 
+What @var{variable}s are accepted, as well as their meanings and default
+values, depend on the selected target language and/or the parser
+skeleton (@pxref{Decl Summary,,%language}, @pxref{Decl
+Summary,,%skeleton}).
+Unaccepted @var{variable}s produce an error.
 Some of the accepted @var{variable}s are:
 
 @itemize @bullet
@@ -4873,7 +4885,7 @@ Some of the accepted @var{variable}s are:
 
 @item Accepted Values: Boolean
 
-@item Default Value: @code{"false"}
+@item Default Value: @code{false}
 @end itemize
 
 @item api.push-pull
@@ -4887,9 +4899,9 @@ Some of the accepted @var{variable}s are:
 (The current push parsing interface is experimental and may evolve.
 More user feedback will help to stabilize it.)
 
-@item Accepted Values: @code{"pull"}, @code{"push"}, @code{"both"}
+@item Accepted Values: @code{pull}, @code{push}, @code{both}
 
-@item Default Value: @code{"pull"}
+@item Default Value: @code{pull}
 @end itemize
 
 @item lr.default-reductions
@@ -4916,7 +4928,7 @@ More user feedback will help to stabilize it.)
 
 @item Accepted Values:
 @itemize
-@item @code{"all"}.
+@item @code{all}.
 For @acronym{LALR} and @acronym{IELR} parsers (@pxref{Decl
 Summary,,lr.type}) by default, all states are permitted to contain
 default reductions.
@@ -4928,7 +4940,7 @@ That is, unlike in a canonical @acronym{LR} state, the lookahead sets of
 reductions in an @acronym{LALR} or @acronym{IELR} state can contain
 tokens that are syntactically incorrect for some left contexts.
 
-@item @code{"consistent"}.
+@item @code{consistent}.
 @cindex consistent states
 A consistent state is a state that has only one possible action.
 If that action is a reduction, then the parser does not need to request
@@ -4940,7 +4952,7 @@ states, then a canonical @acronym{LR} parser reports a syntax error as
 soon as it @emph{needs} the syntactically unacceptable token from the
 scanner.
 
-@item @code{"accepting"}.
+@item @code{accepting}.
 @cindex accepting state
 By default, the only default reduction permitted in a canonical
 @acronym{LR} parser is the accept action in the accepting state, which
@@ -4952,8 +4964,8 @@ without performing any extra reductions.
 
 @item Default Value:
 @itemize
-@item @code{"accepting"} if @code{lr.type} is @code{"canonical LR"}.
-@item @code{"all"} otherwise.
+@item @code{accepting} if @code{lr.type} is @code{canonical-lr}.
+@item @code{all} otherwise.
 @end itemize
 @end itemize
 
@@ -4974,7 +4986,7 @@ are useless in the generated parser.
 
 @item Accepted Values: Boolean
 
-@item Default Value: @code{"false"}
+@item Default Value: @code{false}
 
 @item Caveats:
 
@@ -5016,7 +5028,7 @@ More user feedback will help to stabilize it.)
 
 @item Accepted Values:
 @itemize
-@item @code{"LALR"}.
+@item @code{lalr}.
 While Bison generates @acronym{LALR} parser tables by default for
 historical reasons, @acronym{IELR} or canonical @acronym{LR} is almost
 always preferable for deterministic parsers.
@@ -5045,7 +5057,7 @@ investigate such problems while ignoring the more subtle differences
 from @acronym{IELR} and canonical @acronym{LR}.
 @end itemize
 
-@item @code{"IELR"}.
+@item @code{ielr}.
 @acronym{IELR} is a minimal @acronym{LR} algorithm.
 That is, given any grammar (@acronym{LR} or non-@acronym{LR}),
 @acronym{IELR} and canonical @acronym{LR} always accept exactly the same
@@ -5059,7 +5071,7 @@ grammars, the number of conflicts for @acronym{IELR} is often an order
 of magnitude less as well.
 This can significantly reduce the complexity of developing of a grammar.
 
-@item @code{"canonical LR"}.
+@item @code{canonical-lr}.
 @cindex delayed syntax errors
 @cindex syntax errors delayed
 The only advantage of canonical @acronym{LR} over @acronym{IELR} is
@@ -5075,7 +5087,7 @@ Even when canonical @acronym{LR} behavior is ultimately desired,
 facilitate the development of a grammar.
 @end itemize
 
-@item Default Value: @code{"LALR"}
+@item Default Value: @code{lalr}
 @end itemize
 
 @item namespace
@@ -5456,8 +5468,8 @@ exp: @dots{}    @{ @dots{}; *randomness += 1; @dots{} @}
 More user feedback will help to stabilize it.)
 
 You call the function @code{yypush_parse} to parse a single token.  This
-function is available if either the @code{%define api.push-pull "push"} or
-@code{%define api.push-pull "both"} declaration is used.
+function is available if either the @code{%define api.push-pull push} or
+@code{%define api.push-pull both} declaration is used.
 @xref{Push Decl, ,A Push Parser}.
 
 @deftypefun int yypush_parse (yypstate *yyps)
@@ -5474,7 +5486,7 @@ is required to finish parsing the grammar.
 More user feedback will help to stabilize it.)
 
 You call the function @code{yypull_parse} to parse the rest of the input
-stream.  This function is available if the @code{%define api.push-pull "both"}
+stream.  This function is available if the @code{%define api.push-pull both}
 declaration is used.
 @xref{Push Decl, ,A Push Parser}.
 
@@ -5490,8 +5502,8 @@ The value returned by @code{yypull_parse} is the same as for @code{yyparse}.
 More user feedback will help to stabilize it.)
 
 You call the function @code{yypstate_new} to create a new parser instance.
-This function is available if either the @code{%define api.push-pull "push"} or
-@code{%define api.push-pull "both"} declaration is used.
+This function is available if either the @code{%define api.push-pull push} or
+@code{%define api.push-pull both} declaration is used.
 @xref{Push Decl, ,A Push Parser}.
 
 @deftypefun yypstate *yypstate_new (void)
@@ -5509,8 +5521,8 @@ allocated.
 More user feedback will help to stabilize it.)
 
 You call the function @code{yypstate_delete} to delete a parser instance.
-function is available if either the @code{%define api.push-pull "push"} or
-@code{%define api.push-pull "both"} declaration is used.
+function is available if either the @code{%define api.push-pull push} or
+@code{%define api.push-pull both} declaration is used.
 @xref{Push Decl, ,A Push Parser}.
 
 @deftypefun void yypstate_delete (yypstate *yyps)
@@ -7982,8 +7994,32 @@ already defined, so that the debugging facilities are compiled.
 
 @item -D @var{name}[=@var{value}]
 @itemx --define=@var{name}[=@var{value}]
-Same as running @samp{%define @var{name} "@var{value}"} (@pxref{Decl
-Summary, ,%define}).
+@itemx -F @var{name}[=@var{value}]
+@itemx --force-define=@var{name}[=@var{value}]
+Each of these is equivalent to @samp{%define @var{name} "@var{value}"}
+(@pxref{Decl Summary, ,%define}) except that Bison processes multiple
+definitions for the same @var{name} as follows:
+
+@itemize
+@item
+Bison quietly ignores all command-line definitions for @var{name} except
+the last.
+@item
+If that command-line definition is specified by a @code{-D} or
+@code{--define}, Bison reports an error for any @code{%define}
+definition for @var{name}.
+@item
+If that command-line definition is specified by a @code{-F} or
+@code{--force-define} instead, Bison quietly ignores all @code{%define}
+definitions for @var{name}.
+@item
+Otherwise, Bison reports an error if there are multiple @code{%define}
+definitions for @var{name}.
+@end itemize
+
+You should avoid using @code{-F} and @code{--force-define} in your
+makefiles unless you are confident that it is safe to quietly ignore any
+conflicting @code{%define} that may be added to the grammar file.
 
 @item -L @var{language}
 @itemx --language=@var{language}
@@ -8109,9 +8145,9 @@ More user feedback will help to stabilize it.)
 @section Option Cross Key
 
 Here is a list of options, alphabetized by long option, to help you find
-the corresponding short option.
+the corresponding short option and directive.
 
-@multitable {@option{--defines=@var{defines-file}}} {@option{-D @var{name}[=@var{value}]}} {@code{%nondeterministic-parser}}
+@multitable {@option{--force-define=@var{name}[=@var{value}]}} {@option{-F @var{name}[=@var{value}]}} {@code{%nondeterministic-parser}}
 @headitem Long Option @tab Short Option @tab Bison Directive
 @include cross-options.texi
 @end multitable
@@ -8735,8 +8771,8 @@ parser's to get the set of defined tokens.
 @example
 %@{                                            /* -*- C++ -*- */
 # include <cstdlib>
-# include <errno.h>
-# include <limits.h>
+# include <cerrno>
+# include <climits>
 # include <string>
 # include "calc++-driver.hh"
 # include "calc++-parser.hh"
@@ -8994,7 +9030,7 @@ in a file; Bison itself 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}}.
+@code{%define 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
@@ -9008,7 +9044,7 @@ The first, inclusive, position of the range, and the first beyond.
 @end deftypeivar
 
 @deftypeop {Constructor} {Location} {} Location (Position @var{loc})
-Create a @code{Location} denoting an empty range located at a given point. 
+Create a @code{Location} denoting an empty range located at a given point.
 @end deftypeop
 
 @deftypeop {Constructor} {Location} {} Location (Position @var{begin}, Position @var{end})
@@ -9222,12 +9258,12 @@ Return immediately from the parser, indicating success.
 @end deffn
 
 @deffn {Statement} {return YYERROR;}
-Start error recovery without printing an error message. 
+Start error recovery without printing an error message.
 @xref{Error Recovery}.
 @end deffn
 
 @deffn {Statement} {return YYFAIL;}
-Print an error message and start error recovery. 
+Print an error message and start error recovery.
 @xref{Error Recovery}.
 @end deffn
 
@@ -9937,6 +9973,7 @@ Precedence}.
 
 @deffn {Directive} %define @var{define-variable}
 @deffnx {Directive} %define @var{define-variable} @var{value}
+@deffnx {Directive} %define @var{define-variable} "@var{value}"
 Define a variable to adjust Bison's behavior.
 @xref{Decl Summary,,%define}.
 @end deffn
@@ -10530,6 +10567,10 @@ grammatically indivisible.  The piece of text it represents is a token.
 
 @bye
 
+@c Local Variables:
+@c fill-column: 76
+@c End:
+
 @c LocalWords: texinfo setfilename settitle setchapternewpage finalout
 @c LocalWords: ifinfo smallbook shorttitlepage titlepage GPL FIXME iftex
 @c LocalWords: akim fn cp syncodeindex vr tp synindex dircategory direntry