@c the smallbook format.
@c @smallbook
-@c Set following if you have the new `shorttitlepage' command
-@c @clear shorttitlepage-enabled
-@c @set shorttitlepage-enabled
-
@c Set following if you want to document %default-prec and %no-default-prec.
@c This feature is experimental and may change in future Bison versions.
@c @set defaultprec
-@c ISPELL CHECK: done, 14 Jan 1993 --bob
-
-@c Check COPYRIGHT dates. should be updated in the titlepage, ifinfo
-@c titlepage; should NOT be changed in the GPL. --mew
-
-@c FIXME: I don't understand this `iftex'. Obsolete? --akim.
-@iftex
+@ifnotinfo
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex tp cp
-@end iftex
+@end ifnotinfo
@ifinfo
@synindex fn cp
@synindex vr cp
* bison: (bison). @acronym{GNU} parser generator (Yacc replacement).
@end direntry
-@ifset shorttitlepage-enabled
-@shorttitlepage Bison
-@end ifset
@titlepage
@title Bison
@subtitle The Yacc-compatible Parser Generator
* How Can I Reset the Parser:: @code{yyparse} Keeps some State
* Strings are Destroyed:: @code{yylval} Loses Track of Strings
* Implementing Gotos/Loops:: Control Flow in the Calculator
+* Secure? Conform?:: Is Bison @acronym{POSIX} safe?
+* I can't build Bison:: Troubleshooting
+* Where can I find help?:: Troubleshouting
+* Bug Reports:: Troublereporting
+* Other Languages:: Parsers in Java and others
+* Beta Testing:: Experimenting development versions
+* Mailing Lists:: Meeting other Bison users
Copying This Manual
square (int x) /* @r{identifier, open-paren, keyword `int',}
@r{identifier, close-paren} */
@{ /* @r{open-brace} */
- return x * x; /* @r{keyword `return', identifier, asterisk,
- identifier, semicolon} */
+ return x * x; /* @r{keyword `return', identifier, asterisk,}
+ @r{identifier, semicolon} */
@} /* @r{close-brace} */
@end example
@end ifinfo
desk-top calculator.
These examples are simple, but Bison grammars for real programming
-languages are written the same way.
-@ifinfo
-You can copy these examples out of the Info file and into a source file
-to try them.
-@end ifinfo
+languages are written the same way. You can copy these examples into a
+source file to try them.
@menu
* RPN Calc:: Reverse polish notation calculator;
The groupings of the rpcalc ``language'' defined here are the expression
(given the name @code{exp}), the line of input (@code{line}), and the
complete input transcript (@code{input}). Each of these nonterminal
-symbols has several alternate rules, joined by the @samp{|} punctuator
+symbols has several alternate rules, joined by the vertical bar @samp{|}
which is read as ``or''. The following sections explain what these rules
mean.
Multiple rules for the same @var{result} can be written separately or can
be joined with the vertical-bar character @samp{|} as follows:
-@ifinfo
-@example
-@var{result}: @var{rule1-components}@dots{}
- | @var{rule2-components}@dots{}
- @dots{}
- ;
-@end example
-@end ifinfo
-@iftex
@example
@group
@var{result}: @var{rule1-components}@dots{}
;
@end group
@end example
-@end iftex
@noindent
They are still considered distinct rules even when joined in this way.
@deffn {Directive} %name-prefix="@var{prefix}"
Rename the external symbols used in the parser so that they start with
@var{prefix} instead of @samp{yy}. The precise list of symbols renamed
+in C parsers
is @code{yyparse}, @code{yylex}, @code{yyerror}, @code{yynerrs},
@code{yylval}, @code{yylloc}, @code{yychar}, @code{yydebug}, and
possible @code{yylloc}. For example, if you use
@samp{%name-prefix="c_"}, the names become @code{c_parse}, @code{c_lex},
-and so on. @xref{Multiple Parsers, ,Multiple Parsers in the Same
-Program}.
+and so on. In C++ parsers, it is only the surrounding namespace which is
+named @var{prefix} instead of @samp{yy}.
+@xref{Multiple Parsers, ,Multiple Parsers in the Same Program}.
@end deffn
@ifset defaultprec
@item -b @var{file-prefix}
@itemx --file-prefix=@var{prefix}
-Pretend that @code{%verbose} was specified, i.e, specify prefix to use
+Pretend that @code{%file-prefix} was specified, i.e, specify prefix to use
for all Bison output file names. @xref{Decl Summary}.
@item -r @var{things}
@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.
-@tex
-\def\leaderfill{\leaders\hbox to 1em{\hss.\hss}\hfill}
-
-{\tt
-\line{ --debug \leaderfill -t}
-\line{ --defines \leaderfill -d}
-\line{ --file-prefix \leaderfill -b}
-\line{ --graph \leaderfill -g}
-\line{ --help \leaderfill -h}
-\line{ --name-prefix \leaderfill -p}
-\line{ --no-lines \leaderfill -l}
-\line{ --no-parser \leaderfill -n}
-\line{ --output \leaderfill -o}
-\line{ --print-localedir}
-\line{ --token-table \leaderfill -k}
-\line{ --verbose \leaderfill -v}
-\line{ --version \leaderfill -V}
-\line{ --yacc \leaderfill -y}
-}
-@end tex
-
-@ifinfo
-@example
---debug -t
---defines=@var{defines-file} -d
---file-prefix=@var{prefix} -b @var{file-prefix}
---graph=@var{graph-file} -d
---help -h
---name-prefix=@var{prefix} -p @var{name-prefix}
---no-lines -l
---no-parser -n
---output=@var{outfile} -o @var{outfile}
---print-localedir
---token-table -k
---verbose -v
---version -V
---yacc -y
-@end example
-@end ifinfo
+@multitable {@option{--defines=@var{defines-file}}} {@option{-b @var{file-prefix}XXX}}
+@headitem Long Option @tab Short Option
+@item @option{--debug} @tab @option{-t}
+@item @option{--defines=@var{defines-file}} @tab @option{-d}
+@item @option{--file-prefix=@var{prefix}} @tab @option{-b @var{file-prefix}}
+@item @option{--graph=@var{graph-file}} @tab @option{-d}
+@item @option{--help} @tab @option{-h}
+@item @option{--name-prefix=@var{prefix}} @tab @option{-p @var{name-prefix}}
+@item @option{--no-lines} @tab @option{-l}
+@item @option{--no-parser} @tab @option{-n}
+@item @option{--output=@var{outfile}} @tab @option{-o @var{outfile}}
+@item @option{--print-localedir} @tab
+@item @option{--token-table} @tab @option{-k}
+@item @option{--verbose} @tab @option{-v}
+@item @option{--version} @tab @option{-V}
+@item @option{--yacc} @tab @option{-y}
+@end multitable
@node Yacc Library
@section Yacc Library
@c - Always pure
@c - initial action
-The C++ parser @acronym{LALR}(1) skeleton is named @file{lalr1.cc}. To select
-it, you may either pass the option @option{--skeleton=lalr1.cc} to
-Bison, or include the directive @samp{%skeleton "lalr1.cc"} in the
+The C++ parser @acronym{LALR}(1) skeleton is named @file{lalr1.cc}. To
+select it, you may either pass the option @option{--skeleton=lalr1.cc}
+to Bison, or include the directive @samp{%skeleton "lalr1.cc"} in the
grammar preamble. When run, @command{bison} will create several
-files:
+entities in the @samp{yy} namespace. Use the @samp{%name-prefix}
+directive to change the namespace name, see @ref{Decl Summary}. The
+various classes are generated in the following files:
+
@table @file
@item position.hh
@itemx location.hh
/* By default yylex returns int, we use token_type.
Unfortunately yyterminate by default returns 0, which is
not of token_type. */
-#define yyterminate() return token::END
+#define yyterminate() return token::END
%@}
@end example
%@{
typedef yy::calcxx_parser::token token;
%@}
- /* Convert ints to the actual type of tokens. */
+ /* Convert ints to the actual type of tokens. */
[-+*/] return yy::calcxx_parser::token_type (yytext[0]);
":=" return token::ASSIGN;
@{int@} @{
are addressed.
@menu
-* Memory Exhausted:: Breaking the Stack Limits
-* How Can I Reset the Parser:: @code{yyparse} Keeps some State
-* Strings are Destroyed:: @code{yylval} Loses Track of Strings
-* Implementing Gotos/Loops:: Control Flow in the Calculator
+* Memory Exhausted:: Breaking the Stack Limits
+* How Can I Reset the Parser:: @code{yyparse} Keeps some State
+* Strings are Destroyed:: @code{yylval} Loses Track of Strings
+* Implementing Gotos/Loops:: Control Flow in the Calculator
+* Secure? Conform?:: Is Bison @acronym{POSIX} safe?
+* I can't build Bison:: Troubleshooting
+* Where can I find help?:: Troubleshouting
+* Bug Reports:: Troublereporting
+* Other Languages:: Parsers in Java and others
+* Beta Testing:: Experimenting development versions
+* Mailing Lists:: Meeting other Bison users
@end menu
@node Memory Exhausted
This error is probably the single most frequent ``bug report'' sent to
Bison lists, but is only concerned with a misunderstanding of the role
-of scanner. Consider the following Lex code:
+of the scanner. Consider the following Lex code:
@verbatim
%{
invited to consult the dedicated literature.
+@node Secure? Conform?
+@section Secure? Conform?
+
+@display
+Is Bison secure? Does it conform to POSIX?
+@end display
+
+If you're looking for a guarantee or certification, we don't provide it.
+However, Bison is intended to be a reliable program that conforms to the
+@acronym{POSIX} specification for Yacc. If you run into problems,
+please send us a bug report.
+
+@node I can't build Bison
+@section I can't build Bison
+
+@display
+I can't build Bison because @command{make} complains that
+@code{msgfmt} is not found.
+What should I do?
+@end display
+
+Like most GNU packages with internationalization support, that feature
+is turned on by default. If you have problems building in the @file{po}
+subdirectory, it indicates that your system's internationalization
+support is lacking. You can re-configure Bison with
+@option{--disable-nls} to turn off this support, or you can install GNU
+gettext from @url{ftp://ftp.gnu.org/gnu/gettext/} and re-configure
+Bison. See the file @file{ABOUT-NLS} for more information.
+
+
+@node Where can I find help?
+@section Where can I find help?
+
+@display
+I'm having trouble using Bison. Where can I find help?
+@end display
+
+First, read this fine manual. Beyond that, you can send mail to
+@email{help-bison@@gnu.org}. This mailing list is intended to be
+populated with people who are willing to answer questions about using
+and installing Bison. Please keep in mind that (most of) the people on
+the list have aspects of their lives which are not related to Bison (!),
+so you may not receive an answer to your question right away. This can
+be frustrating, but please try not to honk them off; remember that any
+help they provide is purely voluntary and out of the kindness of their
+hearts.
+
+@node Bug Reports
+@section Bug Reports
+
+@display
+I found a bug. What should I include in the bug report?
+@end display
+
+Before you send a bug report, make sure you are using the latest
+version. Check @url{ftp://ftp.gnu.org/pub/gnu/bison/} or one of its
+mirrors. Be sure to include the version number in your bug report. If
+the bug is present in the latest version but not in a previous version,
+try to determine the most recent version which did not contain the bug.
+
+If the bug is parser-related, you should include the smallest grammar
+you can which demonstrates the bug. The grammar file should also be
+complete (i.e., I should be able to run it through Bison without having
+to edit or add anything). The smaller and simpler the grammar, the
+easier it will be to fix the bug.
+
+Include information about your compilation environment, including your
+operating system's name and version and your compiler's name and
+version. If you have trouble compiling, you should also include a
+transcript of the build session, starting with the invocation of
+`configure'. Depending on the nature of the bug, you may be asked to
+send additional files as well (such as `config.h' or `config.cache').
+
+Patches are most welcome, but not required. That is, do not hesitate to
+send a bug report just because you can not provide a fix.
+
+Send bug reports to @email{bug-bison@@gnu.org}.
+
+@node Other Languages
+@section Other Languages
+
+@display
+Will Bison ever have C++ support? How about Java or @var{insert your
+favorite language here}?
+@end display
+
+C++ support is there now, and is documented. We'd love to add other
+languages; contributions are welcome.
+
+@node Beta Testing
+@section Beta Testing
+
+@display
+What is involved in being a beta tester?
+@end display
+
+It's not terribly involved. Basically, you would download a test
+release, compile it, and use it to build and run a parser or two. After
+that, you would submit either a bug report or a message saying that
+everything is okay. It is important to report successes as well as
+failures because test releases eventually become mainstream releases,
+but only if they are adequately tested. If no one tests, development is
+essentially halted.
+
+Beta testers are particularly needed for operating systems to which the
+developers do not have easy access. They currently have easy access to
+recent GNU/Linux and Solaris versions. Reports about other operating
+systems are especially welcome.
+
+@node Mailing Lists
+@section Mailing Lists
+
+@display
+How do I join the help-bison and bug-bison mailing lists?
+@end display
+
+See @url{http://lists.gnu.org/}.
@c ================================================= Table of Symbols
projects / bison.git / blobdiff