-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.
-
-@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}).
-
-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.
+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
+
+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.
+
+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}).
projects / bison.git / blobdiff