X-Git-Url: https://git.saurik.com/bison.git/blobdiff_plain/22b081deb7ab1d0ec7a279e5213fa7fdc2c85207..3eb4f1a3e62807125a815dc572da9204b5b51865:/doc/bison.texi diff --git a/doc/bison.texi b/doc/bison.texi index d1223bdc..2d06fec9 100644 --- a/doc/bison.texi +++ b/doc/bison.texi @@ -5156,7 +5156,7 @@ default location or at the location specified by @var{qualifier}. @end deffn @deffn {Directive} %debug -Instrument the output parser for traces. Obsoleted by @samp{%define +Instrument the parser for traces. Obsoleted by @samp{%define parse.trace}. @xref{Tracing, ,Tracing Your Parser}. @end deffn @@ -5452,6 +5452,22 @@ The parser namespace is @code{foo} and @code{yylex} is referenced as @c namespace +@c ================================================== api.prefix +@item api.prefix +@findex %define api.prefix + +@itemize @bullet +@item Language(s): All + +@item Purpose: Rename exported symbols +@xref{Multiple Parsers, ,Multiple Parsers in the Same Program}. + +@item Accepted Values: String + +@item Default Value: @code{yy} + +@item History: introduced in Bison 2.6 +@end itemize @c ================================================== api.pure @item api.pure @@ -5676,12 +5692,16 @@ syntax error handling. @xref{LAC}. @findex %define parse.trace @itemize -@item Languages(s): C, C++ +@item Languages(s): C, C++, Java @item Purpose: Require parser instrumentation for tracing. -In C/C++, define the macro @code{YYDEBUG} to 1 in the parser implementation +@xref{Tracing, ,Tracing Your Parser}. + +In C/C++, define the macro @code{YYDEBUG} (or @code{@var{prefix}DEBUG} with +@samp{%define api.prefix @var{prefix}}), see @ref{Multiple Parsers, +,Multiple Parsers in the Same Program}) to 1 in the parser implementation file if it is not already defined, so that the debugging facilities are -compiled. @xref{Tracing, ,Tracing Your Parser}. +compiled. @item Accepted Values: Boolean @@ -5830,34 +5850,88 @@ of the standard Bison skeletons. @section Multiple Parsers in the Same Program Most programs that use Bison parse only one language and therefore contain -only one Bison parser. But what if you want to parse more than one -language with the same program? Then you need to avoid a name conflict -between different definitions of @code{yyparse}, @code{yylval}, and so on. - -The easy way to do this is to use the option @samp{-p @var{prefix}} -(@pxref{Invocation, ,Invoking Bison}). This renames the interface -functions and variables of the Bison parser to start with @var{prefix} -instead of @samp{yy}. You can use this to give each parser distinct -names that do not conflict. - -The precise list of symbols renamed is @code{yyparse}, @code{yylex}, -@code{yyerror}, @code{yynerrs}, @code{yylval}, @code{yylloc}, -@code{yychar} and @code{yydebug}. If you use a push parser, -@code{yypush_parse}, @code{yypull_parse}, @code{yypstate}, -@code{yypstate_new} and @code{yypstate_delete} will also be renamed. -For example, if you use @samp{-p c}, the names become @code{cparse}, -@code{clex}, and so on. +only one Bison parser. But what if you want to parse more than one language +with the same program? Then you need to avoid name conflicts between +different definitions of functions and variables such as @code{yyparse}, +@code{yylval}. To use different parsers from the same compilation unit, you +also need to avoid conflicts on types and macros (e.g., @code{YYSTYPE}) +exported in the generated header. + +The easy way to do this is to define the @code{%define} variable +@code{api.prefix}. With different @code{api.prefix}s it is guaranteed that +headers do not conflict when included together, and that compiled objects +can be linked together too. Specifying @samp{%define api.prefix +@var{prefix}} (or passing the option @samp{-Dapi.prefix=@var{prefix}}, see +@ref{Invocation, ,Invoking Bison}) renames the interface functions and +variables of the Bison parser to start with @var{prefix} instead of +@samp{yy}, and all the macros to start by @var{PREFIX} (i.e., @var{prefix} +upper-cased) instead of @samp{YY}. + +The renamed symbols include @code{yyparse}, @code{yylex}, @code{yyerror}, +@code{yynerrs}, @code{yylval}, @code{yylloc}, @code{yychar} and +@code{yydebug}. If you use a push parser, @code{yypush_parse}, +@code{yypull_parse}, @code{yypstate}, @code{yypstate_new} and +@code{yypstate_delete} will also be renamed. The renamed macros include +@code{YYSTYPE}, @code{YYLTYPE}, and @code{YYDEBUG}, which is treated +specifically --- more about this below. + +For example, if you use @samp{%define api.prefix c}, the names become +@code{cparse}, @code{clex}, @dots{}, @code{CSTYPE}, @code{CLTYPE}, and so +on. + +The @code{%define} variable @code{api.prefix} works in two different ways. +In the implementation file, it works by adding macro definitions to the +beginning of the parser implementation file, defining @code{yyparse} as +@code{@var{prefix}parse}, and so on: + +@example +#define YYSTYPE CTYPE +#define yyparse cparse +#define yylval clval +... +YYSTYPE yylval; +int yyparse (void); +@end example -@strong{All the other variables and macros associated with Bison are not -renamed.} These others are not global; there is no conflict if the same -name is used in different parsers. For example, @code{YYSTYPE} is not -renamed, but defining this in different ways in different parsers causes -no trouble (@pxref{Value Type, ,Data Types of Semantic Values}). +This effectively substitutes one name for the other in the entire parser +implementation file, thus the ``original'' names (@code{yylex}, +@code{YYSTYPE}, @dots{}) are also usable in the parser implementation file. -The @samp{-p} option works by adding macro definitions to the -beginning of the parser implementation file, defining @code{yyparse} -as @code{@var{prefix}parse}, and so on. This effectively substitutes -one name for the other in the entire parser implementation file. +However, in the parser header file, the symbols are defined renamed, for +instance: + +@example +extern CSTYPE clval; +int cparse (void); +@end example + +The macro @code{YYDEBUG} is commonly used to enable the tracing support in +parsers. To comply with this tradition, when @code{api.prefix} is used, +@code{YYDEBUG} (not renamed) is used as a default value: + +@example +/* Enabling traces. */ +#ifndef CDEBUG +# if defined YYDEBUG +# if YYDEBUG +# define CDEBUG 1 +# else +# define CDEBUG 0 +# endif +# else +# define CDEBUG 0 +# endif +#endif +#if CDEBUG +extern int cdebug; +#endif +@end example + +@sp 2 + +Prior to Bison 2.6, a feature similar to @code{api.prefix} was provided by +the obsolete directive @code{%name-prefix} (@pxref{Table of Symbols, ,Bison +Symbols}) and the option @code{--name-prefix} (@pxref{Bison Options}). @node Interface @chapter Parser C-Language Interface @@ -5973,9 +6047,9 @@ function is available if either the @samp{%define api.push-pull push} or @xref{Push Decl, ,A Push Parser}. @deftypefun int yypush_parse (yypstate *yyps) -The value returned by @code{yypush_parse} is the same as for yyparse with the -following exception. @code{yypush_parse} will return YYPUSH_MORE if more input -is required to finish parsing the grammar. +The value returned by @code{yypush_parse} is the same as for yyparse with +the following exception: it returns @code{YYPUSH_MORE} if more input is +required to finish parsing the grammar. @end deftypefun @node Pull Parser Function @@ -8746,9 +8820,17 @@ parser. This is compliant with POSIX Yacc. You could use YYDEBUG 1} in the prologue of the grammar file (@pxref{Prologue, , The Prologue}). -@item the option @option{-t}, @option{--debug} -Use the @samp{-t} option when you run Bison (@pxref{Invocation, -,Invoking Bison}). This is POSIX compliant too. +If the @code{%define} variable @code{api.prefix} is used (@pxref{Multiple +Parsers, ,Multiple Parsers in the Same Program}), for instance @samp{%define +api.prefix x}, then if @code{CDEBUG} is defined, its value controls the +tracing feature (enabled iff nonzero); otherwise tracing is enabled iff +@code{YYDEBUG} is nonzero. + +@item the option @option{-t} (POSIX Yacc compliant) +@itemx the option @option{--debug} (Bison extension) +Use the @samp{-t} option when you run Bison (@pxref{Invocation, ,Invoking +Bison}). With @samp{%define api.prefix c}, it defines @code{CDEBUG} to 1, +otherwise it defines @code{YYDEBUG} to 1. @item the directive @samp{%debug} @findex %debug @@ -9238,8 +9320,9 @@ Pretend that @code{%locations} was specified. @xref{Decl Summary}. @item -p @var{prefix} @itemx --name-prefix=@var{prefix} -Pretend that @code{%name-prefix "@var{prefix}"} was specified. -@xref{Decl Summary}. +Pretend that @code{%name-prefix "@var{prefix}"} was specified (@pxref{Decl +Summary}). Obsoleted by @code{-Dapi.prefix=@var{prefix}}. @xref{Multiple +Parsers, ,Multiple Parsers in the Same Program}. @item -l @itemx --no-lines @@ -11701,9 +11784,24 @@ function is applied to the two semantic values to get a single result. @end deffn @deffn {Directive} %name-prefix "@var{prefix}" -Bison declaration to rename the external symbols. @xref{Decl Summary}. +Obsoleted by the @code{%define} variable @code{api.prefix} (@pxref{Multiple +Parsers, ,Multiple Parsers in the Same Program}). + +Rename the external symbols (variables and functions) used in the parser so +that they start with @var{prefix} instead of @samp{yy}. Contrary to +@code{api.prefix}, do no rename types and macros. + +The precise list of symbols renamed in C parsers is @code{yyparse}, +@code{yylex}, @code{yyerror}, @code{yynerrs}, @code{yylval}, @code{yychar}, +@code{yydebug}, and (if locations are used) @code{yylloc}. If you use a +push parser, @code{yypush_parse}, @code{yypull_parse}, @code{yypstate}, +@code{yypstate_new} and @code{yypstate_delete} will also be renamed. For +example, if you use @samp{%name-prefix "c_"}, the names become +@code{c_parse}, @code{c_lex}, and so on. For C++ parsers, see the +@code{%define namespace} documentation in this section. @end deffn + @ifset defaultprec @deffn {Directive} %no-default-prec Do not assign a precedence to rules that lack an explicit @samp{%prec}