--- name: "Carp::Datum::Cfg" section: "3pm" platform: "linux" package: "libcarp-datum-perl" version: "1:0.1.3-9" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Carp::Datum::Cfg" --- # Carp::Datum::Cfg(3pm) Dynamic Debug Configuration Setting for Datum ## 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" => ""; ``` ## 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" => ""; ``` then a trace for file `"/home/dehaudtc/lib/CGI/Carp.pm"` would be traced as coming from file `"/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 \. ## SEE ALSO **Log::Agent**(3).