[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH 3/3] doc: introduce api.pure full, rearrange some examples
From: |
Theophile Ranquet |
Subject: |
[PATCH 3/3] doc: introduce api.pure full, rearrange some examples |
Date: |
Wed, 28 Nov 2012 10:30:55 +0100 |
* NEWS: Add entry.
* doc/bison.texi (%define Summary): Show the old Yacc behaviour.
(Parser Function): Move parse-param examples here.
(Pure Calling): Remove parse-param examples.
(Error Reporting): Don't show the old behavior, stick to 'full'.
---
NEWS | 11 +++++
doc/bison.texi | 125 ++++++++++++++++++++++++++++++---------------------------
2 files changed, 77 insertions(+), 59 deletions(-)
diff --git a/NEWS b/NEWS
index 3789e92..e7883c6 100644
--- a/NEWS
+++ b/NEWS
@@ -2,6 +2,17 @@ GNU Bison NEWS
* Noteworthy changes in release ?.? (????-??-??) [?]
+** New value for %define variable: api.pure full
+
+ The %define variable api.pure requests a pure (reentrant) parser. However,
+ for historical reasons, using it in a location-tracking Yacc parser resulted
+ in an yyerror function that did not take a location as a parameter. With this
+ new value, the user may request a better pure parser, where yyerror does take
+ a location as a parameter (in location-tracking parsers).
+
+ The use of "%define api.pure true" should be deprecated in favor of this new
+ "%define api.pure full".
+
** Changes in the format of error messages
This used to be the format of many error reports:
diff --git a/doc/bison.texi b/doc/bison.texi
index f2d3dbc..373f738 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -4885,7 +4885,7 @@ declaration @code{%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
@@ -5008,8 +5008,8 @@ yypull_parse (ps); /* Will call the lexer */
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
+Adding the @code{%define api.pure full} 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}.
@node Decl Summary
@@ -5373,9 +5373,39 @@ Some of the accepted @var{variable}s are:
@item Purpose: Request a pure (reentrant) parser program.
@xref{Pure Decl, ,A Pure (Reentrant) Parser}.
address@hidden Accepted Values: Boolean
address@hidden 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.
+
+Note: the @code{full} value is very similar to the @code{true} value, the only
+difference is in the signature of @code{yyerror} on Yacc parsers without
address@hidden, for historical reasons.
+
+I.e., if @samp{%locations %define api.pure} is passed then the prototypes for
address@hidden are:
+
address@hidden
+void yyerror (char const *msg); /* Yacc parsers. */
+void yyerror (YYLTYPE *locp, char const *msg); /* GLR parsers. */
address@hidden example
+
+But if @samp{%locations %define api.pure %parse-param @{int address@hidden is
+used, then both parsers have the same signature:
+
address@hidden
+void yyerror (YYLTYPE *llocp, int *nastiness, char const *msg);
address@hidden example
+
+However, this is a deprecated work-around, prefer using @code{%define api.pure
+full}.
+
+(@pxref{Error Reporting, ,The Error
+Reporting Function @code{yyerror}})
@item Default Value: @code{false}
+
address@hidden History: the @code{full} value was introduced in Bison 2.7
@end itemize
@c ================================================== api.push-pull
@@ -5820,6 +5850,27 @@ In the grammar actions, use expressions like this to
refer to the data:
exp: @dots{} @{ @dots{}; *randomness += 1; @dots{} @}
@end example
address@hidden
+Using the following:
address@hidden
+%parse-param @{int address@hidden
address@hidden example
+
+Results in these signatures:
address@hidden
+void yyerror (int *randomness, const char *msg);
+int yyparse (int *randomness);
address@hidden example
+
address@hidden
+Or, if both @code{%define api.pure full} (or just @code{%define api.pure})
+and @code{%locations} are used:
+
address@hidden
+void yyerror (YYLTYPE *llocp, int *randomness, const char *msg);
+int yyparse (int *randomness);
address@hidden example
+
@node Push Parser Function
@section The Push Parser Function @code{yypush_parse}
@findex yypush_parse
@@ -6106,35 +6157,25 @@ Declare that the braced-code @var{argument-declaration}
is an
additional @code{yylex} argument declaration.
@end deffn
address@hidden
For instance:
@example
-%parse-param @{int address@hidden
%lex-param @{int address@hidden
-%parse-param @{int address@hidden
@end example
@noindent
-results in the following signatures:
+results in the following signature:
@example
int yylex (int *nastiness);
-int yyparse (int *nastiness, int *randomness);
address@hidden example
-
-If @code{%define api.pure} is added:
-
address@hidden
-int yylex (YYSTYPE *lvalp, int *nastiness);
-int yyparse (int *nastiness, int *randomness);
@end example
@noindent
-and finally, if both @code{%define api.pure} and @code{%locations} are used:
+If @code{%define api.pure} (or @code{%define api.pure full}) is added:
@example
-int yylex (YYSTYPE *lvalp, YYLTYPE *llocp, int *nastiness);
-int yyparse (int *nastiness, int *randomness);
+int yylex (YYSTYPE *lvalp, int *nastiness);
@end example
@node Error Reporting
@@ -6194,50 +6235,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
address@hidden %define api.pure} is passed then the prototypes for
address@hidden are:
-
address@hidden
-void yyerror (char const *msg); /* Yacc parsers. */
-void yyerror (YYLTYPE *locp, char const *msg); /* GLR parsers. */
address@hidden example
+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}.
-If @samp{%parse-param @{int address@hidden is used, then:
-
address@hidden
-void yyerror (int *nastiness, char const *msg); /* Yacc parsers. */
-void yyerror (int *nastiness, char const *msg); /* GLR parsers. */
address@hidden 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
address@hidden api.pure} are pure.
-I.e.:
-
address@hidden
-/* Location tracking. */
-%locations
-/* Pure yylex. */
-%define api.pure
-%lex-param @{int address@hidden
-/* Pure yyparse. */
-%parse-param @{int address@hidden
-%parse-param @{int address@hidden
address@hidden example
-
address@hidden
-results in the following signatures for all the parser kinds:
+When @code{%locations %define api.pure full} is used, @code{yyerror} has the
+following signature:
@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
--
1.8.0