man FBB::Msg (3): Generic message handler

SYNOPSIS

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

DESCRIPTION

NAMESPACE

FBB
All constructors, members, operators and manipulators, mentioned in this man-page, are defined in the namespace FBB.

INHERITS FROM

CONSTRUCTORS

The class Msg only has static members. There are no constructors.

MEMBER FUNCTIONS

The class Msg only has static members. The member functions listed below are not frequently used. They exist primarily to control the output streams and to fine-tune the inner workings of the class' data members. Instead, the class-less members msg() and lineMsg() (see below) and the manipulators (see below) are used to create messages.

static size_t count():
Returns the number of error messages generated so far.
static bool display():
Returns true if the currently accumulated message will be inserted into the message stream. This is the default case.
static size_t errors():
Returns the number of error messages generated so far. Synonym of count().
static std::streambuf *infoToWarning():
Following this call all `info'-messages will be written to the same stream as warning messages. The function returns the streambuf used so far.
static void open(std::ifstream &in, std::string const &name):
Convenience function opening the object ifstream in refers to. If opening the stream fails, a fatal error message is generated.
static void open(std::ofstream &out, std::string const &name):
Convenience function opening (creating) the object ofstream out refers to. If opening the stream fails, a fatal error message is generated.
static void open(std::ofstream &out, std::string const &name, size_t protection):
Convenience function opening (creating) the object ofstream out refers to. The protection value is normally specified as an octal value. From the chmod(1) manpage:
The mode is from one to four octal digits (0-7), derived by adding up the bits with values 4, 2, and 1. Omitted digits are assumed to be leading zeros. The first digit selects the set user ID (4) and set group ID (2) and restricted deletion or sticky (1) attributes. The second digit selects permissions for the user who owns the file: read (4), write (2), and execute (1); the third selects permissions for other users in the file's group, with the same values; and the fourth for other users not in the file's group, with the same values.
If opening the stream fails, a fatal error message is generated.
static bool setDisplay(bool mode):
Changes the setting of the `display' variable. At true (Note that the default is false) accumulated messages will be inserted into the message stream.
static std::streambuf *setInfoBuf(std::streambuf *newBuffer, bool display = true):
Define a new streambuf into which info-messages will be inserted. The passed streambuf must remain in existence after the call. If newBuffer is 0, the currently used streambuf is not altered. The function returns the streambuf used so far.
static void setLine(size_t linenr):
Set the value of the line-counter used with the lineMsg manipulator (see below).
static void setMaxCount(size_t maxCount):
Define the maximum number of error messages (using the err manipulator, see below), before a fatal maximum number of error messsages reached message is generated. The default value is the maximum size_t value; not reached in any practical situation.
static void setOstream(std::string const &name):
Define the name of the stream to which messages will be written.
static void setWarning(char const *pre = "[Warning] "):
Define the text printed ahead of warning messages. The default value is equal to this member function's default argument value.
static size_t warnings():
Returns the number of warning messages generated so far.

FREE FUNCTIONS

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

std::ostringstream &linMsg():
Information inserted into this function is used to compose a message. Messages must be completed, using an appropriate manipulator, before another message can be constructed. The final message is prefixed by the text `Line <nr>: ', where <nr> is the value last set by the member function setLine(). Note the blank trailing the colon.
std::ostringstream &msg():
Information inserted into this function is used to compose a message. Messages must be completed, using an appropriate manipulator, before another message can be constructed.
std::ostringstream &msgstream():
Contrary to the function msg, which will first clear the current contents of the message buffer, msgstream returns the current stream `as is'. This allows the use of certain Template Library algorithms, like copy. E.g., assuming that std::vector<std::string> d_words has been defined, and using directives were specificied for the std and FBB namespaces, then
```
    copy(d_words.begin(), d_words.end(), ostream_iterator<string>(msg, " "));
    msgstream() << info;
        
```
can be used to insert the contents of d_words, separated by a blank space, into the Msg stream.

MANIPULATORS

The following manipulators (which are not part of the FBB::Msg, class, but are defined in the FBB namespace) can be inserted into the FBB::Msg object. All messages are by default inserted into the standard output stream (cout).

FBB::err:
An error message is generated. Error messages are prefixed by the text `[Error <count>] ', where <count> counts the number of error messages generated so far. If the maximum error count is exceeded (see setMaxCount() above) a fatal message is generated as well. A newline is added to the message by the manipulator.
FBB::fatal:
A fatal message is generated. Fatal messages are prefixed by the text `[Fatal] '. Following a fatal message an Errno(1) exception is thrown. A newline is added to the message by the manipulator.
FBB::info:
This manipulator generates an informational message. Information messages may be controlled by the setDisplay() member (see above), and have no further characteristics. A newline is added to the message by the manipulator.
FBB::spool:
This manipulator generates a (partial) informational message. spool does not add a newline message, but merrely flushes the stream's buffer.
FBB::warning:
This manipulator generates a warning message. Warning messages may be controlled by the setDisplay() member (see above). By default the text `[Warning] ' is prefixed to the message, but the prefixed message is configurable. A newline is added to the message by the manipulator.

OVERLOADED OPERATOR

The following insertion operator is not defined in the namespace FBB but in std. It is part of the distribution to allow the manipulators to be inserted into an ostrstream:

void operator<<(ostream &ostrstream, void (*)(ostream &)):
The second argument normally is one of the manipulators defined above.

EXAMPLE

    #include <bobcat/msg>
    using namespace FBB;
    int main(int argc)
    try
    {
        if (argc == 1)
            msg() << "Need some arguments" << fatal;
        else
        {
            Msg::setDisplay(true);
            msg() << "Thanks for providing " << argc << 
                                    " arguments " << info;
        }
    }            
    catch(...)
    {
        msg() << "Got an Errno object, but ignoring it" << err;
    }

FILES

bobcat/msg - defines the class interface

BUGS

None Reported.

DISTRIBUTION FILES

bobcat_2.08.01-x.dsc: detached signature;
bobcat_2.08.01-x.tar.gz: source archive;
bobcat_2.08.01-x_i386.changes: change log;
libbobcat1_2.08.01-x_*.deb: debian package holding the libraries;
libbobcat1-dev_2.08.01-x_*.deb: debian package holding the libraries, headers and manual pages;
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 ([email protected]).