Carp::Datum::Cfg - Dynamic Debug Configuration Setting for Datum

 # In application's main
 use Carp::Datum qw(:all on);      # turns Datum "on" or "off"
 DLOAD_CONFIG(-file => "./debug.cf", -config => "config string");

By using the DLOAD_CONFIG function in an application's main file, a debugging configuration can be dynamically loaded to define a particular level of debug/trace flags for a specific sub-part of code.

For instance, the tracing can be turned off when entering a routine of a designated package. That is very useful for concentrating the debugging onto the area that is presently developed and/or to filter some verbose parts of code (recursive function call), when they don't need to be monitored to fix the problem.

Before the obscure explaination of the grammar, here is an example of what can be specified by dynamic configuration:

  /* 
   * flags definition: macro that can be used in further configuration
   * settings
   */
  flags common {
      all(yes);
      trace(yes): all;
  }

  flags silent {
      all(yes);
      flow(n);
      trace(n);
      return(n);
  }

  /*
   * default setting to use when there is no specific setting 
   * for the area
   */
  default common;

  /*
   * specific settings for specific areas
   */
  routine "context", "cleanup"                 { use silent; }
  routine "validate", "is_num", "is_greater"   { use silent; }

  file "Keyed_Tree.pm"                         { use silent; }
  file "Color.pm" {
      use silent; 
      trace(yes): emergency, alert, critical;
  }

  cluster "CGI::MxScreen" {
      use silent; 
      assert(n);
      ensure(n);
  }

  /*
   * aliasing to reduce the trace output line length
   */

  alias "/home/dehaudtc/usr/perl/lib/site_perl/5.6.0/CGI" => "<PM>";

The only user interface is the CWDLOAD_CONFIG routine, which expects the following optional named parameters: Give an inlined configuration string that is appended to the one defined by CW-file, if any. Specifies the configuration file to load to initialize the debugging and tracing flags to be used for this run.

The following main directives can appear at a nesting level of 0. The syntax unit known as BLOCK is a list of semi-colon terminated directives held within curly braces. Defines an alias to be used during tracing. The large_path string is replaced by the short_path in the logs. For instance, given:

  alias "/home/dehaudtc/lib/CGI" => "<CGI>";

    cluster "CGI::MxScreen", "Net::MsgLink" { use silent; }

    cluster "CGI::MxScreen"         { use verbose; }
    cluster "CGI::MxScreen::Screen" { use silent; }

    default silent;

    file "foo.pm", "bar.pm" { use silent; }

    file "foo.pm"      { use verbose; }
    file "/tmp/foo.pm" { use silent; }

    flags common {
        all(yes);
        trace(yes): all;
    }

    flags other {
        use common;         # reuses definiton of common flags
        panic(n);          # but switches off panic, enabled in common
    }

    routine "foo", "bar" { use silent; }

Debugging (and tracing) flags can be specified only within syntactic BLOCK items, as expected by main directives such as CWflags or CWfile. Following is a list of debugging flags that can be specified in the configuration. The order in which they are given in the file is significant: the yes/no settings are applied sequentially. Uses flags defined by a CWflags directive under name. It acts as a recursive macro expansion (since CWuse can also be specified in CWflags). The symbol name must have been defined earlier.

flow(yes|no)

Whether to print out the entering/exiting of routines. That implies the invocation of the CWDFEATURE function in the routines.

return(yes|no)

Whether to print out the returned when using the return CWDVAL and CWDARY routines.

trace(yes|no)

Whether to print out traces specified by the CWDTRACE function. By default all trace levels are affected. It may be followed by a list of trace levels affected by the directive, as in.

    trace(yes): emergency, alert, critical;

Trace levels are purely conventional, and have a strict one-to-one mapping with CWDTM_TRC_ levels given at the CWDTRACE call. They are further described in Trace Levels below. There is one bit per defined trace level, contrary to the convention established by syslog(), for better tuning.

require(yes|no)

Whether to evaluate the pre-condition given by CWDREQUIRE. But see Assertion Evaluation Note below.

assert(yes|no)

Whether to evaluate the assertion given by CWDASSERT. But see Assertion Evaluation Note below.

ensure(yes|no)

Whether to evaluate the post-condition given by CWDENSURE. But see Assertion Evaluation Note below.

panic(yes|no)

Whether to panic upon an assertion failure (pre/post condition or assertion). If not enabled, a simple warning is issued, tracing the assertion failure.

stack(yes|no)

Whether to print out a stack trace upon assertion failure.

all(yes|no)

Enable or disables all the previously described items.

When CWCarp::Datum is switched off, the assertions are always monitored, and any failure is fatal. This is because a failing assertion is a Bad Thing in production mode. Also, since CWDREQUIRE and friends are not C macros but routines, the assertion expression is evaluated anyway, so it might as well be tested. Therefore, a directive like:

    require(n);

Here is the list of trace flags that can be specified by the configuration:

    Configuration    DTRACE flag
    -------------    -------------
              all    TRC_ALL
        emergency    TRC_EMERGENCY
            alert    TRC_ALERT
         critical    TRC_CRITICAL
            error    TRC_ERROR
          warning    TRC_WARNING
           notice    TRC_NOTICE
             info    TRC_INFO
            debug    TRC_DEBUG

    trace(n): all;
    trace(yes): emergency, alert, critical, error;

Some things are not fully documented.

Christophe Dehaudt and Raphael Manfredi are the original authors. Send bug reports, hints, tips, suggestions to Dave Hoover at <squirrel@cpan.org>.

Log::Agent(3).