X-Git-Url: https://git.saurik.com/bison.git/blobdiff_plain/c095d689c3f0189dedd012c1d0e16f2402c26f54..1bddda4d85d1d9431a05699ce1aae40e865de797:/doc/bison.texinfo diff --git a/doc/bison.texinfo b/doc/bison.texinfo index 69034042..022510b8 100644 --- a/doc/bison.texinfo +++ b/doc/bison.texinfo @@ -12,25 +12,15 @@ @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 @@ -67,9 +57,6 @@ Copies published by the Free Software Foundation raise funds for * 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 @@ -324,6 +311,13 @@ Frequently Asked Questions * 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 @@ -508,8 +502,8 @@ int /* @r{keyword `int'} */ 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 @@ -1361,11 +1355,8 @@ under BSD Unix 4.3; each produces a usable, though limited, interactive 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; @@ -1484,7 +1475,7 @@ exp: NUM @{ $$ = $1; @} 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. @@ -2929,15 +2920,6 @@ Usually there is only one action and it follows the components. 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{} @@ -2946,7 +2928,6 @@ be joined with the vertical-bar character @samp{|} as follows: ; @end group @end example -@end iftex @noindent They are still considered distinct rules even when joined in this way. @@ -4237,12 +4218,14 @@ accurate syntax error messages. @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 @@ -6913,7 +6896,7 @@ Same as above, but save in the file @var{defines-file}. @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} @@ -6963,48 +6946,27 @@ the output graph file. @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 @@ -7059,11 +7021,14 @@ int yyparse (void); @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 @@ -7625,7 +7590,7 @@ parser's to get the set of defined tokens. /* 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 @@ -7683,7 +7648,7 @@ It is convenient to use a typedef to shorten %@{ 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@} @{ @@ -7758,10 +7723,17 @@ Several questions about Bison come up occasionally. Here some of them 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 @@ -7877,7 +7849,7 @@ them. Instead of reporting @samp{"foo", "bar"}, it reports 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 %{ @@ -7955,6 +7927,123 @@ This topic is way beyond the scope of this manual, and the reader is 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