api.token.prefix: use code values

[bison.git] / doc / bison.texi

diff --git a/doc/bison.texi b/doc/bison.texi
index 6f50658ac9cae0272acacdb3a3913b095c576d7f..58a14f8bc2fc3a9ee35c440b91ea666f135cc110 100644 (file)
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -1555,7 +1555,7 @@ calculator.  As in C, comments are placed between @samp{/*@dots{}*/}.
 %@}
 @end group
 
 %@}
 @end group
 

-%define api.value.type double
+%define api.value.type @{double@}

 %token NUM
 
 %% /* Grammar rules and actions follow.  */
 %token NUM
 
 %% /* Grammar rules and actions follow.  */


@@ -1582,9 +1582,9 @@ thus specifying the C data type for semantic values of both tokens and
 groupings (@pxref{Value Type, ,Data Types of Semantic Values}).  The Bison
 parser will use whatever type @code{api.value.type} is defined as; if you
 don't define it, @code{int} is the default.  Because we specify
 groupings (@pxref{Value Type, ,Data Types of Semantic Values}).  The Bison
 parser will use whatever type @code{api.value.type} is defined as; if you
 don't define it, @code{int} is the default.  Because we specify

-@code{double}, each token and each expression has an associated value, which
-is a floating point number.  C code can use @code{YYSTYPE} to refer to the
-value @code{api.value.type}.
+@samp{@{double@}}, each token and each expression has an associated value,
+which is a floating point number.  C code can use @code{YYSTYPE} to refer to
+the value @code{api.value.type}.

 
 Each terminal symbol that is not a single-character literal must be
 declared.  (Single-character literals normally don't need to be declared.)
 
 Each terminal symbol that is not a single-character literal must be
 declared.  (Single-character literals normally don't need to be declared.)


@@ -1806,7 +1806,7 @@ The semantic value of the token (if it has one) is stored into the
 global variable @code{yylval}, which is where the Bison parser will look
 for it.  (The C data type of @code{yylval} is @code{YYSTYPE}, whose value
 was defined at the beginning of the grammar via @samp{%define api.value.type
 global variable @code{yylval}, which is where the Bison parser will look
 for it.  (The C data type of @code{yylval} is @code{YYSTYPE}, whose value
 was defined at the beginning of the grammar via @samp{%define api.value.type

-double}; @pxref{Rpcalc Declarations,,Declarations for @code{rpcalc}}.)
+@{double@}}; @pxref{Rpcalc Declarations,,Declarations for @code{rpcalc}}.)

 
 A token type code of zero is returned if the end-of-input is encountered.
 (Bison recognizes any nonpositive value as indicating end-of-input.)
 
 A token type code of zero is returned if the end-of-input is encountered.
 (Bison recognizes any nonpositive value as indicating end-of-input.)


@@ -2004,7 +2004,7 @@ parentheses nested to arbitrary depth.  Here is the Bison code for
 
 @group
 /* Bison declarations.  */
 
 @group
 /* Bison declarations.  */

-%define api.value.type double
+%define api.value.type @{double@}

 %token NUM
 %left '-' '+'
 %left '*' '/'
 %token NUM
 %left '-' '+'
 %left '*' '/'


@@ -3670,14 +3670,14 @@ specify some other type, define the @code{%define} variable
 @code{api.value.type} like this:
 
 @example
 @code{api.value.type} like this:
 
 @example

-%define api.value.type double
+%define api.value.type @{double@}

 @end example
 
 @noindent
 or
 
 @example
 @end example
 
 @noindent
 or
 
 @example

-%define api.value.type "struct semantic_type"
+%define api.value.type @{struct semantic_type@}

 @end example
 
 The value of @code{api.value.type} should be a type name that does not
 @end example
 
 The value of @code{api.value.type} should be a type name that does not


@@ -3787,7 +3787,7 @@ return ID;
 If the @code{%define} variable @code{api.token.prefix} is defined
 (@pxref{%define Summary,,api.token.prefix}), then it is also used to prefix
 the union member names.  For instance, with @samp{%define api.token.prefix
 If the @code{%define} variable @code{api.token.prefix} is defined
 (@pxref{%define Summary,,api.token.prefix}), then it is also used to prefix
 the union member names.  For instance, with @samp{%define api.token.prefix

-TOK_}:
+@{TOK_@}}:

 
 @example
 /* For an "integer".  */
 
 @example
 /* For an "integer".  */


@@ -3795,6 +3795,11 @@ yylval.TOK_INT = 42;
 return TOK_INT;
 @end example
 
 return TOK_INT;
 @end example
 

+This Bison extension cannot work if @code{%yacc} (or
+@option{-y}/@option{--yacc}) is enabled, as POSIX mandates that Yacc
+generate tokens as macros (e.g., @samp{#define INT 258}, or @samp{#define
+TOK_INT 258}).
+

 This feature is new, and user feedback would be most welcome.
 
 A similar feature is provided for C++ that in addition overcomes C++
 This feature is new, and user feedback would be most welcome.
 
 A similar feature is provided for C++ that in addition overcomes C++


@@ -5879,7 +5884,7 @@ introduced in Bison 2.8
 
 
 @c ================================================== api.token.prefix
 
 
 @c ================================================== api.token.prefix

-@deffn Directive {%define api.token.prefix} @var{prefix}
+@deffn Directive {%define api.token.prefix} @{@var{prefix}@}

 
 @itemize
 @item Languages(s): all
 
 @itemize
 @item Languages(s): all


@@ -5890,7 +5895,7 @@ target language.  For instance
 
 @example
 %token FILE for ERROR
 
 @example
 %token FILE for ERROR

-%define api.token.prefix "TOK_"
+%define api.token.prefix @{TOK_@}

 %%
 start: FILE for ERROR;
 @end example
 %%
 start: FILE for ERROR;
 @end example


@@ -5917,7 +5922,7 @@ letters, underscores, and ---not at the beginning--- digits).
 @item Default Value:
 empty
 @item History:
 @item Default Value:
 empty
 @item History:

-introduced in Bison 2.8
+introduced in Bison 3.0

 @end itemize
 @end deffn
 @c api.token.prefix
 @end itemize
 @end deffn
 @c api.token.prefix


@@ -10586,16 +10591,18 @@ filename_type "@var{type}"}.
 The line, starting at 1.
 @end deftypeivar
 
 The line, starting at 1.
 @end deftypeivar
 

-@deftypemethod {position} {uint} lines (int @var{height} = 1)
-Advance by @var{height} lines, resetting the column number.
+@deftypemethod {position} {void} lines (int @var{height} = 1)
+If @var{height} is not null, advance by @var{height} lines, resetting the
+column number.  The resulting line number cannot be less than 1.

 @end deftypemethod
 
 @deftypeivar {position} {uint} column
 The column, starting at 1.
 @end deftypeivar
 
 @end deftypemethod
 
 @deftypeivar {position} {uint} column
 The column, starting at 1.
 @end deftypeivar
 

-@deftypemethod {position} {uint} columns (int @var{width} = 1)
-Advance by @var{width} columns, without changing the line number.
+@deftypemethod {position} {void} columns (int @var{width} = 1)
+Advance by @var{width} columns, without changing the line number. The
+resulting column number cannot be less than 1.

 @end deftypemethod
 
 @deftypemethod {position} {position&} operator+= (int @var{width})
 @end deftypemethod
 
 @deftypemethod {position} {position&} operator+= (int @var{width})


@@ -10637,14 +10644,16 @@ Reset the location to an empty range at the given values.
 The first, inclusive, position of the range, and the first beyond.
 @end deftypeivar
 
 The first, inclusive, position of the range, and the first beyond.
 @end deftypeivar
 

-@deftypemethod {location} {uint} columns (int @var{width} = 1)
-@deftypemethodx {location} {uint} lines (int @var{height} = 1)
-Advance the @code{end} position.
+@deftypemethod {location} {void} columns (int @var{width} = 1)
+@deftypemethodx {location} {void} lines (int @var{height} = 1)
+Forwarded to the @code{end} position.

 @end deftypemethod
 
 @deftypemethod {location} {location} operator+ (const location& @var{end})
 @deftypemethodx {location} {location} operator+ (int @var{width})
 @deftypemethodx {location} {location} operator+= (int @var{width})
 @end deftypemethod
 
 @deftypemethod {location} {location} operator+ (const location& @var{end})
 @deftypemethodx {location} {location} operator+ (int @var{width})
 @deftypemethodx {location} {location} operator+= (int @var{width})

+@deftypemethodx {location} {location} operator- (int @var{width})
+@deftypemethodx {location} {location} operator-= (int @var{width})

 Various forms of syntactic sugar.
 @end deftypemethod
 
 Various forms of syntactic sugar.
 @end deftypemethod
 


@@ -10908,7 +10917,7 @@ also pass the @var{location}.
 For instance, given the following declarations:
 
 @example
 For instance, given the following declarations:
 
 @example

-%define api.token.prefix "TOK_"
+%define api.token.prefix @{TOK_@}

 %token <std::string> IDENTIFIER;
 %token <int> INTEGER;
 %token COLON;
 %token <std::string> IDENTIFIER;
 %token <int> INTEGER;
 %token COLON;


@@ -11234,7 +11243,7 @@ tokens with @code{TOK_} (@pxref{%define Summary,,api.token.prefix}).
 
 @comment file: calc++-parser.yy
 @example
 
 @comment file: calc++-parser.yy
 @example

-%define api.token.prefix "TOK_"
+%define api.token.prefix @{TOK_@}

 %token
   END  0  "end of file"
   ASSIGN  ":="
 %token
   END  0  "end of file"
   ASSIGN  ":="