manpagesection(8. 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(9. 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(10. 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.
    itb(enum class PostEnum_)
        Values of this strongly typed enumeration are passed to the scanner's
        private member tt(postCode), indicating the scanner's action after
        matching a rule. The values of this enumeration are:

        tt(PostEnum_::END): the function tt(lex_)  immediately returns 0
            once tt(postCode) returns, indicating the end of the input was
            reached;

        tt(PostEnum_::POP): the end of an input stream was reached, and
            processing continues with the previously pushed input stream. In
            this case the function tt(lex_) doesn't return, it simply
            coontinues processing the previously pushed stream;

        tt(PostEnum_::RETURN): the function tt(lex_) immediately returns 
            once tt(postCode) returns, returning the next token;

        tt(PostEnum_::WIP): the function tt(lex_) has matched a
            non-returning rule, and continues its rule-matching process.
    )

manpagesection(11. 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(12. PUBLIC MEMBER FUNCTIONS)

    itemization(
    itb(std::string const &cwd() const)
       return the working directory that was active when the tt(Scanner's)
        constructor is called. It is also the program's current working
        directory after constructing a tt(Scanner) object and when its
        tt(lex) member returns.

    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.

includefile(streamswitching.yo)
    )

manpagesection(13. PROTECTED CONSTRUCTORS)

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

    By default (tt(keepCwd == true)) the directory that was active when
tt(ScannerBase) was constructed is made current again once the scanning
process ends (i.e., when tt(Scanner::lex_()) returns 0).

    When tt(keepCwd == false) the scanner doesn't reset its working directory
to the directory that was current when the tt(ScannerBase) was
constructed. This may be convenient in situations where a program repeatedly
calls tt(switchStream()), followed by full lexical scans of the switched-to
streams.
    
        bf(This constructor is not available for interactive scanners.)

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

       The parameter tt(keepCwd) is used as with the previous constructor.
    )

manpagesection(14. PROTECTED MEMBER FUNCTIONS)

    All member functions ending in an underscore character 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. If the stream stack
        (cf. the member tt(streamStack())) contains multiple elements then the
        most recently pushed element is removed and processing continues with
        the then final element of the tt(streamStack). If this switch was
        successfully performed tt(true) is returned. If the stream stack
        contains only one element then all information has been processed and
        tt(false) is returned. This member is called automatically at the end
        of the currently processed input stream. After completely processing
        the initial  input file the member tt(lex) returns 0.

       When the tt(<<EOF>>) pattern is used in the scanner's specification
        file tt(popStream) is not automatically called. In that case it should
        explicitly be called in the tt(<<EOF>>) pattern's action block,
        returning 0 when it returns tt(false). E.g.,
    verb(
    <<EOF>> {
                if (not popStream())
                    return 0;
                cerr << "WIP on " << streamStack().size() << 
                    "file(s)\n";
            }
    )

    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. If tt(curName) does not
        exist a tt(std::exception) is thrown. An exception is also thrown when
        the stream stack size exceeds (by default) 10 (the option
        tt(max-depth) can be used to change the default). 

        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. Starting with
        flc() version 2.08.00 the size and content of the information in this
        vector has been changed. Starting with version 2.08.00 its size is at
        least 1. Its size is incremented at every tt(pushStream) call, and
        decremented at every tt(poStream) call.

        The tt(StreamStruct) itself is a tt(struct) having only one documented
        member: tt(std::string const &pushedName), containing the absolute
        pathname of the initial and pushed streams. 

        Internally, tt(streamStack) vector is used as a stack. The pathname
        of the file that was specified at the scanner's construction time is
        found at index position 0, and pathname of the file that's currently
        being processed is found at tt(streamStack().back()). Switching input
        streams changes the pathname at tt(streamStack().back()), and if the
        pathname of a stream cannot be determined (which happens when
        constructing a scanner from or switching to a tt(std::istream)) then
        the program's current working directory is not altered and
        tt(pushedName) contains tt((istream)). 

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

    )

manpagesection(15. PROTECTED DATA MEMBERS)

    All protected data members are for internal use only, allowing tt(lex_)
to access them. All of them end in an underscore character.

manpagesection(16. 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()   
)
