Assuming that the scanner class is called `Scanner' the class Input is nested
within the class `ScannerBase'. The stream from which flc() retrieves
characters is completely decoupled from the pattern-matching algorithm
implemented in the tt(ScannerBase) class. the pattern-matching algorithm
retrieves the next character from a class tt(Input), nested under
tt(ScannerBase). This class will usually provide all the required
functionality, but users of flc() may optionally provide their own tt(Input)
class. 

In situations where the default tt(Input) implementation doesn't suffice
simply `roll your own', implementing the following interface and use the
tt(%option input-interface) and tt(%option input-implementation) options in
the tt(lexer) file to include, respectively, your own class tt(Input)
interface in the generated tt(Scannerbase.h) file and tt(Input) member
function implementations in the generated tt(lex.cc) file.

When implementing your own class tt(Input), the following public interface
must at least be provided:
        verb(
    class Input
    {
        public:
            Input();
                                            // dynamically allocated iStream
            Input(std::istream *iStream, size_t lineNr = 1);   
            size_t get();                   // the next character
            size_t lineNr() const;          
            size_t nPending() const;          
            void setPending(size_t nPending);          
            void reRead(size_t ch);         // push back 'ch' (if <= 0x100)
                                            // push back str from idx 'fmIdx'
            void reRead(std::string const &str, size_t fmIdx);

            void close();                 // delete dynamically allocated
    };
        )
    This interface may be augmented with additional members, but the
shown interface is used by tt(ScannerBase). Flc() places tt(Input) in
tt(ScannerBase)'s private interface and all communication with tt(Input) is
handled by tt(ScannerBase). tt(Input)'s members must perform the following
tasks:
    itemization(
    itt(Input()): the default constructor performs no special tasks, it
ensures that an tt(Input) object is in a valid state, in particular allowing
tt(close) to do its job.

    it() The copy constructor must be available. When necessary it can be
added to tt(Input)'s interface. The default implementation uses tt(Input)'s
default copy constructor so there was no need to add it explicitly to the
interface.

    itt(Input(std::istream *iStream, size_t lineNr)): information is read from
the tt(istream) that is passed to tt(Input). The tt(std::istream *iStream)
already points at an open, dynamically allocated tt(istream), and is ready for
reading. Stream switching is not performed by tt(Input), but by
tt(ScannerBase). Also the names of streams currently being read (e.g., when
using tt(//include) directives in specification files) are administered and
maintained by tt(ScannerBase). tt(Input) should treat the pointer as plain old
data (POD). The default implementation therefore can use the default copy
constructor, overloaded assignment operator and destructor: tt(iStream) is
simply assigned to one of tt(Input)'s data members, and is simply copied when
tt(Input)'s copy constructor or assignment operator is called. Likewise,
tt(lineNr) is assigned to tt(Input's) data member keeping track of the line
number count. 

    itt(size_t get()): this member must return the next character as an
tt(unsigned char). At end-of-file is must return the value (predefined by
tt(ScannerBase)) tt(AT_EOF). The default implementation is found in 
tt(lex.cc), generated by flc().

    itt(size_t lineNr() const): the line number of the currently processed
line should be returned. By convention these are numbers, so while processing
the first line tt(lineNr) should return 1.

    itt(size_t nPending() const): should return the number of pending
characters (i.e., the number of characters which were passed back to the
tt(Input) object using its tt(reRead) members which were not yet retrieved
again by its tt(get) member).

    itt(void setPending(size_t nPending)): should keep tt(nPending) characters
in the tt(Input) object's pending characters queue. The lexical scanner always
passes the value received from tt(nPending) to tt(setPending), without calling
tt(get) in between. The default implementation uses an tt(std::deque) for
storing pending characters, and is found in tt(lex.cc), generated by flc().

    itt(void reRead(size_t ch)): the character stored in tt(ch) is pushed back
into the tt(Input) object. The call should be ignored if tt(ch) exceeds the
value tt(0xff). The default implementation is found in tt(lex.cc), generated
by flc().

    itt(void reRead(std::string const &str, size_t fmIdx)): the characters in
tt(str) are pushed back into the tt(Input) object in reverse order from
tt(str)'s final character down to (and including) the character at offset
tt(fmIdx).  The default implementation is found in tt(lex.cc), generated
by flc().

    itt(void close()): this member must delete the memory to which tt(iStream)
points, em(en passant) closing the stream. It is called by
tt(ScannerBase::popStream) at end-of-file.  The default implementation is
found in tt(Scannerbase.h), generated by flc(). Note: tt(Input's) destructor
should em(not) delete the memory to which tt(iStream) points.
    )
