    manpagesection(1. QUICK START)

    A bare-bones, no-frills scanner is generated as follows:

    itemization(
    it() First define a subdirectory tt(scanner), and change-dir to
tt(scanner). This directory is going to contain all scanner-related files,
created next.

    it() Create a file tt(lexer) defining the regular expressions to
recognize, and the tokens to return. Use token values exceeding 0xff when
plain ascii character values could also be used as token values. Example
(assume capitalized words are token-symbols defined in an enum defined by the
scanner class):
        verb(
%%
[ \t\n]+                            // skip white space chars.
[0-9]+                              return NUMBER;
[[:alpha:]_][[:alpha:][:digit:]_]*  return IDENTIFIER;
.                                   return matched()[0];
        )

    it() Execute:
        verb(
    flexc++ lexer
        )
    This generates four files: tt(Scanner.h, Scanner.ih, Scannerbase.h), and
tt(lex.cc).

    it() Edit tt(Scanner.h) to add the enum defining the token-symbols in
(usually) the public section of the class tt(Scanner). E.g.,
        verb(
class Scanner: public ScannerBase
{
    public:
        enum Tokens
        {
            IDENTIFIER = 0x100,
            NUMBER
        };
    // ... (etc, as generated by flexc++)
}
        )
    
    it() Change-dir to tt(scanner's) base directory, and there create a file
tt(main.cc) defining tt(int main):
        verb(
#include <iostream>
#include "scanner/Scanner.h"

using namespace std;

int main()
{
    Scanner scanner;        // define a Scanner object

    while (int token = scanner.lex())   // get all tokens
    {
        string const &text = scanner.matched();
        switch (token)
        {
            case Scanner::IDENTIFIER:
                cout << "identifier: " << text << '\n';
            break;

            case Scanner::NUMBER:
                cout << "number: " << text << '\n';
            break;

            default:
                cout << "char. token: `" << text << "'\n";
            break;
        }
    }
}
        )
    it() Compile all tt(.cc) files, creating tt(a.out):
        verb(
    g++ *.cc scanner/*.cc
        )
    
    it() To `tokenize' tt(main.cc), execute:
        verb(
    a.out < main.cc
        )
    )

    manpagesection(2. QUICK START: FLEXC++ and BISONC++)

To interface flc() to the bf(bisonc++)(1) parser generator proceed as follows:
    itemization(
    it() Start from the directory containing tt(main.cc) used in the previous
section; the lexical scanner developed there is also used here.
    it() Create a directory tt(parser) and change-dir to that directory.

    it() Define the following grammar in the file tt(grammar):
        verb(
%scanner        ../scanner/Scanner.h
%token-path     ../scanner/tokens.h
        
%token IDENTIFIER NUMBER CHAR

%%

startrule:
    startrule tokenshow
|
    tokenshow
;

tokenshow:
    token
    {
        std::cout << "matched: " << d_scanner.matched() << '\n';
    }
;

token:
    IDENTIFIER
|
    NUMBER
|
    CHAR
;
    )

    it() Create the parser by executing:
    verb(
bisonc++ grammar
    )
    This generates five files: tt(parse.cc, Parserbase.h, Parser.h,
tt(Parser.ih)) and tt(../scanner/tokens.h), where the last file contains 
the class tt(Tokens) defining the enumeration tt(Tokens_) specifying the
symbolic token names. 
    
    it() Now that the parser has been defined, edit the (three) lines in the
file tt(../scanner/lexer) containing return statements. Change these lines
as follows (the first two lines of the file tt(lexer) remain as-is):
    verb(
[0-9]+                              return Tokens::NUMBER;
[[:alpha:]_][[:alpha:][:digit:]_]*  return Tokens::IDENTIFIER;
.                                   return Tokens::CHAR;
    )
    This allows the scanner to  return tt(Parser) tokens to the generated
parser. 

    it() Modify the scanner so that it returns these tt(Parser) tokens
by executing:
        verb(
    flexc++ lexer
        )

    it() Next, add the line
        verb(
    #include "tokens.h"
        )
    to the file tt(scanner/Scanner.ih), informing the scanner about the
existence of the tokens expected by the parser. 

    If ever you have to use members from the parser's base class generated by
bf(bisonc++)(1), then 
        verb(
    #include "../parser/Parserbase.h"
        )
    should be added to the file tt(scanner/Scanner.ih). In that case including
the file tt(token.h) in tt(scanner/Scanner.ih) is optional.

    it() Change-dir to the tt(scanner's) parent directory and rewrite the
tt(main.cc) file defined in the previous section to contain:
    verb(
#include "parser/Parser.h"

int main(int argc, char **argv)
{
    Parser parser;
    parser.parse();
}
    )
    
    it() Compile all sources:
        verb(
    g++ *.cc */*.cc
        )

    it() Execute the program, providing it with some source file to be
processed:
        verb(
    a.out < main.cc
        )
        )

    manpagesection(3. GENERATED FILES)

Flc() generates four files from a well-formed input file:
    itemization(

    it() A file containing the implementation of the tt(lex) member function
and its support functions. By default this file is named tt(lex.cc).

    it() A file containing the scanner's class interface. By default this file
is named tt(Scanner.h). The scanner class itself is generated once and is
thereafter `owned' by the programmer, who may change it em(ad-lib). Newly
added members (data members, function members) will survive future flc() runs
as flc() will never rewrite an existing scanner class interface file, unless
explicitly ordered to do so. 

    it() A file containing the interface of the scanner class's em(base
class). The scanner class is publicly derived from this base class. It is used
to minimize the size of the scanner interface itself. The scanner base class
is `owned' by bf(flexc++) and should never be hand-modified. By
default the scanner's base class is provided in the file
tt(Scannerbase.h). At each new flc() run this file is rewritten unless flc()
is explicitly ordered em(not) to do so.

    it() A file containing the em(implementation header). This file should
contain includes and declarations that are only required when compiling the
members of the scanner class. By default this file is named
tt(Scanner.ih). This file, like the file containing the scanner class's
interface is never rewritten by flc() unless flc() is explicitly ordered to do
so.
    )

manpagesection(4. OPTIONS)

    includefile(../manual/intro/options)








