Inheritance diagram for smtk::spew:
Public Types | |
| enum | LEVEL { BLOCK, DEBUG, INFO, NOTICE, WARN, ERROR, OFF } |
| spew levels available More... | |
Public Member Functions | |
| spew & | add (const char *format,...) __attribute__((format(printf |
| add to the spew message | |
| const char * | bld (void) const |
| color bold | |
| void | block (void) |
| pop one off the spew stack at level BLOCK | |
| template<class T> | |
| T | block (T t) |
| pop one off the spew stack at level block | |
| const char * | blu (void) const |
| color blue | |
| bool | check_color (void) |
| check is escape colors are set | |
| void | clear (LEVEL l=BLOCK) |
| pop (clear) all off the spew stack | |
| void | debug (void) |
| pop one off the spew stack at level DEBUG | |
| template<class T> | |
| T | debug (T t) |
| pop one off the spew stack at level DEBUG | |
| const char * | end (void) const |
| color end | |
| void | error (void) |
| pop one off the spew stack at level ERROR | |
| template<class T> | |
| T | error (T t) |
| pop one off the spew stack at level ERROR | |
| void | get_env_color (FILE *file, bool over_ride_env=false) |
| parse environment variable SMTK_COLOR. | |
| FILE * | get_file (void) const |
| get the spew file | |
| spew_gui * | get_gui (void) |
| Get the GUI object. | |
| LEVEL | get_level (void) const |
| get the current spew level | |
| spew const char * | get_prefix (void) const |
| get the spew prefix string | |
| const char * | grn (void) const |
| color green | |
| void | info (void) |
| pop one off the spew stack at level INFO | |
| template<class T> | |
| T | info (T t) |
| pop one off the spew stack at level INFO | |
| void | notice (void) |
| pop one off the spew stack at level NOTICE | |
| template<class T> | |
| T | notice (T t) |
| pop one off the spew stack at level NOTICE | |
| void | pop (LEVEL level) |
| pop one off the spew stack | |
| template<class T> | |
| T | pop (LEVEL level, T t) |
| pop one off the spew stack | |
| spew spew & | push (void) |
| push one on the spew stack | |
| spew & | push (const char *func_name,...) __attribute__((format(printf |
| push one on the spew stack | |
| const char * | rblu (void) const |
| color reverse blue | |
| const char * | red (void) const |
| color red | |
| template<class T> | |
| T | ret (T t) |
| handy return value | |
| const char * | rev (void) const |
| color reverse | |
| const char * | rgrn (void) const |
| color reverse green | |
| const char * | rred (void) const |
| color reverse red | |
| const char * | rtur (void) const |
| color reverse turquoise | |
| const char * | rvil (void) const |
| color reverse violet | |
| const char * | ryel (void) const |
| color reverse yellow | |
| spew & | set_callback (void(*func)(const char *prefix, const char *message, spew::LEVEL level)) |
| add a user call-back | |
| spew & | set_color (bool on=true) |
| enable/disable the escape color strings. | |
| int | set_file (const char *filename=0) |
| set the spew file | |
| spew & | set_gtk_gui (bool truth=true) |
| set/unset for GUI feedback | |
| spew & | set_gui (spew_gui *my_gui) |
| set/unset for GUI feedback with user defined GUI | |
| spew & | set_level (LEVEL level) |
| set the spew level | |
| spew & | set_prefix (const char *format,...) __attribute__((format(printf |
| set the spew prefix string | |
| spew spew spew & | sys (void) |
| add a new spew message with system error | |
| spew spew & | sys (const char *func_name,...) __attribute__((format(printf |
| add a new spew message with system error | |
| const char * | tur (void) const |
| color turquoise | |
| const char * | und (void) const |
| color under line | |
| const char * | vil (void) const |
| color violet | |
| void | warn (void) |
| pop one off the spew stack at level WARN | |
| template<class T> | |
| T | warn (T t) |
| pop one off the spew stack at level WARN | |
| const char * | yel (void) const |
| color yellow | |
Examples: devel_spew_1.cpp, devel_spew_2.cpp, devel_spew_3.cpp.
The class spew provides a short message spewing utility for the SmTk application programming interface (API). As it's name implies the nature of the messages are usually diagnostic, or coming from within. It's more of a developer tool than a end application user tool. By default it just spews short messages to standard output. Spew may be configured to spew to pop up GUIs (graphical user interfaces), or user defined call-backs may be used to get an ASCII string. It can be used as a debugging tool with varying levels of verbosity or as spew from your application. The application may prepend a string to all the messages using set_prefix(). The intent of spew is to peek at what is happening when using the SmTk API while a program is running. By default the spew message output does not flush until the program execution reaches the API users code or an exceptional condition is generated. The end program user has many controls over spew by using environment variables. The application developer may set some default behaviors, but the end program user can over-ride them.
By default a spew class object uses a standard C library FILE stream. A program user may select a file to use by setting the environment variable SMTK_SPEW_FILE to any one of the following:
1 or stdout for using the standard output file. stdout may be in any combination of upper or lower case letters.
2 or stderr for using the standard error file. stderr may be in any combination of upper or lower case letters.
none will not output to a file.
filename for appending to the spew to any regular file that the user chooses. filename should be the filename.In addition to the above spew files the SmTk API user may set up a spew call-back which is called every time the spew flushes. Spew stack's messages from SmTk API calls and, by default, flushes anytime the thread of execution reaches the end of a users call to a SmTk API function (or method) call.
The environment variable SMTK_SPEW or SMTK_SPEW_LEVEL affects when spew will spew. If both SMTK_SPEW and SMTK_SPEW_LEVEL are both set the value of SMTK_SPEW will be ignored. The values of SMTK_SPEW and SMTK_SPEW_LEVEL will be understood in any combination of upper or lower case letters. The following values of SMTK_SPEW and SMTK_SPEW_LEVEL can control a spew object:
debug info notice warning or warn error off Environment variables will only effect spew when the object is constructed. So environment variables set in your code will only effect spew objects that are constructed after the environment variables set.
| enum smtk::spew::LEVEL |
spew levels available
This enumeration is used to define the level of spew, from very verbose (DEBUG) too no spew at all (OFF). See spew_level_env in the detailed description of how the environment variable SMTK_SPEW_LEVEL compared to these levels.
| spew & spew::add | ( | const char * | format, | |
| ... | ||||
| ) |
| const char* smtk::tty_color::bld | ( | void | ) | const [inline, inherited] |
| void smtk::spew::block | ( | void | ) | [inline] |
| T smtk::spew::block | ( | T | t | ) | [inline] |
| const char* smtk::tty_color::blu | ( | void | ) | const [inline, inherited] |
| bool smtk::tty_color::check_color | ( | void | ) | [inline, inherited] |
check is escape colors are set
| void smtk::spew::clear | ( | LEVEL | l = BLOCK |
) | [inline] |
| void smtk::spew::debug | ( | void | ) | [inline] |
| T smtk::spew::debug | ( | T | t | ) | [inline] |
| const char* smtk::tty_color::end | ( | void | ) | const [inline, inherited] |
| void smtk::spew::error | ( | void | ) | [inline] |
| T smtk::spew::error | ( | T | t | ) | [inline] |
| void tty_color::get_env_color | ( | FILE * | file, | |
| bool | over_ride_env = false | |||
| ) | [inherited] |
parse environment variable SMTK_COLOR.
See color_env for how the environment variable SMTK_COLOR effects this class.
| file | is used to check if the file is a tty terminal that will interpret the escape sequences. | |
| over_ride_env | if true the color strings will not depend on the environment variable SMTK_COLOR. |
| FILE* smtk::spew::get_file | ( | void | ) | const [inline] |
| spew_gui* smtk::spew::get_gui | ( | void | ) | [inline] |
Get the GUI object.
| LEVEL smtk::spew::get_level | ( | void | ) | const [inline] |
| spew const char* smtk::spew::get_prefix | ( | void | ) | const [inline] |
| const char* smtk::tty_color::grn | ( | void | ) | const [inline, inherited] |
| void smtk::spew::info | ( | void | ) | [inline] |
| T smtk::spew::info | ( | T | t | ) | [inline] |
| void smtk::spew::notice | ( | void | ) | [inline] |
| T smtk::spew::notice | ( | T | t | ) | [inline] |
| void smtk::spew::pop | ( | LEVEL | level | ) | [inline] |
pop one off the spew stack
See template<class T> spew::pop(LEVEL level, T t).
| T smtk::spew::pop | ( | LEVEL | level, | |
| T | t | |||
| ) | [inline] |
pop one off the spew stack
This pops one off the spew entry stack, which this class uses to determine when to flush the message and when this is used properly with accompanying push() can be used to tell what the depth of function call is in the SmTk API. This helps make a list of what called what and what spewed what in the SmTk API. When the spew stack pops the top spew message, all the current the spew messages will be flushed.
pop() is called after push(). Because pop() is called at the end of a spew message call sequence, it decides the importance level of the spew message with the level argument. See also block(), debug(), info(), notice(), warn() and error().
| level | is the selected spew level. This will be over-ridden if this is not at the bottom of the spew stack. The last message popped off the spew stack will determine the spew level. This is so that the function (or method) closest to the user decides what is the nature of the spew message. | |
| t | the returned value. This is convenient to be called in a function that returns a value. |
// example code snippet //
// returns -1
return smtk::spw.add("failed").warn(-1);
push one on the spew stack
Pushes a message entry onto the spew stack. This stack when used properly, push() with accompanying pop() (block(), debug(), info(), notice(), warn() or error()), can be used to tell what the depth of function call is in the SmTk API. This helps make a list of what called what and what spewed what in the SmTk API.
| spew & spew::push | ( | const char * | func_name, | |
| ... | ||||
| ) |
push one on the spew stack
This pushs a spew entry on a stack which this class uses to determine when to flush the message and when this is used properly with accompanying pop() can be used to tell what the depth of function call is in the SmTk API. This helps make a list of what called what and what spewed what in the SmTk API.
| func_name | the function (or method) name to use in the spew message for this call depth. func_name may be used as a printf(3) like format for the remaining arguments. |
| const char* smtk::tty_color::rblu | ( | void | ) | const [inline, inherited] |
| const char* smtk::tty_color::red | ( | void | ) | const [inline, inherited] |
| T smtk::spew::ret | ( | T | t | ) | [inline] |
handy return value
This does nothing but return the value passed. This is handy for reducing the amount of code that a user must write. For example if you need to return a value after adding to spew you can do:
// example code snippet //
if(my_function()) // error
return spw.add("my_function failed").ret(-1);
// longer example code snippet //
if(my_function()) // error
{
spw.add("my_function failed");
return -1;
}
| const char* smtk::tty_color::rev | ( | void | ) | const [inline, inherited] |
| const char* smtk::tty_color::rgrn | ( | void | ) | const [inline, inherited] |
| const char* smtk::tty_color::rred | ( | void | ) | const [inline, inherited] |
| const char* smtk::tty_color::rtur | ( | void | ) | const [inline, inherited] |
| const char* smtk::tty_color::rvil | ( | void | ) | const [inline, inherited] |
| const char* smtk::tty_color::ryel | ( | void | ) | const [inline, inherited] |
| spew& smtk::spew::set_callback | ( | void(*)(const char *prefix, const char *message, spew::LEVEL level) | func | ) | [inline] |
add a user call-back
Add a user call-back function that will be called every time spew is flushed. You may want to remove any color escape sequence strings with set_color() before calling set_callback().
| func | is called with message that will contain the composed message string. |
| spew & spew::set_color | ( | bool | on = true |
) |
enable/disable the escape color strings.
To give the API user the control, this is not called in any part of the SmTk API, other than in this class in the constructor. The setting of escape color strings is also set in the constructor from the value of the environment variable SMTK_COLOR. This will over-ride that. See color_env in the tty_color class detailed description.
| on | If on is true the escape color strings are set, and if on is false all the escape color strings are set to empty strings. |
Reimplemented from smtk::tty_color.
| int spew::set_file | ( | const char * | filename = 0 |
) |
set the spew file
Set the spew file. This only over-rides the default spew file. The spew file can be over-written by the end user by setting the SMTK_SPEW_FILE environment variable. See spew_file_env in the spew class detailed description.
| filename | may be set to "stdout", (for standard error) "stderr" (for standard error), "none" or 0 (for no file spew) or the filename of a regular file. If the file fails to be opened the spew will go back to the way it was before this call. |
| spew & spew::set_gtk_gui | ( | bool | truth = true |
) |
set/unset for GUI feedback
Screen-Shot of this GUI in use.
Set the spew to use the built in GUI (graphical user interface) to display each time there is a spew message flushed.
When setting with GUI feedback on any color escape string sequences will be removed.
| truth | if truth is true this will set up spew for GUI feedback using a GTK dialog window, and if truth is false this will not use a GUI. |
set/unset for GUI feedback with user defined GUI
Set the spew to use the GUI (graphical user interface) that the user makes. The spew object will not try to do something stupid like deleting the object that was passed in. See the example in gtk_spew_gui.cpp and gtk_spew_gui.h.
| my_gui | is a pointer to a spew_gui that the user provided. my_gui may be 0 (NULL) to unset the GUI and make it not display. |
set the spew level
Set the spew level. The spew level can be over-written by the end user by setting the SMTK_SPEW_LEVEL environment variable. See spew_level_env in the spew class detailed description.
| level | the level to set to. |
| spew & spew::set_prefix | ( | const char * | format, | |
| ... | ||||
| ) |
| spew & spew::sys | ( | void | ) |
| spew & spew::sys | ( | const char * | func_name, | |
| ... | ||||
| ) |
add a new spew message with system error
Adds to the spew message using strerror(3) to get the system error string from the current system error number errno(3).
| func_name | is a printf(3) like format. The string composed is intended to be the name of the system function that produced the system error. This system function name will be used to prefix the system error string. |
| const char* smtk::tty_color::tur | ( | void | ) | const [inline, inherited] |
| const char* smtk::tty_color::und | ( | void | ) | const [inline, inherited] |
| const char* smtk::tty_color::vil | ( | void | ) | const [inline, inherited] |
| void smtk::spew::warn | ( | void | ) | [inline] |
| T smtk::spew::warn | ( | T | t | ) | [inline] |
| const char* smtk::tty_color::yel | ( | void | ) | const [inline, inherited] |
1.5.2