regen

[bison.git] / doc / bison.texi

diff --git a/doc/bison.texi b/doc/bison.texi
index 198403feacd5f164c09ae67df4ef8fe374d4652d..bd03ee1cf791b0736e2e234ddaf9666484ac8c71 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 '*' '/'


@@ -2160,7 +2160,7 @@ the same as the declarations for the infix notation calculator.
 %@}
 
 /* Bison declarations.  */
 %@}
 
 /* Bison declarations.  */

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

 %token NUM
 
 %left '-' '+'
 %token NUM
 
 %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".  */


@@ -3885,7 +3885,7 @@ and then your grammar can use the following instead of @code{%union}:
 %@{
 #include "parser.h"
 %@}
 %@{
 #include "parser.h"
 %@}

-%define api.value.type "union YYSTYPE"
+%define api.value.type @{union YYSTYPE@}

 %type <val> expr
 %token <tptr> ID
 @end group
 %type <val> expr
 %token <tptr> ID
 @end group


@@ -5450,6 +5450,7 @@ parse.trace}.
 
 @deffn {Directive} %define @var{variable}
 @deffnx {Directive} %define @var{variable} @var{value}
 
 @deffn {Directive} %define @var{variable}
 @deffnx {Directive} %define @var{variable} @var{value}

+@deffnx {Directive} %define @var{variable} @{@var{value}@}

 @deffnx {Directive} %define @var{variable} "@var{value}"
 Define a variable to adjust Bison's behavior.  @xref{%define Summary}.
 @end deffn
 @deffnx {Directive} %define @var{variable} "@var{value}"
 Define a variable to adjust Bison's behavior.  @xref{%define Summary}.
 @end deffn


@@ -5499,7 +5500,7 @@ preprocessor guard: @samp{YY_@var{PREFIX}_@var{FILE}_INCLUDED}, where
 uppercase, with each series of non alphanumerical characters converted to a
 single underscore.
 
 uppercase, with each series of non alphanumerical characters converted to a
 single underscore.
 

-For instance with @samp{%define api.prefix "calc"} and @samp{%defines
+For instance with @samp{%define api.prefix @{calc@}} and @samp{%defines

 "lib/parse.h"}, the header will be guarded as follows.
 @example
 #ifndef YY_CALC_LIB_PARSE_H_INCLUDED
 "lib/parse.h"}, the header will be guarded as follows.
 @example
 #ifndef YY_CALC_LIB_PARSE_H_INCLUDED


@@ -5661,17 +5662,17 @@ features are associated with variables, which are assigned by the
 
 @deffn {Directive} %define @var{variable}
 @deffnx {Directive} %define @var{variable} @var{value}
 
 @deffn {Directive} %define @var{variable}
 @deffnx {Directive} %define @var{variable} @var{value}

+@deffnx {Directive} %define @var{variable} @{@var{value}@}

 @deffnx {Directive} %define @var{variable} "@var{value}"
 Define @var{variable} to @var{value}.
 
 @deffnx {Directive} %define @var{variable} "@var{value}"
 Define @var{variable} to @var{value}.
 

-@var{value} must be placed in quotation marks if it contains any
-character other than a letter, underscore, period, or non-initial dash
-or digit.  Omitting @code{"@var{value}"} entirely is always equivalent
-to specifying @code{""}.
+The type of the values depend on the syntax.  Braces denote value in the
+target language (e.g., a namespace, a type, etc.).  Keyword values (no
+delimiters) denote finite choice (e.g., a variation of a feature).  String
+values denote remaining cases (e.g., a file name).

 
 

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

 @end deffn
 
 The rest of this section summarizes variables and values that
 @end deffn
 
 The rest of this section summarizes variables and values that


@@ -5753,7 +5754,7 @@ The parser namespace is @code{foo} and @code{yylex} is referenced as
 @c api.namespace
 
 @c ================================================== api.location.type
 @c api.namespace
 
 @c ================================================== api.location.type

-@deffn {Directive} {%define api.location.type} @var{type}
+@deffn {Directive} {%define api.location.type} @{@var{type}@}

 
 @itemize @bullet
 @item Language(s): C++, Java
 
 @itemize @bullet
 @item Language(s): C++, Java


@@ -5772,7 +5773,7 @@ Introduced in Bison 2.7 for C, C++ and Java.  Introduced under the name
 @end deffn
 
 @c ================================================== api.prefix
 @end deffn
 
 @c ================================================== api.prefix

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

 
 @itemize @bullet
 @item Language(s): All
 
 @itemize @bullet
 @item Language(s): All


@@ -5789,7 +5790,7 @@ Introduced in Bison 2.7 for C, C++ and Java.  Introduced under the name
 @end deffn
 
 @c ================================================== api.pure
 @end deffn
 
 @c ================================================== api.pure

-@deffn Directive {%define api.pure}
+@deffn Directive {%define api.pure} @var{purity}

 
 @itemize @bullet
 @item Language(s): C
 
 @itemize @bullet
 @item Language(s): C


@@ -5877,14 +5878,14 @@ Boolean.
 @item Default Value:
 @code{false}
 @item History:
 @item Default Value:
 @code{false}
 @item History:

-introduced in Bison 2.8
+introduced in Bison 3.0

 @end itemize
 @end deffn
 @c api.token.constructor
 
 
 @c ================================================== api.token.prefix
 @end itemize
 @end deffn
 @c api.token.constructor
 
 
 @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


@@ -5895,7 +5896,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


@@ -5922,7 +5923,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


@@ -6016,7 +6017,7 @@ Use this name as semantic value.
 @end itemize
 
 @item History:
 @end itemize
 
 @item History:

-introduced in Bison 2.8.  Was introduced for Java only in 2.3b as
+introduced in Bison 3.0.  Was introduced for Java only in 2.3b as

 @code{stype}.
 @end itemize
 @end deffn
 @code{stype}.
 @end itemize
 @end deffn


@@ -6048,8 +6049,8 @@ feedback will help to stabilize it.)
 @item @code{most} otherwise.
 @end itemize
 @item History:
 @item @code{most} otherwise.
 @end itemize
 @item History:

-introduced as @code{lr.default-reduction} in 2.5, renamed as
-@code{lr.default-reduction} in 2.8.
+introduced as @code{lr.default-reductions} in 2.5, renamed as
+@code{lr.default-reduction} in 3.0.

 @end itemize
 @end deffn
 
 @end itemize
 @end deffn
 


@@ -6066,7 +6067,7 @@ remain in the parser tables.  @xref{Unreachable States}.
 @item History:
 introduced as @code{lr.keep_unreachable_states} in 2.3b, renamed as
 @code{lr.keep-unreachable-states} in 2.5, and as
 @item History:
 introduced as @code{lr.keep_unreachable_states} in 2.3b, renamed as
 @code{lr.keep-unreachable-states} in 2.5, and as

-@code{lr.keep-unreachable-state} in 2.8.
+@code{lr.keep-unreachable-state} in 3.0.

 @end itemize
 @end deffn
 @c lr.keep-unreachable-state
 @end itemize
 @end deffn
 @c lr.keep-unreachable-state


@@ -10591,16 +10592,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})


@@ -10642,14 +10645,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
 


@@ -10913,7 +10918,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;


@@ -11239,7 +11244,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  ":="


@@ -12754,7 +12759,7 @@ 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{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.
+@code{%define api.namespace} documentation in this section.

 @end deffn
 
 
 @end deffn