manpagesection(8.1. THE SCANNER BASE CLASS)

    By default, flc() generates a file tt(Scannerbase.h) containing the
interface of the base class of the scanner class also generated by flc(). The
name of the file that is generated can easily be changed using flc()'s
tt(--baseclass-header) option. In this man-page we use the default name.

    The file tt(Scannerbase.h) is generated at each new flc() run. It contains
no user-serviceable or extensible parts. Rewriting can be prevented by
specifying flc()'s tt(--no-baseclass-header) option).

manpagesection(8.2. PUBLIC ENUMS AND -TYPES)

    itemization(
    itb(enum class StartCondition__)
        This strongly typed enumeration defines the names of the start
conditions (i.e., mini scanners). It at least contains tt(INITIAL), but when
the tt(%s) or tt(%x) directives were used it also contains the identifiers of
the mini scanners declared by these directives. Since tt(StartCondition__) is
a strongly typed enum its values must be preceded by its enum name. E.g.,
        verb(
    begin(StartCondition__::INITIAL);
        )
    )

manpagesection(8.3. PROTECTED ENUMS AND -TYPES)

    itemization(
    itb(enum class ActionType__)
        This strongly typed enumeration is for internal use only.
    itb(enum Leave__)
        This enumeration is for internal use only.
    )

manpagesection(8.4. NO PUBLIC CONSTRUCTORS)

    There are no public constructors. tt(ScannerBase) is a base class for the
tt(Scanner) class generated by flc(). tt(ScannerBase) only offers 
protected constructors.

manpagesection(8.5. PUBLIC MEMBER FUNCTIONS)

    itemization(
    itb(bool debug() const)
       returns tt(true) if tt(--debug) or tt(%debug) was specified, otherwise
        tt(false).

    itb(bool interactiveLine())
       this member is only available with interactive scanners. All remaining
        contents of the current interactive line buffer is discarded, and the
        interactive line buffer is filled with the contents of the next input
        line. This member can be used when a condition is encountered which
        invalidates the remaining contents of a line. Following a call to
        tt(interactiveLine) the next token that is returned by the lexical
        scanner will be the first token on the next line. This member returns
        tt(true) if the next line is available and tt(false) otherwise.

    itb(std::string const  &filename()  const)
       returns the name of the file currently processed by the scanner object.
    itb(size_t              length()    const)
       returns the length of the text that was matched by tt(lex). With
        bf(flex++) this function was called tt(leng).
    itb(size_t              lineNr()    const)
       returns the line number of the currently scanned line. This function is
        always available (note: bf(flex++) only offered a similar function
        (called tt(lineno)) after using the tt(%lineno) option).
    itb(std::string const  &matched()   const)
       returns the text matched by tt(lex) (note: bf(flex++) offers a similar
        member called tt(YYText)).
    itb(void setDebug(bool onOff))
       Switches on/off  debugging output by providing the argument tt(true)
        or tt(false). Switching on debugging output only has visible effects
        if the tt(debug) option was specified.

    itb(void switchIstream(std::string const &infilename))
       The currently processed input stream is closed, and processing
        continues at the stream whose name is specified as the function's
        argument. This is em(not) a stack-operation: after processing
        tt(infilename) processing does not return to the original stream.

        bf(This member is not available with interactive scanners.)

    itb(void switchOstream(std::ostream &out))
       The currently processed output stream is closed, and
        new output is written to tt(out). 

    itb(void switchOstream(std::string const &outfilename))

       The current output stream is closed, and output is written to
        tt(outfilename). If this file already exists, it is rewritten.

    itb(void switchStreams(std::istream &in,
                                      std::ostream &out = std::cout))
       The currently processed input and output streams are closed, and
        processing continues at tt(in), writing output to tt(out). This is
        em(not) a stack-operation: after processing tt(in) processing
        does not return to the original stream.

        bf(This member is not available with interactive scanners.)

    itb(void switchStreams(std::string const &infilename,
                                      std::string const &outfilename))
       The currently processed input and output streams are closed, and
        processing continues at the stream whose name is specified as the
        function's first argument, writing output to the file whose name is
        specified as the function's second argument. This latter file is
        rewritten. This is em(not) a stack-operation: after processing
        tt(infilename) processing does not return to the original stream.
        If tt(outfilename == "-") then the standard output stream
        is used as the scanner's output medium; if tt(outfilename == "") then
        the standard error stream is used as the scanner's output medium.

        If tt(outfilename == "-") then the standard output stream
        is used as the scanner's output medium; if tt(outfilename == "") then
        the standard error stream is used as the scanner's output medium.

        bf(This member is not available with interactive scanners.)

    )

manpagesection(8.6. PROTECTED CONSTRUCTORS)

    itemization(
    itb(ScannerBase(std::string const &infilename, 
                                std::string const &outfilename))
       The scanner object opens and reads tt(infilename) and opens (rewrites)
        and writes tt(outfilename). It is called from the corresponding
        tt(Scanner) constructor.

        bf(This member is not available for interactive scanners.)

    itb(ScannerBase(std::istream &in, std::ostream &out))
       The tt(in) and tt(out) parameters are, respectively, the derived class
        constructor's input stream and output streams.
    )

manpagesection(8.7. PROTECTED MEMBER FUNCTIONS)

    All member functions ending in two underscore characters are for internal
        use only and should not be called by user-defined members of the
        tt(Scanner) class. 

    The following members, however, can safely be called by members of the
        generated tt(Scanner) class:

    itemization(
    itb(void accept(size_t nChars = 0))
       tt(accept(n)) returns all but the first `nChars' characters of the
        current token back to the input stream, where they will be rescanned
        when the scanner looks for the next match.  So, it matches `nChars' of
        the characters in the input buffer, rescanning the rest. This function
        effectively sets tt(length)'s return value to tt(nChars) (note: with
        bf(flex++) this function was called tt(less));

    itb(void begin(StartCondition__ startCondition))
       activate the regular expression rules associated with
        tt(StartCondition__ startCondition). As this enumeration is a strongly
        typed enum the tt(StartCondition__) scope must be specified as
        well. E.g., 
            verb(
        begin(StartCondition__::INITIAL);
            )

    itb(void echo() const) 
       The currently matched text (i.e., the text returned by the member
        tt(matched)) is inserted into the scanner object's output stream;

    itb(void leave(int retValue))
       actions defined in the lexical scanner specification file may or may
        not return. This frequently results in complicated or overlong
        compound statements, blurring the readability of the specification
        file. By encapsulating the actions in a member function readability is
        enhanced. However, frequently a compound statement is still required,
        as in:
            verb(
    regex-to-match  {
                        if (int ret = memberFunction())
                            return ret;
                    }
            )
        The member tt(leave) removes the need for constructions like the
        above. The member tt(leave) can be called from within member
        functions encapsulating actions performed when a regular expression
        has been matched. It ends tt(lex), returning tt(retValue) to its
        caller. The above rule can now be written like this:
            verb(
    regex-to-match  memberFunction();
            )
        and tt(memberFunction) could be implemented as follows:
            verb(
    void memberFunction()
    {
        if (someCondition())
        {                           // any action, e.g., 
                                    // switch mini-scanner
            begin(StartCondition__::INITIAL);

            leave(Parser::TOKENVALUE);    // lex returns TOKENVALUE
            // this point is never reached
        }
    
        pushStream(d_matched);      // switch to the next stream
                                    // lex continues
    }
            )
       The member tt(leave) should only (indirectly) be called 
        (usually nested) from actions defined in the scanner's specification
        file(s); calling tt(leave) outside of this context results in
        undefined behavior.

    itb(void more())
       the matched text is kept and will be prefixed to the text that is
        matched at the next lexical scan;

    itb(std::ostream &out())
       returns a reference to the scanner's output stream;

    itb(bool popStream())
       closes the currently processed input stream and continues to process
        the most recently stacked input stream (removing it from the stack of
        streams). If this switch was successfully performed tt(true) is
        returned, otherwise (e.g., when the stream stack is empty) tt(false)
        is returned;

    itb(void push(size_t ch))
       character tt(ch) is pushed back onto the input stream. I.e., it will be
        the character that is retrieved at the next attempt to obtain a
        character from the input stream;

    itb(void push(std::string const &txt))
       the characters in the string tt(txt) are pushed back onto the input
        stream. I.e., they will be the characters that are retrieved at the
        next attempt to obtain characters from the input stream. The
        characters in tt(txt) are retrieved from the first character to the
        last. So if tt(txt == "hello") then the tt('h') will be the character
        that's retrieved next, followed by tt('e'), etc, until tt('o');

    itb(void pushStream(std::istream &curStream))
        this function pushes tt(curStream) on the stream stack;

        bf(This member is not available with interactive scanners.)

    itb(void pushStream(std::string const &curName))
       same, but the stream tt(curName) is opened first, and the resulting
        tt(istream) is pushed on the stream stack;

        bf(This member is not available with interactive scanners.)

    itb(void redo(size_t nChars = 0))
       this member acts like tt(accept) but its argument counts backward from
        the end of the matched text. All but these tt(nChars) characters are
        kept and the last tt(nChar) characters are rescanned. This function
        effectively reduces tt(length)'s return value by tt(nChars);

    itb(void setFilename(std::string const &name))
       this function sets the name of the stream returned by tt(filename) to
        tt(name);

    itb(void setMatched(std::string const &text))
       this function stores tt(text) in the matched text buffer. Following a
        call to this function tt(matched) returns tt(text).

    itb(StartCondition__  startCondition() const)
       returns the currently active start condition (mini scanner);

    itb(std::vector<StreamStruct> const &streamStack() const)
       returns the vector of currently stacked input streams. The vector's
        size equals 0 unless tt(pushStream) has been used. So flc()'s input
        file is not counted here. The tt(StreamStruct) is a tt(struct) only
        having one accessible member: tt(std::string const &pushedName), which
        holds the name of the pushed stream. The vector is used internally 
        as a stack: the stream that was first pushed is found at index
        position 0, the most recently pushed stream is found at
        tt(streamStack().back()). 

        bf(This member is not available with interactive scanners.)

    )

manpagesection(8.8. PROTECTED DATA MEMBERS)

    All protected data members are for internal use only, allowing tt(lex__)
to access them. All of them end in two underscore characters.

manpagesection(8.9. FLEX++ TO FLEXC++ MEMBERS)
    
setmanalign(lcl)
table(3)(lcl)(
    rowline()   
    row(cell(Flex++ (old))  cell()  cell(Flexc++ (new)))
    rowline()   
    row(cell(tt(lineno()))    cell()  cell(tt(lineNr())))
    row(cell(tt(YYText()))    cell()  cell(tt(matched())))
    row(cell(tt(less()))      cell()  cell(tt(accept())))
    rowline()   
)
