Provided by: libcarp-datum-perl_0.1.3-9_all bug

NAME

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

SYNOPSIS

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

DESCRIPTION

       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.

EXAMPLE

       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(no);
             trace(no);
             return(no);
         }

         /*
          * 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(no);
             ensure(no);
         }

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

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

INTERFACE

       The only user interface is the "DLOAD_CONFIG" routine, which expects the following
       optional named parameters:

       "-config" => string
           Give an inlined configuration string that is appended to the one defined by "-file",
           if any.

       "-file" => filename
           Specifies the configuration file to load to initialize the debugging and tracing flags
           to be used for this run.

CONFIGURATION DIRECTIVES

   Main Configuration Directives
       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.

       "alias" large_path => short_path
           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>";

           then a trace for file "/home/dehaudtc/lib/CGI/Carp.pm" would be traced as coming from
           file "<CGI>/Carp.pm", which is nicer to read.

       "cluster" name1, name2 BLOCK
           The BLOCK defines the flags to be applied to all named clusters.  A cluster is a set
           of classes under a given name scope.  Cluster names are given by strings within double
           quotes, as in:

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

           This would apply to all classes under the "CGI::MxScreen" or "Net::MsgLink" name
           scopes, i.e. "CGI::MxScreen::Screen" would be affected.

           An exact match is attempted first, i.e. saying:

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

           would apply the silent flags for "CGI::MxScreen::Screen" but the verbose ones to
           "CGI::MxScreen::Tie::Stdout".

       "default" name|BLOCK.
           Specifies the default flags that should apply.  The default flags can be given by
           providing the name of flags, defined by the "flags" directive, or by expansing them in
           the following BLOCK.

           For instance:

               default silent;

           would say that the flags to apply by default are the ones defined by an earlier "flags
           silent" directive.  Not expanding defaults allows for quick switching by replacing
           silent with verbose.  It is up to the module user to define what is meant by that
           though.

       "file" name1, name2 BLOCK
           The BLOCK defines the flags to be applied to all named files.  File names are given by
           strings withing double quotes, as in:

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

           This would apply to all files named "foo.pm" or "bar.pm", whatever their directory,
           i.e. it would apply to "/tmp/foo.pm" as well as "../bar.pm".

           An exact match is attempted first, i.e. saying:

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

           would apply the silent flags for "/tmp/foo.pm" but the verbose ones to "./foo.pm".

       "flags" name BLOCK
           Define a symbol name whose flags are described by the following BLOCK.  This name can
           then be used in "default" and "use" directives.

           For instance:

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

           would define the flags known as common, which can then be re-used, as in:

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

           A flag symbol must be defined prior being used.

       "routine" name1, name2 BLOCK
           The BLOCK defines the flags to be applied to all named routines.  Routine names are
           given by strings within double quotes, as in:

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

           This would apply to all routines named "foo" or "bar", whatever their package, for
           instance "main::foo" and "x::bar".

   Debugging and Tracing Flags
       Debugging (and tracing) flags can be specified only within syntactic BLOCK items, as
       expected by main directives such as "flags" or "file".

       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.

       "use" name
           Uses flags defined by a "flags" directive under name.  It acts as a recursive macro
           expansion (since "use" can also be specified in "flags").  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 "DFEATURE" function in the routines.

       return(yes|no)
           Whether to print out the returned when using the return "DVAL" and "DARY" routines.

       trace(yes|no)
           Whether to print out traces specified by the "DTRACE" 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
           "DTM_TRC_" levels given at the "DTRACE" 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 "DREQUIRE".  But see "Assertion
           Evaluation Note" below.

       assert(yes|no)
           Whether to evaluate the assertion given by "DASSERT".  But see "Assertion Evaluation
           Note" below.

       ensure(yes|no)
           Whether to evaluate the post-condition given by "DENSURE".  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.

   Assertion Evaluation Note
       When "Carp::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 "DREQUIRE" 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(no);

       will only turn off monitoring of pre-conditions in debugging mode (e.g. because the
       interface is not finalized, or the clients do not behave properly yet).

   Trace Levels
       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

       A user could say something like:

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

       Since flags are applied in sequence, the first directive turns all tracing flags to off,
       the second enables only the listed ones.

BUGS

       Some things are not fully documented.

AUTHORS

       Christophe Dehaudt and Raphael Manfredi are the original authors.

       Send bug reports, hints, tips, suggestions to Dave Hoover at <squirrel@cpan.org>.

SEE ALSO

       Log::Agent(3).