libcwd: The C++ Debugging Support Library - Reference Manual
Author: Carlo Wood
Description: C++ debugging support library with ostream debug output
Keywords: libcwd, debug output, debug facility, debug channel, object orientation, OO, C++, nested debug output, ostream, memory allocation, debugging, source file and line number

Main Page Reference Manual Namespace List Compound List Namespace Members Compound Members File Members

# Format Of The Debug Output
[Writing Debug Output]

Collaboration diagram for Format Of The Debug Output:

## Classes
class | libcwd::debug_string_ct
| A string class used for the debug output margin and marker.This type is used for the public attributes debug_ct::margin and debug_ct::marker of the debug object class. More...
## Functions
debug_string_ct & | libcwd::debug_ct::margin (void)
| The margin.
debug_string_ct & | libcwd::debug_ct::marker (void)
| The marker.
void | libcwd::debug_ct::push_margin (void)
| Push the current margin on a stack.
void | libcwd::debug_ct::pop_margin (void)
| Pop margin from the stack.
void | libcwd::debug_ct::push_marker (void)
| Push the current marker on a stack.
void | libcwd::debug_ct::pop_marker (void)
| Pop marker from the stack.
void | libcwd::debug_ct::set_indent (unsigned short indentation)
| Set number of spaces to indent.
void | libcwd::debug_ct::inc_indent (unsigned short indentation)
| Increment number of spaces to indent.
void | libcwd::debug_ct::dec_indent (unsigned short indentation)
| Decrement number of spaces to indent.
unsigned short | libcwd::debug_ct::get_indent (void) const
| Get the current indentation.

## Detailed Description

All debug output is written in the following format:

<margin> <label> <marker> <indentation> <data> <suffix>

The <margin> field can for instance be used to print the ID of the process or thread (useful when writing debug messages from more than one process or thread to the same ostream device).

The <marker> field can be used to identify regions (for example with a vertical line) depending on the current context.

The <indentation> field consists of spaces and is intended to make debug output better readable by grouping lines of debug output as an easier alternative than using the marker field for that purpose.

The <label> field exists of the channel label (as passed to the constructor of a channel_ct ) padded by spaces to make this field constant in width (it is padded to the length of the longest existing channel label), followed by the marker, which is by default a colon plus a final space; for example "NOTICE&nbsp;:&nbsp;".

The <data> field represents the second field of the Dout macro, written to the debug ostream with the operator<< inserters.

Finally, the <suffix> field is by default a new-line, optionally followed by a flush. The debug control flag error_cf however, causes an error message to be inserted first. The suffix field could become for example ":&nbsp;EAGAIN&nbsp;(Try&nbsp;again)\\n".

See also:
  Control Flags

Example:

    Debug( libcw_do.margin().assign("*** ", 4) );
    Debug( libcw_do.marker().assign(": | ", 4) );
    Dout(dc::notice, "This line is not indented");
    Debug( libcw_do.set_indent(4) );
    Dout(dc::notice, "This line is indented 4 spaces");
    Debug( libcw_do.inc_indent(2) );
    Dout(dc::notice, "This line is indented 6 spaces");

Outputs

     NOTICE  : | This line is not indented
     NOTICE  : |     This line is indented 4 spaces
     NOTICE  : |       This line is indented 6 spaces

## Function Documentation

debug_string_ct & libcwd::debug_ct::margin | ( | void |  | ) | `[inline, inherited]`

The margin.

This is printed before the label. The margin can be manipulated directly using the methods of class debug_string_ct.

See also:
  push_margin()
  pop_margin()

Referenced by libcwd::debug_ct::pop_margin(), and libcwd::debug_ct::push_margin().

debug_string_ct & libcwd::debug_ct::marker | ( | void |  | ) | `[inline, inherited]`

The marker.

This is printed after the label. The marker can be manipulated directly using the methods of class debug_string_ct.

See also:
  push_marker()
  pop_marker()

Referenced by libcwd::debug_ct::pop_marker(), and libcwd::debug_ct::push_marker().