Operator Precedence
* Why Precedence:: An example showing why precedence is needed.
-* Using Precedence:: How to specify precedence in Bison grammars.
+* Using Precedence:: How to specify precedence and associativity.
+* Precedence Only:: How to specify precedence only.
* Precedence Examples:: How these features are used in the previous example.
* How Precedence:: How they work.
%token NUM
%left '-' '+'
%left '*' '/'
-%left NEG /* negation--unary minus */
-%right '^' /* exponentiation */
+%precedence NEG /* negation--unary minus */
+%right '^' /* exponentiation */
%% /* The grammar follows. */
input: /* empty */
types and says they are left-associative operators. The declarations
@code{%left} and @code{%right} (right associativity) take the place of
@code{%token} which is used to declare a token type name without
-associativity. (These tokens are single-character literals, which
+associativity/precedence. (These tokens are single-character literals, which
ordinarily don't need to be declared. We declare them here to specify
-the associativity.)
+the associativity/precedence.)
Operator precedence is determined by the line ordering of the
declarations; the higher the line number of the declaration (lower on
the page or screen), the higher the precedence. Hence, exponentiation
has the highest precedence, unary minus (@code{NEG}) is next, followed
-by @samp{*} and @samp{/}, and so on. @xref{Precedence, ,Operator
+by @samp{*} and @samp{/}, and so on. Unary minus is not associative,
+only precedence matters (@code{%precedence}. @xref{Precedence, ,Operator
Precedence}.
The other important new feature is the @code{%prec} in the grammar
%left '-' '+'
%left '*' '/'
-%left NEG
+%precedence NEG
%right '^'
%% /* The grammar follows. */
%right '='
%left '-' '+'
%left '*' '/'
-%left NEG /* negation--unary minus */
-%right '^' /* exponentiation */
+%precedence NEG /* negation--unary minus */
+%right '^' /* exponentiation */
@end group
%% /* The grammar follows. */
@end smallexample
the parser, so that the function @code{yylex} (if it is in this file)
can use the name @var{name} to stand for this token type's code.
-Alternatively, you can use @code{%left}, @code{%right}, or
+Alternatively, you can use @code{%left}, @code{%right},
+@code{%precedence}, or
@code{%nonassoc} instead of @code{%token}, if you wish to specify
associativity and precedence. @xref{Precedence Decl, ,Operator
Precedence}.
@cindex declaring operator precedence
@cindex operator precedence, declaring
-Use the @code{%left}, @code{%right} or @code{%nonassoc} declaration to
+Use the @code{%left}, @code{%right}, @code{%nonassoc}, or
+@code{%precedence} declaration to
declare a token and specify its precedence and associativity, all at
once. These are called @dfn{precedence declarations}.
@xref{Precedence, ,Operator Precedence}, for general information on
means that @samp{@var{x} @var{op} @var{y} @var{op} @var{z}} is
considered a syntax error.
+@code{%precedence} gives only precedence to the @var{symbols}, and
+defines no associativity at all. Use this to define precedence only,
+and leave any potential conflict due to associativity enabled.
+
@item
The precedence of an operator determines how it nests with other operators.
All the tokens declared in a single precedence declaration have equal
Define a variable to adjust Bison's behavior.
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}).
+Summary,,%language}, @pxref{Decl Summary,,%skeleton}).
Bison will warn if a @var{variable} is defined multiple times.
Specify the programming language for the generated parser. Currently
supported languages include C, C++, and Java.
@var{language} is case-insensitive.
+
+This directive is experimental and its effect may be modified in future
+releases.
@end deffn
@deffn {Directive} %locations
@deffn {Directive} %skeleton "@var{file}"
Specify the skeleton to use.
-You probably don't need this option unless you are developing Bison.
-You should use @code{%language} if you want to specify the skeleton for a
-different language, because it is clearer and because it will always choose the
-correct skeleton for non-deterministic or push parsers.
+@c You probably don't need this option unless you are developing Bison.
+@c You should use @code{%language} if you want to specify the skeleton for a
+@c different language, because it is clearer and because it will always choose the
+@c correct skeleton for non-deterministic or push parsers.
If @var{file} does not contain a @code{/}, @var{file} is the name of a skeleton
file in the Bison installation directory.
@menu
* Why Precedence:: An example showing why precedence is needed.
-* Using Precedence:: How to specify precedence in Bison grammars.
+* Using Precedence:: How to specify precedence and associativity.
+* Precedence Only:: How to specify precedence only.
* Precedence Examples:: How these features are used in the previous example.
* How Precedence:: How they work.
@end menu
@node Using Precedence
@subsection Specifying Operator Precedence
@findex %left
-@findex %right
@findex %nonassoc
+@findex %precedence
+@findex %right
Bison allows you to specify these choices with the operator precedence
declarations @code{%left} and @code{%right}. Each such declaration
them right-associative. A third alternative is @code{%nonassoc}, which
declares that it is a syntax error to find the same operator twice ``in a
row''.
+The last alternative, @code{%precedence}, allows to define only
+precedence and no associativity at all. As a result, any
+associativity-related conflict that remains will be reported as an
+compile-time error. The directive @code{%nonassoc} creates run-time
+error: using the operator in a associative way is a syntax error. The
+directive @code{%precedence} creates compile-time errors: an operator
+@emph{can} be involved in an associativity-related conflict, contrary to
+what expected the grammar author.
The relative precedence of different operators is controlled by the
-order in which they are declared. The first @code{%left} or
-@code{%right} declaration in the file declares the operators whose
+order in which they are declared. The first precedence/associativity
+declaration in the file declares the operators whose
precedence is lowest, the next such declaration declares the operators
whose precedence is a little higher, and so on.
+@node Precedence Only
+@subsection Specifying Precedence Only
+@findex %precedence
+
+Since @acronym{POSIX} Yacc defines only @code{%left}, @code{%right}, and
+@code{%nonassoc}, which all defines precedence and associativity, little
+attention is paid to the fact that precedence cannot be defined without
+defining associativity. Yet, sometimes, when trying to solve a
+conflict, precedence suffices. In such a case, using @code{%left},
+@code{%right}, or @code{%nonassoc} might hide future (associativity
+related) conflicts that would remain hidden.
+
+The dangling @code{else} ambiguity (@pxref{Shift/Reduce, , Shift/Reduce
+Conflicts}) can be solved explictly. This shift/reduce conflicts occurs
+in the following situation, where the period denotes the current parsing
+state:
+
+@example
+if @var{e1} then if @var{e2} then @var{s1} . else @var{s2}
+@end example
+
+The conflict involves the reduction of the rule @samp{IF expr THEN
+stmt}, which precedence is by default that of its last token
+(@code{THEN}), and the shifting of the token @code{ELSE}. The usual
+disambiguation (attach the @code{else} to the closest @code{if}),
+shifting must be preferred, i.e., the precedence of @code{ELSE} must be
+higher than that of @code{THEN}. But neither is expected to be involved
+in an associativity related conflict, which can be specified as follows.
+
+@example
+%precedence THEN
+%precedence ELSE
+@end example
+
+The unary-minus is another typical example where associativity is
+usually over-specified, see @ref{Infix Calc, , Infix Notation
+Calculator: @code{calc}}. The @code{%left} directive is traditionaly
+used to declare the precedence of @code{NEG}, which is more than needed
+since it also defines its associativity. While this is harmless in the
+traditional example, who knows how @code{NEG} might be used in future
+evolutions of the grammar@dots{}
+
@node Precedence Examples
@subsection Precedence Examples
sign typically has a very high precedence as a unary operator, and a
somewhat lower precedence (lower than multiplication) as a binary operator.
-The Bison precedence declarations, @code{%left}, @code{%right} and
-@code{%nonassoc}, can only be used once for a given token; so a token has
+The Bison precedence declarations
+can only be used once for a given token; so a token has
only one precedence declared in this way. For context-dependent
precedence, you need to use an additional mechanism: the @code{%prec}
modifier for rules.
already defined, so that the debugging facilities are compiled.
@xref{Tracing, ,Tracing Your Parser}.
+@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 -L @var{language}
@itemx --language=@var{language}
Specify the programming language for the generated parser, as if
Summary}). Currently supported languages include C, C++, and Java.
@var{language} is case-insensitive.
+This option is experimental and its effect may be modified in future
+releases.
+
@item --locations
Pretend that @code{%locations} was specified. @xref{Decl Summary}.
Specify the skeleton to use, similar to @code{%skeleton}
(@pxref{Decl Summary, , Bison Declaration Summary}).
-You probably don't need this option unless you are developing Bison.
-You should use @option{--language} if you want to specify the skeleton for a
-different language, because it is clearer and because it will always
-choose the correct skeleton for non-deterministic or push parsers.
+@c You probably don't need this option unless you are developing Bison.
+@c You should use @option{--language} if you want to specify the skeleton for a
+@c different language, because it is clearer and because it will always
+@c choose the correct skeleton for non-deterministic or push parsers.
If @var{file} does not contain a @code{/}, @var{file} is the name of a skeleton
file in the Bison installation directory.
@node C++ Bison Interface
@subsection C++ Bison Interface
-@c - %language "C++"
+@c - %skeleton "lalr1.cc"
@c - Always pure
@c - initial action
-The C++ @acronym{LALR}(1) parser is selected using the language directive,
-@samp{%language "C++"}, or the synonymous command-line option
-@option{--language=c++}.
+The C++ @acronym{LALR}(1) parser is selected using the skeleton directive,
+@samp{%skeleton "lalr1.c"}, or the synonymous command-line option
+@option{--skeleton=lalr1.c}.
@xref{Decl Summary}.
When run, @command{bison} will create several entities in the @samp{yy}
@comment file: calc++-parser.yy
@example
-%language "C++" /* -*- C++ -*- */
+%skeleton "lalr1.cc" /* -*- C++ -*- */
%require "@value{VERSION}"
%defines
%define parser_class_name "calcxx_parser"
| exp '-' exp @{ $$ = $1 - $3; @}
| exp '*' exp @{ $$ = $1 * $3; @}
| exp '/' exp @{ $$ = $1 / $3; @}
+ | '(' exp ')' @{ $$ = $2; @}
| "identifier" @{ $$ = driver.variables[*$1]; delete $1; @}
| "number" @{ $$ = $1; @};
%%
typedef yy::calcxx_parser::token token;
%@}
/* Convert ints to the actual type of tokens. */
-[-+*/] return yy::calcxx_parser::token_type (yytext[0]);
+[-+*/()] return yy::calcxx_parser::token_type (yytext[0]);
":=" return token::ASSIGN;
@{int@} @{
errno = 0;
int
main (int argc, char *argv[])
@{
+ int res = 0;
calcxx_driver driver;
for (++argv; argv[0]; ++argv)
if (*argv == std::string ("-p"))
driver.trace_scanning = true;
else if (!driver.parse (*argv))
std::cout << driver.result << std::endl;
+ else
+ res = 1;
+ return res;
@}
@end example
@code{%defines} directive or the @option{-d}/@option{--defines} options.
@c FIXME: Possible code change.
-Currently, support for debugging and verbose errors are always compiled
+Currently, support for debugging is always compiled
in. Thus the @code{%debug} and @code{%token-table} directives and the
@option{-t}/@option{--debug} and @option{-k}/@option{--token-table}
options have no effect. This may change in the future to eliminate
-unused code in the generated parser, so use @code{%debug} and
-@code{%verbose-error} explicitly if needed. Also, in the future the
+unused code in the generated parser, so use @code{%debug} explicitly
+if needed. Also, in the future the
@code{%token-table} directive might enable a public interface to
access the token names and codes.
+Getting a ``code too large'' error from the Java compiler means the code
+hit the 64KB bytecode per method limination of the Java class file.
+Try reducing the amount of code in actions and static initializers;
+otherwise, report a bug so that the parser skeleton will be improved.
+
+
@node Java Semantic Values
@subsection Java Semantic Values
@c - No %union, specify type in %type/%token.
file should match the name of the class in this case. Similarly, you can
use @code{abstract}, @code{final} and @code{strictfp} with the
@code{%define} declaration to add other modifiers to the parser class.
+A single @code{%define annotations "@var{annotations}"} directive can
+be used to add any number of annotations to the parser class.
The Java package name of the parser class can be specified using the
@code{%define package} directive. The superclass and the implemented
below, all the other members and fields are preceded with a @code{yy} or
@code{YY} prefix to avoid clashes with user code.
-@c FIXME: The following constants and variables are still undocumented:
-@c @code{bisonVersion}, @code{bisonSkeleton} and @code{errorVerbose}.
-
The parser class can be extended using the @code{%parse-param}
directive. Each occurrence of the directive will add a @code{protected
final} field to the parser class, and an argument to its constructor,
which initialize them automatically.
-Token names defined by @code{%token} and the predefined @code{EOF} token
-name are added as constant fields to the parser class.
-
@deftypeop {Constructor} {YYParser} {} YYParser (@var{lex_param}, @dots{}, @var{parse_param}, @dots{})
Build a new parser object with embedded @code{%code lexer}. There are
no parameters, unless @code{%parse-param}s and/or @code{%lex-param}s are
used.
+
+Use @code{%code init} for code added to the start of the constructor
+body. This is especially useful to initialize superclasses. Use
+@code{%define init_throws} to specify any uncatch exceptions.
@end deftypeop
@deftypeop {Constructor} {YYParser} {} YYParser (Lexer @var{lexer}, @var{parse_param}, @dots{})
If the scanner is defined by @code{%code lexer}, this constructor is
declared @code{protected} and is called automatically with a scanner
created with the correct @code{%lex-param}s.
+
+Use @code{%code init} for code added to the start of the constructor
+body. This is especially useful to initialize superclasses. Use
+@code{%define init_throws} to specify any uncatch exceptions.
@end deftypeop
@deftypemethod {YYParser} {boolean} parse ()
@code{false} otherwise.
@end deftypemethod
+@deftypemethod {YYParser} {boolean} getErrorVerbose ()
+@deftypemethodx {YYParser} {void} setErrorVerbose (boolean @var{verbose})
+Get or set the option to produce verbose error messages. These are only
+available with the @code{%error-verbose} directive, which also turn on
+verbose error messages.
+@end deftypemethod
+
+@deftypemethod {YYParser} {void} yyerror (String @var{msg})
+@deftypemethodx {YYParser} {void} yyerror (Position @var{pos}, String @var{msg})
+@deftypemethodx {YYParser} {void} yyerror (Location @var{loc}, String @var{msg})
+Print an error message using the @code{yyerror} method of the scanner
+instance in use. The @code{Location} and @code{Position} parameters are
+available only if location tracking is active.
+@end deftypemethod
+
@deftypemethod {YYParser} {boolean} recovering ()
During the syntactic analysis, return @code{true} if recovering
from a syntax error.
or nonzero, full tracing.
@end deftypemethod
+@deftypecv {Constant} {YYParser} {String} {bisonVersion}
+@deftypecvx {Constant} {YYParser} {String} {bisonSkeleton}
+Identify the Bison version and skeleton used to generate this parser.
+@end deftypecv
+
@node Java Scanner Interface
@subsection Java Scanner Interface
There are two possible ways to interface a Bison-generated Java parser
with a scanner: the scanner may be defined by @code{%code lexer}, or
defined elsewhere. In either case, the scanner has to implement the
-@code{Lexer} inner interface of the parser class.
+@code{Lexer} inner interface of the parser class. This interface also
+contain constants for all user-defined token names and the predefined
+@code{EOF} token.
In the first case, the body of the scanner class is placed in
@code{%code lexer} blocks. If you want to pass parameters from the
@xref{Error Recovery}.
@end deftypefn
-@deftypefn {Function} {protected void} yyerror (String msg)
-@deftypefnx {Function} {protected void} yyerror (Position pos, String msg)
-@deftypefnx {Function} {protected void} yyerror (Location loc, String msg)
+@deftypefn {Function} {void} yyerror (String @var{msg})
+@deftypefnx {Function} {void} yyerror (Position @var{loc}, String @var{msg})
+@deftypefnx {Function} {void} yyerror (Location @var{loc}, String @var{msg})
Print an error message using the @code{yyerror} method of the scanner
-instance in use.
+instance in use. The @code{Location} and @code{Position} parameters are
+available only if location tracking is active.
@end deftypefn
@xref{Java Differences}.
@end deffn
+@deffn {Directive} {%code init} @{ @var{code} @dots{} @}
+Code inserted at the beginning of the parser constructor body.
+@xref{Java Parser Interface}.
+@end deffn
+
@deffn {Directive} {%code lexer} @{ @var{code} @dots{} @}
Code added to the body of a inner lexer class within the parser class.
@xref{Java Scanner Interface}.
@end deffn
@deffn {Directive} %@{ @var{code} @dots{} %@}
-Not supported. Use @code{%code import} instead.
+Not supported. Use @code{%code imports} instead.
@xref{Java Differences}.
@end deffn
@xref{Java Bison Interface}.
@end deffn
+@deffn {Directive} {%define annotations} "@var{annotations}"
+The Java annotations for the parser class. Default is none.
+@xref{Java Bison Interface}.
+@end deffn
+
@deffn {Directive} {%define extends} "@var{superclass}"
The superclass of the parser class. Default is none.
@xref{Java Bison Interface}.
@xref{Java Bison Interface}.
@end deffn
+@deffn {Directive} {%define init_throws} "@var{exceptions}"
+The exceptions thrown by @code{%code init} from the parser class
+constructor. Default is none.
+@xref{Java Parser Interface}.
+@end deffn
+
@deffn {Directive} {%define lex_throws} "@var{exceptions}"
The exceptions thrown by the @code{yylex} method of the lexer, a
comma-separated list. Default is @code{java.io.IOException}.
@end deffn
@deffn {Directive} %left
-Bison declaration to assign left associativity to token(s).
+Bison declaration to assign precedence and left associativity to token(s).
@xref{Precedence Decl, ,Operator Precedence}.
@end deffn
@end deffn
@deffn {Directive} %nonassoc
-Bison declaration to assign nonassociativity to token(s).
+Bison declaration to assign precedence and nonassociativity to token(s).
@xref{Precedence Decl, ,Operator Precedence}.
@end deffn
@xref{Contextual Precedence, ,Context-Dependent Precedence}.
@end deffn
+@deffn {Directive} %precedence
+Bison declaration to assign precedence to token(s), but no associativity
+@xref{Precedence Decl, ,Operator Precedence}.
+@end deffn
+
@deffn {Directive} %pure-parser
Deprecated version of @code{%define api.pure} (@pxref{Decl Summary, ,%define}),
for which Bison is more careful to warn about unreasonable usage.
@end deffn
@deffn {Directive} %right
-Bison declaration to assign right associativity to token(s).
+Bison declaration to assign precedence and right associativity to token(s).
@xref{Precedence Decl, ,Operator Precedence}.
@end deffn
projects / bison.git / blobdiff