Future/bison
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/bison.git synced 2026-03-13 06:13:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/maint'

Browse Source 
* origin/maint:
  doc: minor fixes
  doc: improve the index
  doc: introduce api.pure full, rearrange some examples
  yacc.c: support "%define api.pure full"
  local.at: improvements

Conflicts:
	NEWS
	data/yacc.c
	doc/bison.texi
	tests/calc.at
This commit is contained in:
Akim Demaille
2012-11-29 14:54:37 +01:00
parent f5fceda596 511dd971ba
commit 5807bb9156
6 changed files with 146 additions and 95 deletions
Download Patch File Download Diff File Expand all files Collapse all files

140
doc/bison.texi
View File

@@ -4954,7 +4954,7 @@ declaration @samp{%define api.pure} says that you want the parser to be
reentrant. It looks like this:
@example
%define api.pure
%define api.pure full
@end example
The result is that the communication variables @code{yylval} and
@@ -5004,7 +5004,7 @@ compatibility with the impure Yacc pull mode interface. Unless you know
what you are doing, your declarations should look like this:
@example
%define api.pure
%define api.pure full
%define api.push-pull push
@end example
@@ -5508,9 +5508,41 @@ The parser namespace is @code{foo} and @code{yylex} is referenced as
@item Purpose: Request a pure (reentrant) parser program.
@xref{Pure Decl, ,A Pure (Reentrant) Parser}.
@item Accepted Values: Boolean
@item Accepted Values: @code{true}, @code{false}, @code{full}
The value may be omitted: this is equivalent to specifying @code{true}, as is
the case for Boolean values.
When @code{%define api.pure full} is used, the parser is made reentrant. This
changes the signature for @code{yylex} (@pxref{Pure Calling}), and also that of
@code{yyerror} when the tracking of locations has been activated, as shown
below.
The @code{true} value is very similar to the @code{full} value, the only
difference is in the signature of @code{yyerror} on Yacc parsers without
@code{%parse-param}, for historical reasons.
I.e., if @samp{%locations %define api.pure} is passed then the prototypes for
@code{yyerror} are:
@example
void yyerror (char const *msg); /* Yacc parsers. */
void yyerror (YYLTYPE *locp, char const *msg); /* GLR parsers. */
@end example
But if @samp{%locations %define api.pure %parse-param @{int *nastiness@}} is
used, then both parsers have the same signature:
@example
void yyerror (YYLTYPE *llocp, int *nastiness, char const *msg);
@end example
(@pxref{Error Reporting, ,The Error
Reporting Function @code{yyerror}})
@item Default Value: @code{false}
@item History: the @code{full} value was introduced in Bison 2.7
@end itemize
@c api.pure
@@ -5637,7 +5669,7 @@ remain in the parser tables. @xref{Unreachable States}.
@item Default Value: @code{false}
@end itemize
introduced as @code{lr.keep_unreachable_states} in 2.3b, renamed as
@code{lr.keep-unreachable-state} in 2.5, and as
@code{lr.keep-unreachable-states} in 2.5, and as
@code{lr.keep-unreachable-state} in 2.8.
@c lr.keep-unreachable-state
@@ -6073,6 +6105,27 @@ In the grammar actions, use expressions like this to refer to the data:
exp: @dots{} @{ @dots{}; *randomness += 1; @dots{} @}
@end example
@noindent
Using the following:
@example
%parse-param @{int *randomness@}
@end example
Results in these signatures:
@example
void yyerror (int *randomness, const char *msg);
int yyparse (int *randomness);
@end example
@noindent
Or, if both @code{%define api.pure full} (or just @code{%define api.pure})
and @code{%locations} are used:
@example
void yyerror (YYLTYPE *llocp, int *randomness, const char *msg);
int yyparse (int *randomness);
@end example
@node Push Parser Function
@section The Push Parser Function @code{yypush_parse}
@findex yypush_parse
@@ -6324,7 +6377,7 @@ The data type of @code{yylloc} has the name @code{YYLTYPE}.
@node Pure Calling
@subsection Calling Conventions for Pure Parsers
When you use the Bison declaration @samp{%define api.pure} to request a
When you use the Bison declaration @code{%define api.pure full} to request a
pure, reentrant parser, the global communication variables @code{yylval}
and @code{yylloc} cannot be used. (@xref{Pure Decl, ,A Pure (Reentrant)
Parser}.) In such parsers the two global variables are replaced by
@@ -6369,6 +6422,7 @@ Specify that @var{argument-declaration} are additional
declarations, which is equivalent to repeating @code{%param}.
@end deffn
@noindent
For instance:
@example
@@ -6385,7 +6439,7 @@ 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:
If @samp{%define api.pure full} is added:
@example
int yylex (YYSTYPE *lvalp, scanner_mode *mode, environment_type *env);
@@ -6393,7 +6447,8 @@ int yyparse (parser_mode *mode, environment_type *env);
@end example
@noindent
and finally, if both @samp{%define api.pure} and @code{%locations} are used:
and finally, if both @samp{%define api.pure full} and @code{%locations} are
used:
@example
int yylex (YYSTYPE *lvalp, YYLTYPE *llocp,
@@ -6458,50 +6513,16 @@ error recovery if you have written suitable error recovery grammar rules
immediately return 1.
Obviously, in location tracking pure parsers, @code{yyerror} should have
an access to the current location.
This is indeed the case for the GLR
parsers, but not for the Yacc parser, for historical reasons. I.e., if
@samp{%locations %define api.pure} is passed then the prototypes for
@code{yyerror} are:
an access to the current location. With @code{%define api.pure}, this is
indeed the case for the GLR parsers, but not for the Yacc parser, for
historical reasons, and this is the why @code{%define api.pure full} should be
prefered over @code{%define api.pure}.
When @code{%locations %define api.pure full} is used, @code{yyerror} has the
following signature:
@example
void yyerror (char const *msg); /* Yacc parsers. */
void yyerror (YYLTYPE *locp, char const *msg); /* GLR parsers. */
@end example
If @samp{%parse-param @{int *nastiness@}} is used, then:
@example
void yyerror (int *nastiness, char const *msg); /* Yacc parsers. */
void yyerror (int *nastiness, char const *msg); /* GLR parsers. */
@end example
Finally, GLR and Yacc parsers share the same @code{yyerror} calling
convention for absolutely pure parsers, i.e., when the calling
convention of @code{yylex} @emph{and} the calling convention of
@samp{%define api.pure} are pure.
I.e.:
@example
/* Location tracking. */
%locations
/* Pure yylex. */
%define api.pure
%lex-param @{int *nastiness@}
/* Pure yyparse. */
%parse-param @{int *nastiness@}
%parse-param @{int *randomness@}
@end example
@noindent
results in the following signatures for all the parser kinds:
@example
int yylex (YYSTYPE *lvalp, YYLTYPE *llocp, int *nastiness);
int yyparse (int *nastiness, int *randomness);
void yyerror (YYLTYPE *locp,
int *nastiness, int *randomness,
char const *msg);
void yyerror (YYLTYPE *locp, char const *msg);
@end example
@noindent
@@ -7675,9 +7696,9 @@ mysterious behavior altogether. You simply need to activate a more powerful
parser table construction algorithm by using the @code{%define lr.type}
directive.
@deffn {Directive} {%define lr.type @var{TYPE}}
@deffn {Directive} {%define lr.type} @var{type}
Specify the type of parser tables within the LR(1) family. The accepted
values for @var{TYPE} are:
values for @var{type} are:
@itemize
@item @code{lalr} (default)
@@ -7865,9 +7886,9 @@ split the parse instead.
To adjust which states have default reductions enabled, use the
@code{%define lr.default-reduction} directive.
@deffn {Directive} {%define lr.default-reduction @var{WHERE}}
@deffn {Directive} {%define lr.default-reduction} @var{where}
Specify the kind of states that are permitted to contain default reductions.
The accepted values of @var{WHERE} are:
The accepted values of @var{where} are:
@itemize
@item @code{most} (default for LALR and IELR)
@item @code{consistent}
@@ -7905,7 +7926,7 @@ that solves these problems for canonical LR, IELR, and LALR without
sacrificing @code{%nonassoc}, default reductions, or state merging. You can
enable LAC with the @code{%define parse.lac} directive.
@deffn {Directive} {%define parse.lac @var{VALUE}}
@deffn {Directive} {%define parse.lac} @var{value}
Enable LAC to improve syntax error handling.
@itemize
@item @code{none} (default)
@@ -8001,9 +8022,9 @@ resolution because they are useless in the generated parser. However,
keeping unreachable states is sometimes useful when trying to understand the
relationship between the parser and the grammar.
@deffn {Directive} {%define lr.keep-unreachable-state @var{VALUE}}
@deffn {Directive} {%define lr.keep-unreachable-state} @var{value}
Request that Bison allow unreachable states to remain in the parser tables.
@var{VALUE} must be a Boolean. The default is @code{false}.
@var{value} must be a Boolean. The default is @code{false}.
@end deffn
There are a few caveats to consider:
@@ -10278,7 +10299,7 @@ depends whether you use unions, or variants.
@node Split Symbols
@subsubsection Split Symbols
Therefore the interface is as follows.
The interface is as follows.
@deftypemethod {parser} {int} yylex (semantic_type* @var{yylval}, location_type* @var{yylloc}, @var{type1} @var{arg1}, ...)
@deftypemethodx {parser} {int} yylex (semantic_type* @var{yylval}, @var{type1} @var{arg1}, ...)
@@ -10977,8 +10998,7 @@ You can create documentation for generated parsers using Javadoc.
Contrary to C parsers, Java parsers do not use global variables; the
state of the parser is always local to an instance of the parser class.
Therefore, all Java parsers are ``pure'', and the @code{%pure-parser}
and @samp{%define api.pure} directives does not do anything when used in
Java.
and @code{%define api.pure} directives do nothing when used in Java.
Push parsers are currently unsupported in Java and @code{%define
api.push-pull} have no effect.
@@ -11612,7 +11632,7 @@ or
@quotation
My parser includes support for an @samp{#include}-like feature, in
which case I run @code{yyparse} from @code{yyparse}. This fails
although I did specify @samp{%define api.pure}.
although I did specify @samp{%define api.pure full}.
@end quotation
These problems typically come not from Bison itself, but from