includefile(include/header)

COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::Mstream)(3bobcat)(_CurYrs_)(libbobcat-dev__CurVers_)
                    (Message handler)

manpagename(FBB::Mstream)(Generic message handling stream)

manpagesynopsis()
    bf(#include <bobcat/mstream>)nl()
    Linking option: tt(-lbobcat)

manpagedescription()
    Objects of this class are used for handling messages in a standardized
way. Messages may be prefixed with order (line) numbers an/or,
labels. Messages generated by tt(Mstream) objects may optionally end by
throwing an tt(FBB::Exception) (which is an tt(std::exception)), allowing
simple implementation of, e.g., fatal error messages.

    Four message streams are provided by the tt(BOBCAT) library and may be
used after including the tt(mstream) header file. They are all defined in the
tt(FBB) namespace:
    itemization(
    itt(FBB::emsg) for generating standard (labeled and numbered) error
        messages, e.g.
        verb(
[Error 1] this is an error message
        )
    itt(FBB::fmsg) for generating (labeled) fatal error messages, ending in an
        exception, e.g.,
        verb(
[Fatal] this fatal message is followed by an exception
        )
        The exception's tt(what) member contains tt(FBB::fmsg's id) value (see
        member tt(id) below).
    itt(FBB::imsg) for generating plain informational messages, e.g.,
        verb(
this is a plain message
        )
    itt(FBB::wmsg) for generating (labeled) warning messages;
        verb(
[Warning] this is a warning
        )
    )
    By default all messages are inserted into the standard output stream, but
other destinations (standard error, a named file, etc.) can easily be
configured.

    tt(Mstream) objects themselves are tt(std::ostream) objects, so they
can be used as objects passed to functions expecting tt(ostream)
arguments. Messages inserted into tt(Mstream) objects are buffered until
the buffer is flushed by their tt(std::ostream) parts or when either the
tt(FBB::endl) or tt(FBB::flush) is inserted into the message stream. Since
these manipulators act like tt(std::endl) and tt(std::flush) when inserted
into another kind of tt(std::ostream) object, tt(using FBB::endl) and tt(using
FBB::flush) might be worth considering. Also, when tt(using namespace std)
em(and) tt(using namespace FBB) is specified the tt(FBB::endl) and
tt(FBB::flush) manipulator will automatically be used with tt(Mstream)
objects.

    Messages inserted into tt(Mstream) objects are considered completed
at the insertion of the tt(FBB::endl) or tt(FBB::flush) manipulators. Message
labels, line number labels and line numbers will only be shown for the next
line after these manipulators have been inserted and exceptions are, if
needed, thrown from these manipulators.

manpagesection(NAMESPACE)
    bf(FBB)nl()
    All elements mentioned in this man-page, are defined in the namespace
bf(FBB).

manpagesection(INHERITS FROM)
    bf(std::ostream)

manpagesection(CONSTRUCTORS)
    itemization(
    itb(Mstream())
        The default constructor generates messages using the
tt(std::streambuf) used by tt(std::cout). There is no limit to the number of
messages that may be inserted. No message or line numbers are shown, no
exceptions are thrown when inserting messages.
    itb(explicit Mstream(std::ostream &ostr, size_t maxCount =
        std::numeric_limits<size_t>::max(), std::string const &tag = "", bool
        throwing = false))
       This constructor uses the tt(std::streambuf) that is also used by the
        tt(ostream ostr). By default (using the default argument values) there
        is no limit to the number of messages that may be inserted. No message
        or line numbers are shown, no exceptions are thrown when inserting
        messages. Specifying any other value than
        tt(std::numeric_limits<size_t>::max()) will set the maximum number of
        messages that can be inserted to that value. The tt(tag) defines the
        text of the message label (e.g., tt(Error)).

        When tt(throwing) is tt(true) an exception is thrown after completing
        a message. The generated exception's tt(what) member may show the
        bf(FBB::Mstream) object's id (see below at the member tt(id)) of the
        tt(Mstream) object throwing the exception.
    itb(explicit Mstream(std::streambuf *buf, size_t maxCount =
        std::numeric_limits<size_t>::max(), std::string const &tag = "", bool
        throwing = false))
       This constructor uses tt(buf) to insert messages into. The remaining
        parameters are identical to those of the previous constructor.
    itb(explicit Mstream(std::string const &name, size_t maxCount =
        std::numeric_limits<size_t>::max(), std::string const &tag = "", bool
        throwing = false))
       This constructor creates a tt(std::ofstream) from the provided tt(name)
        parameter. It throws an exception if the stream cannot be opened for
        writing. If a file by that name already exists it is rewritten.  The
        remaining parameters are identical to those of the previous two
        constructors.
    )

    Copy and move constructors (and assignment operators) are not available.


manpagesection(MEMBER FUNCTIONS)

    itemization(
    itb(size_t count() const)
        returns the number of inserted messages (if tt(setCount) has been
called: the value set by the last tt(setCount) call plus the number of
inserted messages since that call).

    itb(bool  isActive() const)
        returns tt(true) if messages can  actually be inserted into the
bf(FBB::MStream) object, and tt(false) if inserted messages are ignored. When
ignoring messages the message count is not updated.

    itb(int id() const)
        returns the unique em(id) of the tt(Mstream) object.

    itb(bool lineExcess() const)
        returns bf(true) after attempting to insert an additional message
        after tt(maxCount) number of messages have been inserted.

    itb(std::string const &lineTag() const)
        returns the currently used line-tag (by default `tt(Line)').

    itb(size_t maxCount() const)
        returns the maximum number of messages that can be inserted. If the
returned value equals tt(std::numeric_limits<size_t>::max()) then there is no
limit to the number of messages that can be inserted.

    itb(void noLineNr())
        calling this member will suppress the display of a line number if it
is called after calling tt(setLineNr) (see below) but before a message is
being (or has been) inserted.

    itb(void off())
        after calling tt(off) messages inserted into the tt(Mstream)
object are silently ignored. After calling tt(off) the internal message
counter is not incremented when messages are inserted.

    itb(void on())
        by default and after calling tt(on) messages inserted into the
tt(Mstream) object are sent to their destination stream.

    itb(void reset(std::ostream &ostr))
        messages inserted into the tt(Mstream) object are handled by the
tt(std::streambuf) also used by tt(ostr). Other parameters (e.g.,
tt(maxCount), the message label) are kept as-is.

    itb(void reset(std::streambuf *buf))
        messages inserted into the tt(Mstream) object are handled by
tt(std::streambuf buf). Other parameters (e.g., tt(maxCount), the message
label) are kept as-is.

    itb(void reset(FBB::Mstream const &mstream))
        the current object is reset using the parameters of the tt(mstream)
parameter.

    itb(void reset(std::string const &name, size_t maxCount,
                std::string const &tag, bool throwing))
        messages inserted into tt(Mstream) objects are handled by a
tt(std::ofstream) created using the provided tt(name) parameter.  An exception
is thrown if the stream cannot be opened for writing. If a file by that name
already exists it is rewritten. Other parameters (e.g., tt(maxCount), the
message label) are kept as-is.

    itb(void reset(std::ostream &ostr, size_t maxCount,
                std::string const &tag, bool throwing))
        messages inserted into tt(Mstream) objects are handled by the
tt(std::streambuf) also used by tt(ostr).  By specifying
        tt(std::numeric_limits<size_t>::max()) for tt(maxCount) there is no
limit to the number of messages that may be handled by this
tt(std::streambuf). The tt(tag) defines the text of the message label (e.g.,
tt(Error) or the empty string for no message label). When tt(throwing) is
specified as tt(true) an exception is thrown after completing a message.

    itb(void reset(std::streambuf *buf, size_t maxCount,
                std::string const &tag, bool throwing))
        messages inserted into tt(Mstream) objects are handled by
tt(std::streambuf buf). The remaining parameters are identical to those of the
previous tt(reset) member.

    itb(void reset(std::string const &name, size_t maxCount,
                std::string const &tag, bool throwing))
        messages inserted into tt(Mstream) objects are handled by a
tt(std::ofstream) created using the provided tt(name) parameter. It throws an
exception if the stream cannot be opened for writing. If a file by that name
already exists it is rewritten.  The remaining parameters are identical to
those of the previous two tt(reset) members.

    itb(void reset(FBB::Mstream const &mstream))
        the current object is reset using the parameters of the tt(mstream)
parameter. Following the reset all of the current object's parameters can
independently be modified from those used by tt(mstream).

    itb(bool setActive(bool ifTrue))
        If tt(ifTrue) equals tt(true) the tt(Mstream) is activated
otherwise its actions are suppressed. Returns tt(ifTrue).

    itb(void setCount(size_t count))
        assigns the value tt(count) to the object's message counter.

    itb(void setLineNr(size_t lineNr))
        specifies the value tt(lineNr) as the message's line number when the
next line is displayed (see also tt(noLineNr)). This value is em(not)
changed by the tt(Mstream) object. To display another line number the
member will have to be called again (i.e., the line number is not displayed
automatically again at every new line).

    itb(void setLineTag(std::string const &tag))
        specifies the tag prefixing line numbers. By default the line tag
equals `tt(Line)'.

    itb(void setMaxCount(size_t maxCount))
        defines tt(maxCount) as the maximum number of messages that can be
inserted into the tt(Mstream) object.

    itb(void setTag(std::string const &tag))
        specifies the tag prefixing messages. By default the tag is empty. If
not empty the tag is enclosed by square brackets. E.g., specifying the tag
`tt(Error)' will prefix messages with tt([Error]).

    itb(std::string const &tag() const)
        returns the currently used message tag (by default an empty string).

    itb(bool throws())
        returns tt(true) when the tt(Mstream) object will throw an exception
at the next completed message. The generated exception's tt(what) member
contains the id (see earlier for the member tt(id)) of the tt(Mstream) object
throwing the exception.

    itb(void throwing(bool ifTrue))
        modifies the behaviro of tt(Mstream) objects at completed
messages. After passing tt(true) tt(Mstream) objects will throw an exception
at the next completed message, otherwise this exception is not thrown. The
generated exception's tt(what) member contains the id (see earlier for the
member tt(id)) of the tt(Mstream) object throwing the exception.
    )

manpagesection(MANIPULATORS)
    Note that the following two manipulators are not members of the class
bf(Mstream), but are free functions defined in the namespace bf(FBB).

    itemization(
    itb(std::ostream &endl(std::ostream &out))
        This manipulator inserts a newline character in the tt(Mstream)'s
stream and then calls tt(FBB::flush). This manipulator acts like tt(std::endl)
and tt(std::flush) when inserted into another kind of tt(std::ostream) object.

    itb(std::ostream &flush(std::ostream &out))
    This manipulator completes the message that is currently being inserted
into an tt(Mstream) object. It flushes the object's destination stream and
prepares the object for the next message.  When the object's tt(throws) member
returns tt(true) it throws an exception whose tt(what) member contains the
id (see earlier for the member tt(id)) of the tt(Mstream) object throwing the
exception. When used in combination with another kind of tt(std::ostream)
object it acts like tt(std::flush).

    itb(std::ostream &noid(std::ostream &out))
    This manipulator completes the message that is currently being inserted
into an tt(Mstream) object. It flushes the object's destination stream and
prepares the object for the next message.  When the object's tt(throws) member
returns tt(true) it throws an exception whose tt(what) member does not
contain the bf(Mstream) object's ID. When used in combination with another
kind of tt(std::ostream) object it acts like tt(std::flush).

    itb(std::ostream &noidl(std::ostream &out))
        This manipulator inserts a newline character in the tt(Mstream)'s
stream and then calls tt(FBB::noid). This manipulator acts like tt(std::endl)
and tt(std::flush) when inserted into another kind of tt(std::ostream) object.
    )

As the manipulators tt(FBB::endl) and tt(FBB::flush) act like, respectively,
tt(std::endl) and tt(std::flush) when inserted into another kind of
tt(std::ostream) object, using the declarations `tt(using FBB::endl)' and
`tt(using FBB::flush)' might be worth considering. Also, when tt(using
namespace std) em(and) tt(using namespace FBB) is specified the tt(FBB::endl)
and tt(FBB::flush) manipulator will automatically be called when inserting
tt(endl) or tt(flush) into tt(Mstream) objects.

manpagesection(EXAMPLE)
    verbinclude(../../mstream/driver/driver.cc)

manpagefiles()
    em(bobcat/mstream) - defines the class interface

manpageseealso()
    bf(bobcat)(7), bf(exception)(3bobcat), bf(mbuf)(3bobcat)

manpagebugs()
    None Reported.

includefile(include/trailer)