Complain about unused %define variables and %code qualifiers.

[bison.git] / doc / bison.texinfo

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index a02d07607b655bd85da5d75820fd457804cccc01..835dac3596ebc36b6a243fad90335ce2323a7415 100644 (file)
--- 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.
 
 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
 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
 
 @} 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
 
 @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
 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
 @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
 
 @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
 @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,
 
 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
 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
 @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
 @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
 
 @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.
 
 @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
 
 @itemize @bullet
 @item requires


@@ -4831,34 +4836,41 @@ already defined, so that the debugging facilities are compiled.
 @end deffn
 
 @deffn {Directive} %define @var{variable}
 @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.
 @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{""}.
 
 @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
 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.
 
 @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
 
 @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
 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 Accepted Values: Boolean
 

-@item Default Value: @code{"false"}
+@item Default Value: @code{false}

 @end itemize
 
 @item api.push-pull
 @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.)
 
 (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
 @end itemize
 
 @item lr.default-reductions


@@ -4916,7 +4928,7 @@ More user feedback will help to stabilize it.)
 
 @item Accepted Values:
 @itemize
 
 @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.
 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.
 
 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
 @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.
 
 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
 @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 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
 
 @end itemize
 @end itemize
 


@@ -4974,7 +4986,7 @@ are useless in the generated parser.
 
 @item Accepted Values: Boolean
 
 
 @item Accepted Values: Boolean
 

-@item Default Value: @code{"false"}
+@item Default Value: @code{false}

 
 @item Caveats:
 
 
 @item Caveats:
 


@@ -5016,7 +5028,7 @@ More user feedback will help to stabilize it.)
 
 @item Accepted Values:
 @itemize
 
 @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.
 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
 
 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
 @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.
 
 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
 @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
 
 facilitate the development of a grammar.
 @end itemize
 

-@item Default Value: @code{"LALR"}
+@item Default Value: @code{lalr}

 @end itemize
 
 @item namespace
 @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
 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)
 @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
 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}.
 
 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.
 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)
 @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.
 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)
 @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}]
 
 @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}
 
 @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
 @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
 @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>
 @example
 %@{                                            /* -*- C++ -*- */
 # include <cstdlib>

-# include <errno.h>
-# include <limits.h>
+# include <cerrno>
+# include <climits>

 # include <string>
 # include "calc++-driver.hh"
 # include "calc++-parser.hh"
 # 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
 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
 
 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})
 @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})
 @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;}
 @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;}
 @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
 
 @xref{Error Recovery}.
 @end deffn
 


@@ -9937,6 +9973,7 @@ Precedence}.
 
 @deffn {Directive} %define @var{define-variable}
 @deffnx {Directive} %define @var{define-variable} @var{value}
 
 @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
 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
 
 
 @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
 @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