Some scanners (such as those which support `include' files) require reading
from several input streams. Usually, a directive like tt(#include) is defined
controlling stack-wise stream switching. Alternatively, direct switches to
other streams can be requested.  Flc() offers both ways to switch streams.

    itemization(
    it() For stack-wise stream switching, a directive like tt(#include) is
usually defined. When encountered, processing of the current stream is
suspended and the scanning process continues at the stream whose name is
specified at the tt(#include) directive. When reaching a stream's end-of-file
the scanner switches back to the suspended input stream. In this case streams
are pushed on a stack when encountering a stream switching directive and
popped off the stack once the current file has completely been processed.
    it() Second, the user may request the scanner to switch to another stream.
Optionally, the user may request to switch back. In this case, the user is
completely responsible for all stream-related bookkeeping. The scanner merely
provides a means to switch from one stream to another.  
    )

    The members tt(void pushStream(std::istream &curStream)) and tt(void
pushStream(std::string const &curName)) are provided for stack-wise stream
switching. By default, at a stream's end-of-file the member tt(bool
popStream()) is automatically called by flc(), closing the currently processed
input stream and continuing the processing of 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. If the stream to switch to does not
exist a tt(std::exception) is thrown. An exception is also thrown when files
are recursively pushed. 

    Returning to the previously stacked stream is handled automatically and
does not require the use of an tt(<<EOF>>) rule. If an tt(<<EOF>>) rule is
defined, however, previously pushed streams are em(not) automatically
re-activated. In that case, returning to previously pushed streams is the
responsibility of the programmer. After completely processing the first input
file the member tt(lex) returns 0.

    When switching to another stream the line number counter and file name are
reset to, respectively, 1 and the new file's name. When returning to a
previously suspended (stacked) stream that stream's line number and file name
are restored. 

    Direct, non-stack based stream switching is handled by various public
support member functions of the Scanner class (actually, the functions are
implemented as members of the ScannerBase base class):
    itemization(
includefile(../../man/streamswitching.yo)
    )
    When switching streams using the above input-stream switching members
processing of the current input file ends, and continues at the file or stream
specified when calling these members.





