From 221591de324798156b7b16f2dc733cd23b8e1417 Mon Sep 17 00:00:00 2001 From: Akim Demaille Date: Mon, 7 Sep 2009 08:05:43 +0200 Subject: [PATCH 5/5] %param: documentation. * NEWS (2.6): Document %param, %lex-param, and %parse-param changes. * doc/bison.texinfo: Document that %lex-param and %parse-param are n-ary. Changes some examples to demonstrate it. (Calc++ Parser): Use %param. --- NEWS | 17 ++++++++++- doc/bison.texinfo | 85 +++++++++++++++++++++++++++++++---------------------- 2 files changed, 66 insertions(+), 36 deletions(-) diff --git a/NEWS b/NEWS index 63d09a3..8f1b195 100644 --- a/NEWS +++ b/NEWS @@ -3,7 +3,22 @@ Bison News * Changes in version ?.? (????-??-??): -** Java skeleton improvements: +** Additional yylex/yyparse arguments + + The new directive %param declare additional argument to both yylex + and yyparse. The %lex-param, %parse-param, and %param directive + support one or more arguments. Instead of + + %lex-param {arg1_type *arg1} + %lex-param {arg2_type *arg2} + %parse-param {arg1_type *arg1} + %parse-param {arg2_type *arg2} + + one may now declare + + %param {arg1_type *arg1} {arg2_type *arg2} + +** Java skeleton improvements The constants for token names were moved to the Lexer interface. Also, it is possible to add code to the parser's constructors using diff --git a/doc/bison.texinfo b/doc/bison.texinfo index 4cc5a77..5472eb2 100644 --- a/doc/bison.texinfo +++ b/doc/bison.texinfo @@ -5547,10 +5547,10 @@ If you use a reentrant parser, you can optionally pass additional parameter information to it in a reentrant way. To do so, use the declaration @code{%parse-param}: address@hidden {Directive} %parse-param @address@hidden@} address@hidden {Directive} %parse-param @address@hidden@} @ldots @findex %parse-param -Declare that an argument declared by the braced-code address@hidden is an additional @code{yyparse} argument. +Declare that one or more address@hidden 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. @@ -5559,8 +5559,7 @@ functions or prototypes. The last identifier in Here's an example. Write this in the parser: @example -%parse-param @{int address@hidden -%parse-param @{int address@hidden +%parse-param @{int address@hidden @{int address@hidden @end example @noindent @@ -5856,46 +5855,57 @@ textual locations, then the type @code{YYLTYPE} will not be defined. In 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 address@hidden, use @code{%param}. address@hidden {Directive} lex-param @address@hidden@} address@hidden {Directive} %lex-param @address@hidden@} @ldots @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}. address@hidden deffn + address@hidden {Directive} %param @address@hidden@} @ldots address@hidden %param +Specify that @var{argument-declaration} are additional address@hidden/@code{yyparse} argument declaration. This is equivalent to address@hidden @address@hidden@} @ldots %parse-param address@hidden@address@hidden @ldots}. You may pass one or more +declarations, which is equivalent to repeating @code{%param}. @end deffn For instance: @example -%parse-param @{int address@hidden -%lex-param @{int address@hidden -%parse-param @{int address@hidden +%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 @@ -8815,15 +8825,14 @@ global variables. @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 @@ -8836,7 +8845,7 @@ automatically propagated. @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 @@ -9301,8 +9310,8 @@ which initialize them automatically. @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 address@hidden are used. Use @code{%code init} for code added to the start of the constructor body. This is especially useful to initialize superclasses. Use @@ -9311,11 +9320,12 @@ 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 @@ -10287,8 +10297,8 @@ Bison declaration to assign precedence and left associativity to token(s). @xref{Precedence Decl, ,Operator Precedence}. @end deffn address@hidden {Directive} %lex-param @address@hidden@} -Bison declaration to specifying an additional parameter that address@hidden {Directive} %lex-param @address@hidden@} @ldots +Bison declaration to specifying additional arguments that @code{yylex} should accept. @xref{Pure Calling,, Calling Conventions for Pure Parsers}. @end deffn @@ -10327,10 +10337,15 @@ Bison declaration to set the name of the parser file. @xref{Decl Summary}. @end deffn address@hidden {Directive} %parse-param @address@hidden@} -Bison declaration to specifying an additional parameter that address@hidden should accept. @xref{Parser Function,, The Parser -Function @code{yyparse}}. address@hidden {Directive} %param @address@hidden@} @ldots +Bison declaration to specify additional arguments that both address@hidden and @code{yyparse} should accept. @xref{Parser Function,, The +Parser Function @code{yyparse}}. address@hidden deffn + address@hidden {Directive} %parse-param @address@hidden@} @ldots +Bison declaration to specify additional arguments that @code{yyparse} +should accept. @xref{Parser Function,, The Parser Function @code{yyparse}}. @end deffn @deffn {Directive} %prec -- 1.6.4