xml: beware of user strings used to give a %prec to rules.

[bison.git] / doc / bison.texinfo

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index b09cf842a8ff22cf3f4e04fd07fd49bb52577683..3dd43503025e5a28f9e4370602f4a748d24166b8 100644 (file)
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -4845,7 +4845,8 @@ The possible choices for @var{variable}, as well as their meanings, depend on
 the selected target language and/or the parser skeleton (@pxref{Decl
 Summary,,%language}, @pxref{Decl Summary,,%skeleton}).
 
 the selected target language and/or the parser skeleton (@pxref{Decl
 Summary,,%language}, @pxref{Decl Summary,,%skeleton}).
 

-Bison will warn if a @var{variable} is defined multiple times.
+It is an error if a @var{variable} is defined by @code{%define} multiple
+times, but @ref{Bison Options,,-D @var{name}[=@var{value}]}.

 
 Omitting @code{"@var{value}"} is always equivalent to specifying it as
 @code{""}.
 
 Omitting @code{"@var{value}"} is always equivalent to specifying it as
 @code{""}.


@@ -4902,6 +4903,43 @@ More user feedback will help to stabilize it.)
 @end itemize
 @c api.push-pull
 
 @end itemize
 @c api.push-pull
 

+@item api.tokens.prefix
+@findex %define api.tokens.prefix
+
+@itemize
+@item Languages(s): all
+
+@item Purpose:
+Add a prefix to the token names when generating their definition in the
+target language.  For instance
+
+@example
+%token FILE for ERROR
+%define api.tokens.prefix "TOK_"
+%%
+start: FILE for ERROR;
+@end example
+
+@noindent
+generates the definition of the symbols @code{TOK_FILE}, @code{TOK_for},
+and @code{TOK_ERROR} in the generated source files.  In particular, the
+scanner must use these prefixed token names, while the grammar itself
+may still use the short names (as in the sample rule given above).  The
+generated informational files (@file{*.output}, @file{*.xml},
+@file{*.dot}) are not modified by this prefix.  See @ref{Calc++ Parser}
+and @ref{Calc++ Scanner}, for a complete example.
+
+@item Accepted Values:
+Any string.  Should be a valid identifier prefix in the target language,
+in other words, it should typically be an identifier itself (sequence of
+letters, underscores, and ---not at the beginning--- digits).
+
+@item Default Value:
+empty
+@end itemize
+@c api.tokens.prefix
+
+

 @item error-verbose
 @findex %define error-verbose
 @itemize
 @item error-verbose
 @findex %define error-verbose
 @itemize


@@ -5190,10 +5228,11 @@ is not already defined, so that the debugging facilities are compiled.
 
 @item Default Value: @code{false}
 @end itemize
 
 @item Default Value: @code{false}
 @end itemize

-@end table

 @c parse.trace
 @c parse.trace

+
+@end table

 @end deffn
 @end deffn

-@c %define
+@c ----------------------------------------------------------   %define

 
 @deffn {Directive} %defines
 Write a header file containing macro definitions for the token type
 
 @deffn {Directive} %defines
 Write a header file containing macro definitions for the token type


@@ -8102,8 +8141,32 @@ already defined, so that the debugging facilities are compiled.
 
 @item -D @var{name}[=@var{value}]
 @itemx --define=@var{name}[=@var{value}]
 
 @item -D @var{name}[=@var{value}]
 @itemx --define=@var{name}[=@var{value}]

-Same as running @samp{%define @var{name} "@var{value}"} (@pxref{Decl
-Summary, ,%define}).
+@item -F @var{name}[=@var{value}]
+@itemx --force-define=@var{name}[=@var{value}]
+Each of these is equivalent to @samp{%define @var{name} "@var{value}"}
+(@pxref{Decl Summary, ,%define}) except that Bison processes multiple
+definitions for the same @var{name} as follows:
+
+@itemize
+@item
+Bison quietly ignores all command-line definitions for @var{name} except
+the last.
+@item
+If that command-line definition is specified by a @code{-D} or
+@code{--define}, Bison reports an error for any @code{%define}
+definition for @var{name}.
+@item
+If that command-line definition is specified by a @code{-F} or
+@code{--force-define} instead, Bison quietly ignores all @code{%define}
+definitions for @var{name}.
+@item
+Otherwise, Bison reports an error if there are multiple @code{%define}
+definitions for @var{name}.
+@end itemize
+
+You should avoid using @code{-F} and @code{--force-define} in your
+makefiles unless you are confident that it is safe to quietly ignore any
+conflicting @code{%define} that may be added to the grammar file.

 
 @item -L @var{language}
 @itemx --language=@var{language}
 
 @item -L @var{language}
 @itemx --language=@var{language}


@@ -8229,9 +8292,9 @@ More user feedback will help to stabilize it.)
 @section Option Cross Key
 
 Here is a list of options, alphabetized by long option, to help you find
 @section Option Cross Key
 
 Here is a list of options, alphabetized by long option, to help you find

-the corresponding short option.
+the corresponding short option and directive.

 
 

-@multitable {@option{--defines=@var{defines-file}}} {@option{-D @var{name}[=@var{value}]}} {@code{%nondeterministic-parser}}
+@multitable {@option{--force-define=@var{name}[=@var{value}]}} {@option{-F @var{name}[=@var{value}]}} {@code{%nondeterministic-parser}}

 @headitem Long Option @tab Short Option @tab Bison Directive
 @include cross-options.texi
 @end multitable
 @headitem Long Option @tab Short Option @tab Bison Directive
 @include cross-options.texi
 @end multitable


@@ -8777,13 +8840,14 @@ The code between @samp{%code @{} and @samp{@}} is output in the
 
 @noindent
 The token numbered as 0 corresponds to end of file; the following line
 
 @noindent
 The token numbered as 0 corresponds to end of file; the following line

-allows for nicer error messages referring to ``end of file'' instead
-of ``$end''.  Similarly user friendly named are provided for each
-symbol.  Note that the tokens names are prefixed by @code{TOKEN_} to
-avoid name clashes.
+allows for nicer error messages referring to ``end of file'' instead of
+``$end''.  Similarly user friendly names are provided for each symbol.
+To avoid name clashes in the generated files (@pxref{Calc++ Scanner}),
+prefix tokens with @code{TOK_} (@pxref{Decl Summary,, api.tokens.prefix}).

 
 @comment file: calc++-parser.yy
 @example
 
 @comment file: calc++-parser.yy
 @example

+%define api.tokens.prefix "TOK_"

 %token        END      0 "end of file"
 %token        ASSIGN     ":="
 %token <sval> IDENTIFIER "identifier"
 %token        END      0 "end of file"
 %token        ASSIGN     ":="
 %token <sval> IDENTIFIER "identifier"


@@ -8813,22 +8877,24 @@ The grammar itself is straightforward.
 %start unit;
 unit: assignments exp  @{ driver.result = $2; @};
 
 %start unit;
 unit: assignments exp  @{ driver.result = $2; @};
 

-assignments: assignments assignment @{@}
-           | /* Nothing.  */        @{@};
+assignments:
+  assignments assignment @{@}
+| /* Nothing.  */        @{@};

 
 assignment:
 
 assignment:

-     "identifier" ":=" exp
+  "identifier" ":=" exp

        @{ driver.variables[*$1] = $3; delete $1; @};
 
 %left '+' '-';
 %left '*' '/';
        @{ driver.variables[*$1] = $3; delete $1; @};
 
 %left '+' '-';
 %left '*' '/';

-exp: exp '+' exp   @{ $$ = $1 + $3; @}
-   | exp '-' exp   @{ $$ = $1 - $3; @}
-   | exp '*' exp   @{ $$ = $1 * $3; @}
-   | exp '/' exp   @{ $$ = $1 / $3; @}
-   | '(' exp ')'   @{ $$ = $2; @}
-   | "identifier"  @{ $$ = driver.variables[*$1]; delete $1; @}
-   | "number"      @{ $$ = $1; @};
+exp:
+  exp '+' exp   @{ $$ = $1 + $3; @}
+| exp '-' exp   @{ $$ = $1 - $3; @}
+| exp '*' exp   @{ $$ = $1 * $3; @}
+| exp '/' exp   @{ $$ = $1 / $3; @}
+| '(' exp ')'   @{ $$ = $2; @}
+| "identifier"  @{ $$ = driver.variables[*$1]; delete $1; @}
+| "number"      @{ $$ = $1; @};

 %%
 @end example
 
 %%
 @end example
 


@@ -8856,8 +8922,8 @@ parser's to get the set of defined tokens.
 @example
 %@{                                            /* -*- C++ -*- */
 # include <cstdlib>
 @example
 %@{                                            /* -*- C++ -*- */
 # include <cstdlib>

-# include <errno.h>
-# include <limits.h>
+# include <cerrno>
+# include <climits>

 # include <string>
 # include "calc++-driver.hh"
 # include "calc++-parser.hh"
 # include <string>
 # include "calc++-driver.hh"
 # include "calc++-parser.hh"


@@ -8869,10 +8935,10 @@ parser's to get the set of defined tokens.
 # undef yywrap
 # define yywrap() 1
 
 # undef yywrap
 # define yywrap() 1
 

-/* By default yylex returns int, we use token_type.
-   Unfortunately yyterminate by default returns 0, which is
+/* By default yylex returns an int; we use token_type.
+   The default yyterminate implementation returns 0, which is

    not of token_type.  */
    not of token_type.  */

-#define yyterminate() return token::END
+#define yyterminate() return TOKEN(END)

 %@}
 @end example
 
 %@}
 @end example
 


@@ -8920,28 +8986,32 @@ preceding tokens.  Comments would be treated equally.
 @end example
 
 @noindent
 @end example
 
 @noindent

-The rules are simple, just note the use of the driver to report errors.
-It is convenient to use a typedef to shorten
-@code{yy::calcxx_parser::token::identifier} into
-@code{token::identifier} for instance.
+The rules are simple.  The driver is used to report errors.  It is
+convenient to use a macro to shorten
+@code{yy::calcxx_parser::token::TOK_@var{Name}} into
+@code{TOKEN(@var{Name})}; note the token prefix, @code{TOK_}.

 
 @comment file: calc++-scanner.ll
 @example
 %@{
 
 @comment file: calc++-scanner.ll
 @example
 %@{

-  typedef yy::calcxx_parser::token token;
+# define TOKEN(Name)                          \
+  yy::calcxx_parser::token::TOK_ ## Name

 %@}
            /* Convert ints to the actual type of tokens.  */
 [-+*/()]   return yy::calcxx_parser::token_type (yytext[0]);
 %@}
            /* Convert ints to the actual type of tokens.  */
 [-+*/()]   return yy::calcxx_parser::token_type (yytext[0]);

-":="       return token::ASSIGN;
+":="       return TOKEN(ASSIGN);

 @{int@}      @{
   errno = 0;
   long n = strtol (yytext, NULL, 10);
   if (! (INT_MIN <= n && n <= INT_MAX && errno != ERANGE))
     driver.error (*yylloc, "integer is out of range");
   yylval->ival = n;
 @{int@}      @{
   errno = 0;
   long n = strtol (yytext, NULL, 10);
   if (! (INT_MIN <= n && n <= INT_MAX && errno != ERANGE))
     driver.error (*yylloc, "integer is out of range");
   yylval->ival = n;

-  return token::NUMBER;
+  return TOKEN(NUMBER);
+@}
+@{id@}       @{
+  yylval->sval = new std::string (yytext);
+  return TOKEN(IDENTIFIER);

 @}
 @}

-@{id@}       yylval->sval = new std::string (yytext); return token::IDENTIFIER;

 .          driver.error (*yylloc, "invalid character");
 %%
 @end example
 .          driver.error (*yylloc, "invalid character");
 %%
 @end example