MainConfigurationDirectives
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, name2BLOCK
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, name2BLOCK
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" nameBLOCK
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, name2BLOCK
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".
DebuggingandTracingFlags
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.
AssertionEvaluationNote
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).
TraceLevels
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.
Install Now
