Future/bison
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/bison.git synced 2026-03-23 19:23:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: formatting changes

Browse Source 
* doc/bison.texi: Here.
This commit is contained in:
Akim Demaille
2018-11-25 14:00:41 +01:00
parent e1c55d83f8
commit 9476783307
1 changed files with 55 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files

118
doc/bison.texi
View File

@@ -4810,18 +4810,16 @@ The basic way to declare a token type name (terminal symbol) is as follows:
%token @var{name} %token @var{name}
@end example @end example
Bison will convert this into a @code{#define} directive in Bison will convert this into a @code{#define} directive in the parser, so
the parser, so that the function @code{yylex} (if it is in this file) that the function @code{yylex} (if it is in this file) can use the name
can use the name @var{name} to stand for this token type's code. @var{name} to stand for this token type's code.
Alternatively, you can use @code{%left}, @code{%right}, Alternatively, you can use @code{%left}, @code{%right}, @code{%precedence},
@code{%precedence}, or or @code{%nonassoc} instead of @code{%token}, if you wish to specify
@code{%nonassoc} instead of @code{%token}, if you wish to specify associativity and precedence. @xref{Precedence Decl, ,Operator Precedence}.
associativity and precedence. @xref{Precedence Decl, ,Operator
Precedence}.
You can explicitly specify the numeric code for a token type by appending You can explicitly specify the numeric code for a token type by appending a
a nonnegative decimal or hexadecimal integer value in the field immediately nonnegative decimal or hexadecimal integer value in the field immediately
following the token name: following the token name:
@example @example
@@ -4830,14 +4828,14 @@ following the token name:
@end example @end example
@noindent @noindent
It is generally best, however, to let Bison choose the numeric codes for It is generally best, however, to let Bison choose the numeric codes for all
all token types. Bison will automatically select codes that don't conflict token types. Bison will automatically select codes that don't conflict with
with each other or with normal characters. each other or with normal characters.
In the event that the stack type is a union, you must augment the In the event that the stack type is a union, you must augment the
@code{%token} or other token declaration to include the data type @code{%token} or other token declaration to include the data type
alternative delimited by angle-brackets (@pxref{Multiple Types, ,More alternative delimited by angle-brackets (@pxref{Multiple Types, ,More Than
Than One Value Type}). One Value Type}).
For example: For example:
@@ -4851,9 +4849,9 @@ For example:
@end group @end group
@end example @end example
You can associate a literal string token with a token type name by You can associate a literal string token with a token type name by writing
writing the literal string at the end of a @code{%token} the literal string at the end of a @code{%token} declaration which declares
declaration which declares the name. For example: the name. For example:
@example @example
%token arrow "=>" %token arrow "=>"
@@ -4872,14 +4870,14 @@ equivalent literal string tokens:
@noindent @noindent
Once you equate the literal string and the token name, you can use them Once you equate the literal string and the token name, you can use them
interchangeably in further declarations or the grammar rules. The interchangeably in further declarations or the grammar rules. The
@code{yylex} function can use the token name or the literal string to @code{yylex} function can use the token name or the literal string to obtain
obtain the token type code number (@pxref{Calling Convention}). the token type code number (@pxref{Calling Convention}). Syntax error
Syntax error messages passed to @code{yyerror} from the parser will reference messages passed to @code{yyerror} from the parser will reference the literal
the literal string instead of the token name. string instead of the token name.
The token numbered as 0 corresponds to end of file; the following line The token numbered as 0 corresponds to end of file; the following line
allows for nicer error messages referring to ``end of file'' instead allows for nicer error messages referring to ``end of file'' instead of
of ``$end'': ``$end'':
@example @example
%token END 0 "end of file" %token END 0 "end of file"
@@ -4891,12 +4889,11 @@ of ``$end'':
@cindex declaring operator precedence @cindex declaring operator precedence
@cindex operator precedence, declaring @cindex operator precedence, declaring
Use the @code{%left}, @code{%right}, @code{%nonassoc}, or Use the @code{%left}, @code{%right}, @code{%nonassoc}, or @code{%precedence}
@code{%precedence} declaration to declaration to declare a token and specify its precedence and associativity,
declare a token and specify its precedence and associativity, all at all at once. These are called @dfn{precedence declarations}.
once. These are called @dfn{precedence declarations}. @xref{Precedence, ,Operator Precedence}, for general information on operator
@xref{Precedence, ,Operator Precedence}, for general information on precedence.
operator precedence.
The syntax of a precedence declaration is nearly the same as that of The syntax of a precedence declaration is nearly the same as that of
@code{%token}: either @code{%token}: either
@@ -4918,34 +4915,32 @@ all the @var{symbols}:
@itemize @bullet @itemize @bullet
@item @item
The associativity of an operator @var{op} determines how repeated uses The associativity of an operator @var{op} determines how repeated uses of
of the operator nest: whether @samp{@var{x} @var{op} @var{y} @var{op} the operator nest: whether @samp{@var{x} @var{op} @var{y} @var{op} @var{z}}
@var{z}} is parsed by grouping @var{x} with @var{y} first or by is parsed by grouping @var{x} with @var{y} first or by grouping @var{y} with
grouping @var{y} with @var{z} first. @code{%left} specifies @var{z} first. @code{%left} specifies left-associativity (grouping @var{x}
left-associativity (grouping @var{x} with @var{y} first) and with @var{y} first) and @code{%right} specifies right-associativity
@code{%right} specifies right-associativity (grouping @var{y} with (grouping @var{y} with @var{z} first). @code{%nonassoc} specifies no
@var{z} first). @code{%nonassoc} specifies no associativity, which associativity, which means that @samp{@var{x} @var{op} @var{y} @var{op}
means that @samp{@var{x} @var{op} @var{y} @var{op} @var{z}} is @var{z}} is considered a syntax error.
considered a syntax error.
@code{%precedence} gives only precedence to the @var{symbols}, and @code{%precedence} gives only precedence to the @var{symbols}, and defines
defines no associativity at all. Use this to define precedence only, no associativity at all. Use this to define precedence only, and leave any
and leave any potential conflict due to associativity enabled. potential conflict due to associativity enabled.
@item @item
The precedence of an operator determines how it nests with other operators. The precedence of an operator determines how it nests with other operators.
All the tokens declared in a single precedence declaration have equal All the tokens declared in a single precedence declaration have equal
precedence and nest together according to their associativity. precedence and nest together according to their associativity. When two
When two tokens declared in different precedence declarations associate, tokens declared in different precedence declarations associate, the one
the one declared later has the higher precedence and is grouped first. declared later has the higher precedence and is grouped first.
@end itemize @end itemize
For backward compatibility, there is a confusing difference between the For backward compatibility, there is a confusing difference between the
argument lists of @code{%token} and precedence declarations. argument lists of @code{%token} and precedence declarations. Only a
Only a @code{%token} can associate a literal string with a token type name. @code{%token} can associate a literal string with a token type name. A
A precedence declaration always interprets a literal string as a reference to a precedence declaration always interprets a literal string as a reference to
separate token. a separate token. For example:
For example:
@example @example
%left OR "<=" // Does not declare an alias. %left OR "<=" // Does not declare an alias.
@@ -4968,25 +4963,22 @@ used. This is done with a @code{%type} declaration, like this:
@end example @end example
@noindent @noindent
Here @var{nonterminal} is the name of a nonterminal symbol, and Here @var{nonterminal} is the name of a nonterminal symbol, and @var{type}
@var{type} is the name given in the @code{%union} to the alternative is the name given in the @code{%union} to the alternative that you want
that you want (@pxref{Union Decl, ,The Union Declaration}). You (@pxref{Union Decl, ,The Union Declaration}). You can give any number of
can give any number of nonterminal symbols in the same @code{%type} nonterminal symbols in the same @code{%type} declaration, if they have the
declaration, if they have the same value type. Use spaces to separate same value type. Use spaces to separate the symbol names.
the symbol names.
You can also declare the value type of a terminal symbol. To do this, You can also declare the value type of a terminal symbol. To do this, use
use the same @code{<@var{type}>} construction in a declaration for the the same @code{<@var{type}>} construction in a declaration for the terminal
terminal symbol. All kinds of token declarations allow symbol. All kinds of token declarations allow @code{<@var{type}>}.
@code{<@var{type}>}.
@node Initial Action Decl @node Initial Action Decl
@subsection Performing Actions before Parsing @subsection Performing Actions before Parsing
@findex %initial-action @findex %initial-action
Sometimes your parser needs to perform some initializations before Sometimes your parser needs to perform some initializations before parsing.
parsing. The @code{%initial-action} directive allows for such arbitrary The @code{%initial-action} directive allows for such arbitrary code.
code.
@deffn {Directive} %initial-action @{ @var{code} @} @deffn {Directive} %initial-action @{ @var{code} @}
@findex %initial-action @findex %initial-action