FBB::Mstream(3bobcat)                                             Message handler                                            FBB::Mstream(3bobcat)

NAME

       FBB::Mstream - Generic message handling stream

SYNOPSIS

       #include <bobcat/mstream>
       Linking option: -lbobcat

DESCRIPTION

       Objects  of  this class may be used to handle messages in a standardized way. Messages may be prefixed with order numbers and labels and/or
       line numbers. Messages generated by Mstream objects may optionally end in an exception, allowing  simple  implementation  of,  e.g.,  fatal
       error messages.

       Four  message  streams  are provided by the BOBCAT library and may be used after including the mstream header file. They are all defined in
       the FBB namespace:

       o      FBB::emsg for generating standard (labeled and numbered) error messages, e.g.

              [Error 1] this is an error message

       o      FBB::fmsg for generating (labeled) fatal error messages, ending in an exception, e.g.,

              [Fatal] this fatal message is followed by an exception

       o      FBB::imsg for generating plain informational messages, e.g.,

              this is a plain message

       o      FBB::wmsg for generating (labeled) warning messages;

              [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.

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

       Messages  inserted  into  Mstream  objects  are  considered completed at the insertion of the FBB::endl or 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.

NAMESPACE

       FBB
       All elements mentioned in this man-page, are defined in the namespace FBB.

INHERITS FROM

       std::ostream

CONSTRUCTORS

       o      Mstream():
              The  default  constructor generates messages using the std::streambuf used by std::cout. There is no limit to the number of messages
              that may be inserted. No message or line numbers are shown, no exception are thrown when inserting messages.

       o      explicit Mstream(std::ostream &ostr, size_t maxCount = UINT_MAX, std::string const &tag = "", bool throwing = false):
              This constructor uses the std::streambuf that is also used by the 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 exception are thrown when
              inserting messages. Specifying any other value than UINT_MAX will set the maximum number of messages that can be  inserted  to  that
              value.  The  tag  defines the text of the message label (e.g., Error). When throwing is specified as true an FBB::Errno exception is
              thrown after completing a message. The generated exception holds the id (see below for the member id) of  the  Mstream  object  from
              which the exception was thrown as well as the text FBB::Mstream.

       o      explicit Mstream(std::streambuf &buf, size_t maxCount = UINT_MAX, std::string const &tag = "", bool throwing = false):
              This constructor uses buf to insert messages into. The remaining parameters are identical to those of the previous constructor.

       o      explicit Mstream(std::string const &name, size_t maxCount = UINT_MAX, std::string const &tag = "", bool throwing = false):
              This constructor creates a std::ofstream from the provided name parameter. It throws an FBB::Errno 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.   As Mstream inherits from std::ostream the copy constructor is not available. Neither is the move con-
              structor.

MEMBER FUNCTIONS

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

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

       o      int id() const:
              returns the unique id of the Mstream object.

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

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

       o      size_t maxCount() const:
              returns the maximum number of messages that can be inserted. If the returned value equals UINT_MAX then there is  no  limit  to  the
              number of messages that can be inserted.

       o      void noLineNr():
              calling this member will suppress the display of a line number if it is called after calling setLineNr (see below) but before a mes-
              sage is being (or has been) inserted.

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

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

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

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

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

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

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

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

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

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

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

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

       o      void setLineNr(size_t lineNr):
              specifies the value lineNr as the message's line number when the next line is displayed (see  also  noLineNr).  This  value  is  not
              changed  by the 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).

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

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

       o      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., speci-
              fying the tag `Error' will prefix messages with [Error].

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

       o      bool throws():
              returns true when the Mstream object will throw an FBB::Errno exception at the next completed message. The generated exception holds
              the id (see earlier for the member id) of the Mstream object from which the exception was thrown as well as the text FBB::Mstream.

       o      void throwing(bool ifTrue):
              modifies the behaviro of Mstream objects at completed messages. After passing true Mstream objects will throw an  FBB::Errno  excep-
              tion  at  the  next completed message, otherwise this exception is not thrown. The generated exception holds the id (see earlier for
              the member id) of the Mstream object from which the exception was thrown as well as the text FBB::Mstream.

MANIPULATORS

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

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

       o      std::ostream &flush(std::ostream &out):
              This  manipulator completes the message that is currently being inserted into an Mstream object. It flushes the object's destination
              stream and prepares the object for the next message.  When the object's throws member returns true  it  will  throw  an  FBB:::Errno
              exception  which  holds  the id (see earlier for the member id) of the Mstream object from which the exception was thrown as well as
              the text FBB::Mstream.  When used in combination with another kind of std::ostream object it acts like std::flush.

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

EXAMPLE

       #include <iostream>
       #include <algorithm>
       #include <iterator>

       #include <bobcat/mstream>
       #include <bobcat/errno>

       using namespace std;
       using namespace FBB;

       int main(int argc, char **argv)
       try
       {
           imsg << "Informational: " << endl;
           imsg.off();
           cout << "The i-msg stream is now off. This message should appear once" <<
                                                                               endl;
           imsg << "The i-msg stream is now off. This message should appear once" <<
                                                                               endl;
           imsg << "The i-msg stream is now off. This message should appear once" <<
                                                                               endl;
           cout << "But this message is shown" << endl;

           wmsg << "Warning message" << endl;
           emsg << "Oops, this this is an error (not really)" << endl;
           emsg << "Oops, this goes wrong, too" << endl;

           imsg.on();
           imsg << "And another informational msg: " << emsg.count() <<
                   " error messages
" << flush;

           emsg << "Third error" << endl;
           emsg.setMaxCount(3);

           imsg << "Msg in between" << endl;

           cerr << "(cerr) LineExcess: " << emsg.lineExcess() << ", count = " <<
                   emsg.count() << endl;

           emsg << "Fourth error" << endl;

           cerr << "(cerr) LineExcess: " << emsg.lineExcess() << ", count = " <<
                   emsg.count() << endl;

           cerr << "Beyond
";
       }
       catch(FBB::Errno const &e)
       {
           std::cerr << "Got an Errno object: " << e.why() << '
';
       }
       catch(...)
       {
           std::cerr << "Got an exception
";
       }

FILES

       bobcat/mstream - defines the class interface

SEE ALSO

       bobcat(7), errno(3bobcat), mbuf(3bobcat)

BUGS

       None Reported.

DISTRIBUTION FILES

       o      bobcat_3.01.00-x.dsc: detached signature;

       o      bobcat_3.01.00-x.tar.gz: source archive;

       o      bobcat_3.01.00-x_i386.changes: change log;

       o      libbobcat1_3.01.00-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_3.01.00-x_*.deb: debian package holding the libraries, headers and manual pages;

       o      http://sourceforge.net/projects/bobcat: public archive location;

BOBCAT

       Bobcat is an acronym of `Brokken's Own Base Classes And Templates'.

COPYRIGHT

       This is free software, distributed under the terms of the GNU General Public License (GPL).

AUTHOR

       Frank B. Brokken (f.b.brokken@rug.nl).

libbobcat1-dev_3.01.00-x.tar.gz                                      2005-2012                                               FBB::Mstream(3bobcat)