+@comment file: calc++-driver.hh
+@example
+ // Error handling.
+ void error (const yy::location& l, const std::string& m);
+ void error (const std::string& m);
+@};
+#endif // ! CALCXX_DRIVER_HH
+@end example
+
+The implementation of the driver is straightforward. The @code{parse}
+member function deserves some attention. The @code{error} functions
+are simple stubs, they should actually register the located error
+messages and set error state.
+
+@comment file: calc++-driver.cc
+@example
+#include "calc++-driver.hh"
+#include "calc++-parser.hh"
+
+calcxx_driver::calcxx_driver ()
+ : trace_scanning (false), trace_parsing (false)
+@{
+ variables["one"] = 1;
+ variables["two"] = 2;
+@}
+
+calcxx_driver::~calcxx_driver ()
+@{
+@}
+
+void
+calcxx_driver::parse (const std::string &f)
+@{
+ file = f;
+ scan_begin ();
+ yy::calcxx_parser parser (*this);
+ parser.set_debug_level (trace_parsing);
+ parser.parse ();
+ scan_end ();
+@}
+
+void
+calcxx_driver::error (const yy::location& l, const std::string& m)
+@{
+ std::cerr << l << ": " << m << std::endl;
+@}
+
+void
+calcxx_driver::error (const std::string& m)
+@{
+ std::cerr << m << std::endl;
+@}
+@end example
+
+@node Calc++ Parser
+@subsection Calc++ Parser
+
+The parser definition file @file{calc++-parser.yy} starts by asking for
+the C++ LALR(1) skeleton, the creation of the parser header file, and
+specifies the name of the parser class. Because the C++ skeleton
+changed several times, it is safer to require the version you designed
+the grammar for.
+
+@comment file: calc++-parser.yy
+@example
+%skeleton "lalr1.cc" /* -*- C++ -*- */
+%require "2.1a"
+%defines
+%define "parser_class_name" "calcxx_parser"
+@end example
+
+@noindent
+@findex %requires
+Then come the declarations/inclusions needed to define the
+@code{%union}. Because the parser uses the parsing driver and
+reciprocally, both cannot include the header of the other. Because the
+driver's header needs detailed knowledge about the parser class (in
+particular its inner types), it is the parser's header which will simply
+use a forward declaration of the driver.
+@xref{Table of Symbols, ,%requires}.
+
+@comment file: calc++-parser.yy
+@example
+%requires @{
+# include <string>
+class calcxx_driver;
+@}
+@end example
+
+@noindent
+The driver is passed by reference to the parser and to the scanner.
+This provides a simple but effective pure interface, not relying on
+global variables.
+
+@comment file: calc++-parser.yy
+@example
+// The parsing context.
+%parse-param @{ calcxx_driver& driver @}
+%lex-param @{ calcxx_driver& driver @}
+@end example
+
+@noindent
+Then we request the location tracking feature, and initialize the
+first location's file name. Afterwards new locations are computed
+relatively to the previous locations: the file name will be
+automatically propagated.
+
+@comment file: calc++-parser.yy
+@example
+%locations
+%initial-action
+@{
+ // Initialize the initial location.
+ @@$.begin.filename = @@$.end.filename = &driver.file;
+@};
+@end example
+
+@noindent
+Use the two following directives to enable parser tracing and verbose
+error messages.
+
+@comment file: calc++-parser.yy
+@example
+%debug
+%error-verbose
+@end example
+
+@noindent
+Semantic values cannot use ``real'' objects, but only pointers to
+them.
+
+@comment file: calc++-parser.yy
+@example
+// Symbols.
+%union
+@{
+ int ival;
+ std::string *sval;
+@};
+@end example
+
+@noindent
+@findex %code
+The code between @samp{%code @{} and @samp{@}} is output in the
+@file{*.cc} file; it needs detailed knowledge about the driver.
+
+@comment file: calc++-parser.yy
+@example
+%code @{
+# include "calc++-driver.hh"
+@}
+@end example
+
+
+@noindent
+The token numbered as 0 corresponds to end of file; the following line
+allows for nicer error messages referring to ``end of file'' instead
+of ``$end''. Similarly user friendly named are provided for each
+symbol. Note that the tokens names are prefixed by @code{TOKEN_} to
+avoid name clashes.
+
+@comment file: calc++-parser.yy
+@example
+%token END 0 "end of file"
+%token ASSIGN ":="
+%token <sval> IDENTIFIER "identifier"
+%token <ival> NUMBER "number"
+%type <ival> exp "expression"
+@end example
+
+@noindent
+To enable memory deallocation during error recovery, use
+@code{%destructor}.
+
+@c FIXME: Document %printer, and mention that it takes a braced-code operand.
+@comment file: calc++-parser.yy
+@example
+%printer @{ debug_stream () << *$$; @} "identifier"
+%destructor @{ delete $$; @} "identifier"
+
+%printer @{ debug_stream () << $$; @} "number" "expression"
+@end example
+
+@noindent
+The grammar itself is straightforward.
+
+@comment file: calc++-parser.yy
+@example
+%%
+%start unit;
+unit: assignments exp @{ driver.result = $2; @};
+
+assignments: assignments assignment @{@}
+ | /* Nothing. */ @{@};
+
+assignment:
+ "identifier" ":=" exp
+ @{ driver.variables[*$1] = $3; delete $1; @};
+
+%left '+' '-';
+%left '*' '/';
+exp: exp '+' exp @{ $$ = $1 + $3; @}
+ | exp '-' exp @{ $$ = $1 - $3; @}
+ | exp '*' exp @{ $$ = $1 * $3; @}
+ | exp '/' exp @{ $$ = $1 / $3; @}
+ | "identifier" @{ $$ = driver.variables[*$1]; delete $1; @}
+ | "number" @{ $$ = $1; @};
+%%
+@end example
+
+@noindent
+Finally the @code{error} member function registers the errors to the
+driver.
+
+@comment file: calc++-parser.yy
+@example
+void
+yy::calcxx_parser::error (const yy::calcxx_parser::location_type& l,
+ const std::string& m)
+@{
+ driver.error (l, m);
+@}
+@end example
+
+@node Calc++ Scanner
+@subsection Calc++ Scanner
+
+The Flex scanner first includes the driver declaration, then the
+parser's to get the set of defined tokens.
+
+@comment file: calc++-scanner.ll
+@example
+%@{ /* -*- C++ -*- */
+# include <cstdlib>
+# include <errno.h>
+# include <limits.h>
+# include <string>
+# include "calc++-driver.hh"
+# include "calc++-parser.hh"
+
+/* Work around an incompatibility in flex (at least versions
+ 2.5.31 through 2.5.33): it generates code that does
+ not conform to C89. See Debian bug 333231
+ <http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=333231>. */
+# undef yywrap
+# define yywrap() 1
+
+/* 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
+%@}
+@end example
+
+@noindent
+Because there is no @code{#include}-like feature we don't need
+@code{yywrap}, we don't need @code{unput} either, and we parse an
+actual file, this is not an interactive session with the user.
+Finally we enable the scanner tracing features.
+
+@comment file: calc++-scanner.ll
+@example
+%option noyywrap nounput batch debug
+@end example
+
+@noindent
+Abbreviations allow for more readable rules.
+
+@comment file: calc++-scanner.ll
+@example
+id [a-zA-Z][a-zA-Z_0-9]*
+int [0-9]+
+blank [ \t]
+@end example
+
+@noindent
+The following paragraph suffices to track locations accurately. Each
+time @code{yylex} is invoked, the begin position is moved onto the end
+position. Then when a pattern is matched, the end position is
+advanced of its width. In case it matched ends of lines, the end
+cursor is adjusted, and each time blanks are matched, the begin cursor
+is moved onto the end cursor to effectively ignore the blanks
+preceding tokens. Comments would be treated equally.
+
+@comment file: calc++-scanner.ll
+@example
+%@{
+# define YY_USER_ACTION yylloc->columns (yyleng);
+%@}
+%%
+%@{
+ yylloc->step ();
+%@}
+@{blank@}+ yylloc->step ();
+[\n]+ yylloc->lines (yyleng); yylloc->step ();
+@end example
+
+@noindent
+The rules are simple, just note the use of the driver to report errors.
+It is convenient to use a typedef to shorten
+@code{yy::calcxx_parser::token::identifier} into
+@code{token::identifier} for instance.
+
+@comment file: calc++-scanner.ll
+@example
+%@{
+ typedef yy::calcxx_parser::token token;
+%@}
+ /* Convert ints to the actual type of tokens. */
+[-+*/] return yy::calcxx_parser::token_type (yytext[0]);
+":=" return token::ASSIGN;
+@{int@} @{
+ errno = 0;
+ long n = strtol (yytext, NULL, 10);
+ if (! (INT_MIN <= n && n <= INT_MAX && errno != ERANGE))
+ driver.error (*yylloc, "integer is out of range");
+ yylval->ival = n;
+ return token::NUMBER;
+@}
+@{id@} yylval->sval = new std::string (yytext); return token::IDENTIFIER;
+. driver.error (*yylloc, "invalid character");
+%%
+@end example
+
+@noindent
+Finally, because the scanner related driver's member function depend
+on the scanner's data, it is simpler to implement them in this file.
+
+@comment file: calc++-scanner.ll
+@example
+void
+calcxx_driver::scan_begin ()
+@{
+ yy_flex_debug = trace_scanning;
+ if (!(yyin = fopen (file.c_str (), "r")))
+ error (std::string ("cannot open ") + file);
+@}
+
+void
+calcxx_driver::scan_end ()
+@{
+ fclose (yyin);
+@}
+@end example
+
+@node Calc++ Top Level
+@subsection Calc++ Top Level
+
+The top level file, @file{calc++.cc}, poses no problem.
+
+@comment file: calc++.cc
+@example
+#include <iostream>
+#include "calc++-driver.hh"
+
+int
+main (int argc, char *argv[])
+@{
+ calcxx_driver driver;
+ for (++argv; argv[0]; ++argv)
+ if (*argv == std::string ("-p"))
+ driver.trace_parsing = true;
+ else if (*argv == std::string ("-s"))
+ driver.trace_scanning = true;
+ else
+ @{
+ driver.parse (*argv);
+ std::cout << driver.result << std::endl;
+ @}
+@}
+@end example
+
+@c ================================================= FAQ
+
+@node FAQ
+@chapter Frequently Asked Questions
+@cindex frequently asked questions
+@cindex questions
+
+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
+* Multiple start-symbols:: Factoring closely related grammars
+* 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
+@section Memory Exhausted
projects / bison.git / blobdiff