* Glossary:: Basic concepts are explained.
* Copying This Manual:: License for copying this manual.
* Bibliography:: Publications cited in this manual.
-* Index:: Cross-references to the text.
+* Index of Terms:: Cross-references to the text.
@detailmenu
--- The Detailed Node Listing ---
@deffn {Directive} %initial-action @{ @var{code} @}
@findex %initial-action
Declare that the braced @var{code} must be invoked before parsing each time
-@code{yyparse} is called. The @var{code} may use @code{$$} and
-@code{@@$} --- initial value and location of the lookahead --- and the
-@code{%parse-param}.
+@code{yyparse} is called. The @var{code} may use @code{$$} (or
+@code{$<@var{tag}>$}) and @code{@@$} --- initial value and location of the
+lookahead --- and the @code{%parse-param}.
@end deffn
For instance, if your locations use a file name, you may use
@deffn {Directive} %destructor @{ @var{code} @} @var{symbols}
@findex %destructor
Invoke the braced @var{code} whenever the parser discards one of the
-@var{symbols}.
-Within @var{code}, @code{$$} designates the semantic value associated
-with the discarded symbol, and @code{@@$} designates its location.
-The additional parser parameters are also available (@pxref{Parser Function, ,
-The Parser Function @code{yyparse}}).
+@var{symbols}. Within @var{code}, @code{$$} (or @code{$<@var{tag}>$})
+designates the semantic value associated with the discarded symbol, and
+@code{@@$} designates its location. The additional parser parameters are
+also available (@pxref{Parser Function, , The Parser Function
+@code{yyparse}}).
When a symbol is listed among @var{symbols}, its @code{%destructor} is called a
per-symbol @code{%destructor}.
the current lookahead and the entire stack (except the current
right-hand side symbols) when the parser returns immediately, and
@item
+the current lookahead and the entire stack (including the current right-hand
+side symbols) when the C++ parser (@file{lalr1.cc}) catches an exception in
+@code{parse},
+@item
the start symbol, when the parser succeeds.
@end itemize
@c This is the same text as for %destructor.
Invoke the braced @var{code} whenever the parser displays one of the
@var{symbols}. Within @var{code}, @code{yyoutput} denotes the output stream
-(a @code{FILE*} in C, and an @code{std::ostream&} in C++),
-@code{$$} designates the semantic value associated with the symbol, and
-@code{@@$} its location. The additional parser parameters are also
-available (@pxref{Parser Function, , The Parser Function @code{yyparse}}).
+(a @code{FILE*} in C, and an @code{std::ostream&} in C++), @code{$$} (or
+@code{$<@var{tag}>$}) designates the semantic value associated with the
+symbol, and @code{@@$} its location. The additional parser parameters are
+also available (@pxref{Parser Function, , The Parser Function
+@code{yyparse}}).
The @var{symbols} are defined as for @code{%destructor} (@pxref{Destructor
Decl, , Freeing Discarded Symbols}.): they can be per-type (e.g.,
If you have declared @code{%code requires} or @code{%code provides}, the output
header also contains their code.
@xref{%code Summary}.
+
+@cindex Header guard
+The generated header is protected against multiple inclusions with a C
+preprocessor guard: @samp{YY_@var{PREFIX}_@var{FILE}_INCLUDED}, where
+@var{PREFIX} and @var{FILE} are the prefix (@pxref{Multiple Parsers,
+,Multiple Parsers in the Same Program}) and generated file name turned
+uppercase, with each series of non alphanumerical characters converted to a
+single underscore.
+
+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
+# define YY_CALC_LIB_PARSE_H_INCLUDED
+...
+#endif /* ! YY_CALC_LIB_PARSE_H_INCLUDED */
+@end example
@end deffn
@deffn {Directive} %defines @var{defines-file}
YYDEBUG 1} in the prologue of the grammar file (@pxref{Prologue, , The
Prologue}).
-If the @code{%define} variable @code{api.prefix} is used (@xref{Multiple
+If the @code{%define} variable @code{api.prefix} is used (@pxref{Multiple
Parsers, ,Multiple Parsers in the Same Program}), for instance @samp{%define
api.prefix x}, then if @code{CDEBUG} is defined, its value controls the
-tracing feature (enabled iff nonzero); otherwise tracing is enabled iff
-@code{YYDEBUG} is nonzero.
+tracing feature (enabled if and only if nonzero); otherwise tracing is
+enabled if and only if @code{YYDEBUG} is nonzero.
@item the option @option{-t} (POSIX Yacc compliant)
@itemx the option @option{--debug} (Bison extension)
conflicts is not reported, so @option{-W} and @option{--warning} then have
no effect on the conflict report.
+@item deprecated
+Deprecated constructs whose support will be removed in future versions of
+Bison.
+
@item other
All warnings not categorized above. These warnings are enabled by default.
@item none
Turn off all the warnings.
@item error
-Treat warnings as errors.
+See @option{-Werror}, below.
@end table
A category can be turned off by prefixing its name with @samp{no-}. For
instance, @option{-Wno-yacc} will hide the warnings about
POSIX Yacc incompatibilities.
+
+@item -Werror[=@var{category}]
+@itemx -Wno-error[=@var{category}]
+Enable warnings falling in @var{category}, and treat them as errors. If no
+@var{category} is given, it defaults to making all enabled warnings into errors.
+
+@var{category} is the same as for @option{--warnings}, with the exception that
+it may not be prefixed with @samp{no-} (see above).
+
+Prefixed with @samp{no}, it deactivates the error treatment for this
+@var{category}. However, the warning itself won't be disabled, or enabled, by
+this option.
+
+Note that the precedence of the @samp{=} and @samp{,} operators is such that
+the following commands are @emph{not} equivalent, as the first will not treat
+S/R conflicts as errors.
+
+@example
+$ bison -Werror=yacc,conflicts-sr input.y
+$ bison -Werror=yacc,error=conflicts-sr input.y
+@end example
@end table
@noindent
Description of the grammar, conflicts (resolved and unresolved), and
parser's automaton.
+@item itemset
+Implies @code{state} and augments the description of the automaton with
+the full set of items for each state, instead of its core only.
+
@item lookahead
Implies @code{state} and augments the description of the automaton with
each rule's lookahead set.
-@item itemset
-Implies @code{state} and augments the description of the automaton with
-the full set of items for each state, instead of its core only.
+@item solved
+Implies @code{state}. Explain how conflicts were solved thanks to
+precedence and associativity directives.
+
+@item all
+Enable all the items.
+
+@item none
+Do not generate the report.
@end table
@item --report-file=@var{file}
@deftypemethod {parser} {int} parse ()
Run the syntactic analysis, and return 0 on success, 1 otherwise.
+
+@cindex exceptions
+The whole function is wrapped in a @code{try}/@code{catch} block, so that
+when an exception is thrown, the @code{%destructor}s are called to release
+the lookahead symbol, and the symbols pushed on the stack.
@end deftypemethod
@deftypemethod {parser} {std::ostream&} debug_stream ()
No @code{%destructor} is needed to enable memory deallocation during error
recovery; the memory, for strings for instance, will be reclaimed by the
regular destructors. All the values are printed using their
-@code{operator<<}.
+@code{operator<<} (@pxref{Printer Decl, , Printing Semantic Values}).
-@c FIXME: Document %printer, and mention that it takes a braced-code operand.
@comment file: calc++-parser.yy
@example
%printer @{ yyoutput << $$; @} <*>;
More user feedback will help to stabilize it.)
@end deffn
-@deffn {Macro} YYPARSE_PARAM
-An obsolete macro for specifying the name of a parameter that
-@code{yyparse} should accept. The use of this macro is deprecated, and
-is supported only for Yacc like parsers. @xref{Pure Calling,, Calling
-Conventions for Pure Parsers}.
-@end deffn
-
@deffn {Macro} YYRECOVERING
The expression @code{YYRECOVERING ()} yields 1 when the parser
is recovering from a syntax error, and 0 otherwise.
@uref{http://www.cs.rhul.ac.uk/research/languages/publications/tomita_style_1.ps}
@end table
-@node Index
-@unnumbered Index
+@node Index of Terms
+@unnumbered Index of Terms
@printindex cp
@c LocalWords: toString deftypeivar deftypeivarx deftypeop YYParser strictfp
@c LocalWords: superclasses boolean getErrorVerbose setErrorVerbose deftypecv
@c LocalWords: getDebugStream setDebugStream getDebugLevel setDebugLevel url
-@c LocalWords: bisonVersion deftypecvx bisonSkeleton getStartPos getEndPos
+@c LocalWords: bisonVersion deftypecvx bisonSkeleton getStartPos getEndPos uint
@c LocalWords: getLVal defvar deftypefn deftypefnx gotos msgfmt Corbett LALR's
-@c LocalWords: subdirectory Solaris nonassociativity perror schemas Malloy
-@c LocalWords: Scannerless ispell american
+@c LocalWords: subdirectory Solaris nonassociativity perror schemas Malloy ints
+@c LocalWords: Scannerless ispell american ChangeLog smallexample CSTYPE CLTYPE
+@c LocalWords: clval CDEBUG cdebug deftypeopx yyterminate
@c Local Variables:
@c ispell-dictionary: "american"
projects / bison.git / blobdiff