
manpagesection(9.1 THE CLASS INPUT)

    Flc() generates a file tt(Scannerbase.h) defining the scanner class's base
class, by default named tt(ScannerBase) (which is the name used in this
man-page). The base class tt(ScannerBase) contains a nested class tt(Input)
whose interface looks like this:
        verb(
class Input
{
    public:
        Input();
        Input(std::istream *iStream, size_t lineNr = 1);
        size_t get();
        size_t lineNr() const;          
        void reRead(size_t ch);
        void reRead(std::string const &str, size_t fmIdx);
        void close();
};
        )        
    The members of this class are all required and offer a level in between
the operations of tt(ScannerBase) and flc()'s actual input file that's being
processed. 

    By default, flc() provides an implementation for all of tt(Input)'s
required members. Therefore, in most situations this man-page can safely be
ignored.

    However, users may define and extend their own tt(Input) class and provide
flc()'s base class with that tt(Input) class. To do so flc()'s rules file must
contain the following two directives:
        verb(
       %input-implementation = "sourcefile"
       %input-interface = "interface"
        )
    Here, tt(interface) is the name of a file containing the class tt(Input)'s
interface. This interface is then inserted into tt(ScannerBase)'s interface
instead of the default class tt(Input)'s interface. This interface must em(at
least) offer the above-mentioned members and constructors (their functions are
described below). The class may contain additional members if required by the
user-defined implementation. The implementation itself is expected in
tt(sourcefile). The contents of this file are inserted in the generated
tt(lex.cc) file instead of tt(Input)'s  default implementation. The file
tt(sourcefile) should probably not have a tt(.cc) extension to prevent its
compilation by a program maintenance utility.

When the lexical scanner generated by flc() switches streams using the
tt(//include) directive (see section bf(6.1. FILE SWITCHING)) the input
stream that's currently processed is pushed on an tt(Input) stack maintained
by tt(ScannerBase), and processing continues at the file named at the
tt(//include) directive. Once the latter file has been processed, the
previously pushed stream is popped off the stack, and processing of the popped
stream continues. This implies that tt(Input) objects must be
`stack-able'. The required interface is designed to satisfy this requirement.


manpagesection(9.2. CONSTRUCTORS)

    itemization(
    itb(Input())
        The default constructor is used by bf(ScannerBase) to prepare the
stack for tt(Input) objects. It must make sure that a default (empty)
tt(Input) object is in a valid state and can be destroyed. It serves no
further purpose. tt(Input) objects, however, must support the default (or
overloaded) assignment operator.
    itb(Input(std::istream *iStream, size_t lineNr = 1))
        This constructor receives a pointer to a dynamically allocated
tt(istream) object. The tt(Input) constructor should preserve this pointer
when the tt(Input) object is pushed on and popped off the stack. A
tt(shared_ptr) probably comes in handy here. The tt(Input) object becomes the
owner of the tt(istream) object, albeit that its destructor is em(not)
supposed to destroy the tt(istream) object. Destruction remains the
responsibility of the tt(ScannerBase) object, which calls the tt(Input::close)
member (see below) when it's time to destroy (close) the stream.

        The new input stream's line counter is set to tt(lineNr), by default
1. 
    )

manpagesection(9.3. REQUIRED PUBLIC MEMBER FUNCTIONS)

    itemization(
    itb(size_t get())
        returns the next character to be processed by the lexical
scanner. Usually it will be the next character from the tt(istream) passed to
the tt(Input) class at construction time. It is never called by the
tt(ScannerBase) object for tt(Input) objects defined using tt(Input)'s default
constructor. It should return 0x100 once tt(istream)'s end-of-file has been
reached. 
    itb(size_t lineNr() const) 
        should return the (1-based) number of the tt(istream) object passed to
the tt(Input) object. At construction time the tt(istream) has just been
opened and so at that point tt(lineNr) should return 1.
    itb(void reRead(size_t ch))
        if provided with a value smaller than 0x100 tt(ch) should be pushed
back onto the tt(istream), where it becomes the character next to be
returned. Physically the character doesn't have to be pushed back. The default
implementation uses a tt(deque) onto which the character is pushed-front. Only
when this tt(deque) is exhausted characters are retrieved from the tt(Input)
object's tt(istream).
    itb(void reRead(std::string const &str, size_t fmIdx))
        the characters in tt(str) from tt(fmIdx) until the string's final
character are pushed back onto the tt(istream) object so that the string's
first character is retrieved first and the string's last character is
retrieved last. 
    itb(void close()) 
        the tt(istream) object initially passed to the tt(Input) object is
deleted by tt(close), thereby not only freeing the stream's memory, but also
closing the stream if the stream in fact was an tt(ifstream). Note that the
tt(Input)'s destructor should em(not) destroy the tt(Input)'s tt(istream)
object.
    )
    
