@} 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
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
@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
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 @samp{%define api.push-pull "push"} declaration with the
-@samp{%define api.push-pull "both"} declaration. Doing this will create all of
+you should replace the @samp{%define api.push-pull push} declaration with the
+@samp{%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
-@samp{%define api.push-pull "both"} declaration slower than the normal
+@samp{%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
@end example
Adding the @samp{%define api.pure} declaration does exactly the same thing to
-the generated parser with @samp{%define api.push-pull "both"} as it did for
-@samp{%define api.push-pull "push"}.
+the generated parser with @samp{%define api.push-pull both} as it did for
+@samp{%define api.push-pull push}.
@node Decl Summary
@subsection Bison Declaration Summary
@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
@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}).
It is an error if a @var{variable} is defined by @code{%define} multiple
-times, but @ref{Bison Options,,-D @var{name}[=@var{value}]}.
+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:
@table @code
@item Accepted Values: Boolean
-@item Default Value: @code{"false"}
+@item Default Value: @code{false}
@end itemize
@c api.pure
(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
@c api.push-pull
@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.
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
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
@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
@item Accepted Values: Boolean
-@item Default Value: @code{"false"}
+@item Default Value: @code{false}
@item Caveats:
@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.
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
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
facilitate the development of a grammar.
@end itemize
-@item Default Value: @code{"LALR"}
+@item Default Value: @code{lalr}
@end itemize
@code{yyerror}}.
@item Accepted Values:
@itemize
-@item @code{"simple"}
+@item @code{simple}
Error messages passed to @code{yyerror} are simply @w{@code{"syntax
error"}}.
-@item @code{"verbose"}
+@item @code{verbose}
Error messages report the unexpected token, and possibly the expected
ones.
@end itemize
parameter information to it in a reentrant way. To do so, use the
declaration @code{%parse-param}:
-@deffn {Directive} %parse-param @{@var{argument-declaration}@}
+@deffn {Directive} %parse-param @{@var{argument-declaration}@} @dots{}
@findex %parse-param
-Declare that an argument declared by the braced-code
-@var{argument-declaration} is an additional @code{yyparse} argument.
+Declare that one or more
+@var{argument-declaration} are additional @code{yyparse} arguments.
The @var{argument-declaration} is used when declaring
functions or prototypes. The last identifier in
@var{argument-declaration} must be the argument name.
Here's an example. Write this in the parser:
@example
-%parse-param @{int *nastiness@}
-%parse-param @{int *randomness@}
+%parse-param @{int *nastiness@} @{int *randomness@}
@end example
@noindent
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 @samp{%define api.push-pull "push"} or
-@samp{%define api.push-pull "both"} declaration is used.
+function is available if either the @samp{%define api.push-pull push} or
+@samp{%define api.push-pull both} declaration is used.
@xref{Push Decl, ,A Push Parser}.
@deftypefun int yypush_parse (yypstate *yyps)
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 @samp{%define api.push-pull "both"}
+stream. This function is available if the @samp{%define api.push-pull both}
declaration is used.
@xref{Push Decl, ,A Push Parser}.
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 @samp{%define api.push-pull "push"} or
-@samp{%define api.push-pull "both"} declaration is used.
+This function is available if either the @samp{%define api.push-pull push} or
+@samp{%define api.push-pull both} declaration is used.
@xref{Push Decl, ,A Push Parser}.
@deftypefun yypstate *yypstate_new (void)
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 @samp{%define api.push-pull "push"} or
-@samp{%define api.push-pull "both"} declaration is used.
+function is available if either the @samp{%define api.push-pull push} or
+@samp{%define api.push-pull both} declaration is used.
@xref{Push Decl, ,A Push Parser}.
@deftypefun void yypstate_delete (yypstate *yyps)
this case, omit the second argument; @code{yylex} will be called with
only one argument.
-
-If you wish to pass the additional parameter data to @code{yylex}, use
+If you wish to pass additional arguments to @code{yylex}, use
@code{%lex-param} just like @code{%parse-param} (@pxref{Parser
-Function}).
+Function}). To pass additional arguments to both @code{yylex} and
+@code{yyparse}, use @code{%param}.
-@deffn {Directive} lex-param @{@var{argument-declaration}@}
+@deffn {Directive} %lex-param @{@var{argument-declaration}@} @dots{}
@findex %lex-param
-Declare that the braced-code @var{argument-declaration} is an
-additional @code{yylex} argument declaration.
+Specify that @var{argument-declaration} are additional @code{yylex} argument
+declarations. You may pass one or more such declarations, which is
+equivalent to repeating @code{%lex-param}.
+@end deffn
+
+@deffn {Directive} %param @{@var{argument-declaration}@} @dots{}
+@findex %param
+Specify that @var{argument-declaration} are additional
+@code{yylex}/@code{yyparse} argument declaration. This is equivalent to
+@samp{%lex-param @{@var{argument-declaration}@} @dots{} %parse-param
+@{@var{argument-declaration}@} @dots{}}. You may pass one or more
+declarations, which is equivalent to repeating @code{%param}.
@end deffn
For instance:
@example
-%parse-param @{int *nastiness@}
-%lex-param @{int *nastiness@}
-%parse-param @{int *randomness@}
+%lex-param @{scanner_mode *mode@}
+%parse-param @{parser_mode *mode@}
+%param @{environment_type *env@}
@end example
@noindent
results in the following signature:
@example
-int yylex (int *nastiness);
-int yyparse (int *nastiness, int *randomness);
+int yylex (scanner_mode *mode, environment_type *env);
+int yyparse (parser_mode *mode, environment_type *env);
@end example
If @samp{%define api.pure} is added:
@example
-int yylex (YYSTYPE *lvalp, int *nastiness);
-int yyparse (int *nastiness, int *randomness);
+int yylex (YYSTYPE *lvalp, scanner_mode *mode, environment_type *env);
+int yyparse (parser_mode *mode, environment_type *env);
@end example
@noindent
and finally, if both @samp{%define api.pure} and @code{%locations} are used:
@example
-int yylex (YYSTYPE *lvalp, YYLTYPE *llocp, int *nastiness);
-int yyparse (int *nastiness, int *randomness);
+int yylex (YYSTYPE *lvalp, YYLTYPE *llocp,
+ scanner_mode *mode, environment_type *env);
+int yyparse (parser_mode *mode, environment_type *env);
@end example
@node Error Reporting
@w{@code{"syntax error"}}.
@findex %define parse.error
-If you invoke @samp{%define parse.error "verbose"} in the Bison
+If you invoke @samp{%define parse.error verbose} in the Bison
declarations section (@pxref{Bison Declarations, ,The Bison Declarations
Section}), then Bison provides a more verbose and specific error message
string instead of just plain @w{@code{"syntax error"}}.
@item -D @var{name}[=@var{value}]
@itemx --define=@var{name}[=@var{value}]
-@item -F @var{name}[=@var{value}]
+@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
@comment file: calc++-parser.yy
@example
// The parsing context.
-%parse-param @{ calcxx_driver& driver @}
-%lex-param @{ calcxx_driver& driver @}
+%param @{ calcxx_driver& driver @}
@end example
@noindent
-Then we request the location tracking feature, and initialize the
+Then we request location tracking, and initialize the
first location's file name. Afterwards new locations are computed
relatively to the previous locations: the file name will be
-automatically propagated.
+propagated.
@comment file: calc++-parser.yy
@example
@end example
@noindent
-Use the two following directives to enable parser tracing and verbose
+Use the following two directives to enable parser tracing and verbose
error messages.
@comment file: calc++-parser.yy
@example
%define parse.trace
-%define parse.error "verbose"
+%define parse.error verbose
@end example
@noindent
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
-@samp{%define location_type "@var{class-name}}.
+@samp{%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
@deftypeop {Constructor} {YYParser} {} YYParser (@var{lex_param}, @dots{}, @var{parse_param}, @dots{})
Build a new parser object with embedded @code{%code lexer}. There are
-no parameters, unless @code{%parse-param}s and/or @code{%lex-param}s are
-used.
+no parameters, unless @code{%param}s and/or @code{%parse-param}s and/or
+@code{%lex-param}s are used.
Use @code{%code init} for code added to the start of the constructor
body. This is especially useful to initialize superclasses. Use
@deftypeop {Constructor} {YYParser} {} YYParser (Lexer @var{lexer}, @var{parse_param}, @dots{})
Build a new parser object using the specified scanner. There are no
-additional parameters unless @code{%parse-param}s are used.
+additional parameters unless @code{%param}s and/or @code{%parse-param}s are
+used.
If the scanner is defined by @code{%code lexer}, this constructor is
declared @code{protected} and is called automatically with a scanner
-created with the correct @code{%lex-param}s.
+created with the correct @code{%param}s and/or @code{%lex-param}s.
Use @code{%code init} for code added to the start of the constructor
body. This is especially useful to initialize superclasses. Use
@deftypemethod {YYParser} {boolean} getErrorVerbose ()
@deftypemethodx {YYParser} {void} setErrorVerbose (boolean @var{verbose})
Get or set the option to produce verbose error messages. These are only
-available with @samp{%define parse.error "verbose"}, which also turns on
+available with @samp{%define parse.error verbose}, which also turns on
verbose error messages.
@end deftypemethod
@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
@end deffn
@deffn {Directive} %error-verbose
-An obsolete directive standing for @samp{%define parse.error "verbose"}.
+An obsolete directive standing for @samp{%define parse.error verbose}.
@end deffn
@deffn {Directive} %file-prefix "@var{prefix}"
@xref{Precedence Decl, ,Operator Precedence}.
@end deffn
-@deffn {Directive} %lex-param @{@var{argument-declaration}@}
-Bison declaration to specifying an additional parameter that
+@deffn {Directive} %lex-param @{@var{argument-declaration}@} @dots{}
+Bison declaration to specifying additional arguments that
@code{yylex} should accept. @xref{Pure Calling,, Calling Conventions
for Pure Parsers}.
@end deffn
Summary}.
@end deffn
-@deffn {Directive} %parse-param @{@var{argument-declaration}@}
-Bison declaration to specifying an additional parameter that
-@code{yyparse} should accept. @xref{Parser Function,, The Parser
-Function @code{yyparse}}.
+@deffn {Directive} %param @{@var{argument-declaration}@} @dots{}
+Bison declaration to specify additional arguments that both
+@code{yylex} and @code{yyparse} should accept. @xref{Parser Function,, The
+Parser Function @code{yyparse}}.
+@end deffn
+
+@deffn {Directive} %parse-param @{@var{argument-declaration}@} @dots{}
+Bison declaration to specify additional arguments that @code{yyparse}
+should accept. @xref{Parser Function,, The Parser Function @code{yyparse}}.
@end deffn
@deffn {Directive} %prec
with @code{#define} in the prologue to request verbose, specific error
message strings when @code{yyerror} is called. It doesn't matter what
definition you use for @code{YYERROR_VERBOSE}, just whether you define
-it. Using @samp{%define parse.error "verbose"} is preferred
+it. Using @samp{%define parse.error verbose} is preferred
(@pxref{Error Reporting, ,The Error Reporting Function @code{yyerror}}).
@end deffn
@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
projects / bison.git / blobdiff