Inform

Files:	Inform.h, Inform.c
Derived from:	none
Global instance (if any):	msgInfo, msgWarn, msgErr, msgDebug
Used in optional component:	Part of main VMD code

Description

A streams-like utility object used to format messages for display at the console or other selectable ostream object. Messages are given to an Inform object via insertion operators («), and the messages are printed out to a provided ostream device, prefixed by a certain string. A special manipulator `sendmsg' is used to signal when a mesage should be printed.

Each Inform object has a current `message level', which is also indicated when the messages are printed out. Routines are provided to set the current level of the Inform object, so that only messages with a level smaller than or equal to the current output level are printed. Levels range from 1 (most likely to be printed) to 10 (very unlikely to be printed). The main use of this feature in VMD is in conjunction with debugging messages, where the level of debugging information can be changed via text commands.

There are four global instances of Inform which are available to the entire program (as long as they include the file Inform.h):

• msgInfo - Generally informative messages.
• msgWarn - Special warning messages, which do not signal an error but warn of some possible problem with the current state.
• msgErr - Error messages.
• msgDebug - Debugging messages. The macro MSGDEBUG() exists which should be used when printing messages to msgDebug; if the macro VMDDEBUG is set during compilation, the debugging messages will be included in the executable. An example of use:
  MSGDEBUG("This is a debug message" « sendmsg)

Constructors

• Inform::Inform(char *name, int ison=1)
  The name argument is the name of the instance of this object; when messages are printed out they are profixed with the name, the message level, and a right paren, i.e.
  Info 1) Info message.
  The `ison' argument determines if messages should be printed or not at the start. Besides the message levels, each Inform object can be on or off. When off, message are not printed, otherwise they are if the message level is set properly.

Enumerations, lists or character name arrays

Inform contains several manipulators used to determine how the message is printed or to do actions. They are:

• sendmsg - used to signal that the message is complete, and should be printed. So, this should be that last item inserted into the Inform stream.

• level1 ... level10 - sets the output level of the current message to $X$, where $X$ is the digit at the end of this name (1 ... 10).

Internal data structures

• char *name - name of the instance. Used to print message prefix.

• ostrstream *msg - character stream used to hold the message string to be printed.

• ostream *msgDest - destination stream, where the message will be printed. This could be the console (cout), or also a file.

• int On - whether the object should print out its messages.

• int needNewline - before the message is actually printed, sometimes a newline must be printed, and sometimes not. This flag tells whether to print a newline. Once a message is printed, this flag is cleared. The member function need_newline may be used to set this flag.

• int outputLevel - the current output message level of the instance. This level is compared with the level of the message currently being requested to be printed; if the level of the message is less than or equal to the current message level of the Inform object, then the message is printed, otherwise it is just ignored.

• int msgLevel - the current output level of the message that is to be printed. This may be changed anytime during the construction of the message; the level at the time when the request to print the message is made is the one used.

Nonvirtual member functions

• void on(int) - set the object to be on or off.
• int on(void) - return the current on/off status.

• output_level(int) - set the current output level.
• int output_level(void) - return current output level of the Inform object.

• msg_level(int) - set the current level of the next message to be printed.
• int msg_level(void) - return the current message output level.

• void need_newline(int) - set the current flag for whether a newline is needed or not.
• int need_newline(void) - return current newline print status.

• void destination(ostream *) - give the provided destination stream to the Inform object as a place where to print messages.
• ostream *destination(void) - return destination to where messages will be printed.

• send(void) - prints the contents of the current message buffer to the destination stream, if necessary.

• operator«(various types) - overloaded insertion operators which are used to put data into the current message buffer. These are used just like regular stream insertion operators, and when the message is complete, either the routine send should be called, or else the sendmsg manipulator should be inserted into the stream. Newline characters may be put in the stream, Inform will print out each newline-separated line with the proper prefix.

Method of use

As stated, there are four global instances of Inform which should be used for printing all messages in VMD. They are used just like a stream, except the manipulator sendmsg is used instead of endl to signal that the string should be printed. An example:

msgWarn « level3 « "This is a level-3 warning." « sendmsg;

In this case, if msgWarn is on, and it's output level is greater than or equal to 3, then this message will be printed, otherwise it will be ignored.

For debugging messages (printed to msgDebug), make sure to use the MSGDEBUG macro, so that these debugging messages can be conditionally excluded from the executable.

Suggestions for future changes/additions

Right now, only the debug Inform object takes advantage of the message level facility, all other messages (information, warning, or error) are all level-1 messages. More messages should be printed out by VMD, but at different levels of verbosity and content, and text commands should be put in to control the current output level of msgInfo, msgWarn, and msgErr.

Text commands should be added to allow the message text to be sent to a file, or to the console (right now, they are always sent to the console). This would not be very difficult, a new text command would need to be added which would open a file, and call the destination routine with the respective ostream pointer.