@value{VERSION}), the @acronym{GNU} parser generator.
Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1995, 1998,
-1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software
-Foundation, Inc.
+1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free
+Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@end deffn
@deffn {Directive} %debug
-In the parser file, define the macro @code{YYDEBUG} to 1 if it is not
-already defined, so that the debugging facilities are compiled.
-@end deffn
+Instrument the output parser for traces. Obsoleted by @samp{%define
+parse.trace}.
@xref{Tracing, ,Tracing Your Parser}.
+@end deffn
@deffn {Directive} %define @var{variable}
@deffnx {Directive} %define @var{variable} "@var{value}"
Some of the accepted @var{variable}s are:
-@itemize @bullet
+@table @code
@item api.pure
@findex %define api.pure
The parser namespace is @code{foo} and @code{yylex} is referenced as
@code{bar::lex}.
@end itemize
+@c namespace
+
+@item parse.assert
+@findex %define parse.assert
+
+@itemize
+@item Languages(s): C++
+
+@item Purpose: Issue runtime assertions to catch invalid uses.
+In C++, when variants are used, symbols must be constructed and
+destroyed properly. This option checks these constraints.
+
+@item Accepted Values: Boolean
+
+@item Default Value: @code{false}
@end itemize
+@c parse.assert
+@item parse.trace
+@findex %define parse.trace
+
+@itemize
+@item Languages(s): C, C++
+
+@item Purpose: Require parser instrumentation for tracing.
+In C/C++, define the macro @code{YYDEBUG} to 1 in the parser file if it
+is not already defined, so that the debugging facilities are compiled.
+@xref{Tracing, ,Tracing Your Parser}.
+
+@item Accepted Values: Boolean
+
+@item Default Value: @code{false}
+@end itemize
+@end table
+@c parse.trace
@end deffn
+@c %define
@deffn {Directive} %defines
Write a header file containing macro definitions for the token type
@item the directive @samp{%debug}
@findex %debug
-Add the @code{%debug} directive (@pxref{Decl Summary, ,Bison
-Declaration Summary}). This is a Bison extension, which will prove
-useful when Bison will output parsers for languages that don't use a
-preprocessor. Unless @acronym{POSIX} and Yacc portability matter to
-you, this is
-the preferred solution.
+Add the @code{%debug} directive (@pxref{Decl Summary, ,Bison Declaration
+Summary}). This Bison extension is maintained for backward
+compatibility with previous versions of Bison.
+
+@item the variable @samp{parse.trace}
+@findex %define parse.trace
+Add the @samp{%define parse.trace} directive (@pxref{Decl Summary,
+,Bison Declaration Summary}), or pass the @option{-Dparse.trace} option
+(@pxref{Bison Options}). This is a Bison extension, which is especially
+useful for languages that don't use a preprocessor. Unless
+@acronym{POSIX} and Yacc portability matter to you, this is the
+preferred solution.
@end table
-We suggest that you always enable the debug option so that debugging is
+We suggest that you always enable the trace option so that debugging is
always possible.
The trace facility outputs messages with macro calls of the form
like @samp{%glr-parser}, Bison might not be Yacc-compatible even if
this option is specified.
-@item -W
-@itemx --warnings
+@item -W [@var{category}]
+@itemx --warnings[=@var{category}]
Output warnings falling in @var{category}. @var{category} can be one
of:
@table @code
The other output files' names are constructed from @var{file} as
described under the @samp{-v} and @samp{-d} options.
-@item -g[@var{file}]
+@item -g [@var{file}]
@itemx --graph[=@var{file}]
Output a graphical representation of the @acronym{LALR}(1) grammar
automaton computed by Bison, in @uref{http://www.graphviz.org/, Graphviz}
If omitted and the grammar file is @file{foo.y}, the output file will be
@file{foo.dot}.
-@item -x[@var{file}]
+@item -x [@var{file}]
@itemx --xml[=@var{file}]
Output an XML report of the @acronym{LALR}(1) automaton computed by Bison.
@code{@var{file}} is optional.
@node Option Cross Key
@section Option Cross Key
-@c FIXME: How about putting the directives too?
Here is a list of options, alphabetized by long option, to help you find
the corresponding short option.
-@multitable {@option{--defines=@var{defines-file}}} {@option{-b @var{file-prefix}XXX}}
-@headitem Long Option @tab Short Option
+@multitable {@option{--defines=@var{defines-file}}} {@option{-D @var{name}[=@var{value}]}} {@code{%nondeterministic-parser}}
+@headitem Long Option @tab Short Option @tab Bison Directive
@include cross-options.texi
@end multitable
@comment file: calc++-parser.yy
@example
-%debug
+%define parse.trace
%error-verbose
@end example
@code{%defines} directive or the @option{-d}/@option{--defines} options.
@c FIXME: Possible code change.
-Currently, support for debugging is always compiled
-in. Thus the @code{%debug} and @code{%token-table} directives and the
+Currently, support for tracing is always compiled
+in. Thus the @samp{%define parse.trace} and @samp{%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} explicitly
+unused code in the generated parser, so use @samp{%define parse.trace}
+explicitly
if needed. Also, in the future the
@code{%token-table} directive might enable a public interface to
access the token names and codes.
@end deftypeivar
@deftypeop {Constructor} {Location} {} Location (Position @var{loc})
-Create a @code{Location} denoting an empty range located at a given point.
+Create a @code{Location} denoting an empty range located at a given point.
@end deftypeop
@deftypeop {Constructor} {Location} {} Location (Position @var{begin}, Position @var{end})
@end deffn
@deffn {Statement} {return YYERROR;}
-Start error recovery without printing an error message.
+Start error recovery without printing an error message.
@xref{Error Recovery}.
@end deffn
@deffn {Statement} {return YYFAIL;}
-Print an error message and start error recovery.
+Print an error message and start error recovery.
@xref{Error Recovery}.
@end deffn
Equip the parser for debugging. @xref{Decl Summary}.
@end deffn
-@deffn {Directive} %debug
-Equip the parser for debugging. @xref{Decl Summary}.
-@end deffn
-
@ifset defaultprec
@deffn {Directive} %default-prec
Assign a precedence to rules that lack an explicit @samp{%prec}
projects / bison.git / blobdiff