.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Datum::Cfg 3pm" .TH Datum::Cfg 3pm "2009-09-20" "perl v5.10.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Carp::Datum::Cfg \- Dynamic Debug Configuration Setting for Datum .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& # In application\*(Aqs main \& use Carp::Datum qw(:all on); # turns Datum "on" or "off" \& DLOAD_CONFIG(\-file => "./debug.cf", \-config => "config string"); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" By using the \s-1DLOAD_CONFIG\s0 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. .PP 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. .SH "EXAMPLE" .IX Header "EXAMPLE" Before the obscure explaination of the grammar, here is an example of what can be specified by dynamic configuration: .PP .Vb 8 \& /* \& * 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" => ""; .Ve .SH "INTERFACE" .IX Header "INTERFACE" The only user interface is the \f(CW\*(C`DLOAD_CONFIG\*(C'\fR routine, which expects the following optional named parameters: .ie n .IP """\-config"" => \fIstring\fR" 4 .el .IP "\f(CW\-config\fR => \fIstring\fR" 4 .IX Item "-config => string" Give an inlined configuration string that is appended to the one defined by \f(CW\*(C`\-file\*(C'\fR, if any. .ie n .IP """\-file"" => \fIfilename\fR" 4 .el .IP "\f(CW\-file\fR => \fIfilename\fR" 4 .IX Item "-file => filename" Specifies the configuration file to load to initialize the debugging and tracing flags to be used for this run. .SH "CONFIGURATION DIRECTIVES" .IX Header "CONFIGURATION DIRECTIVES" .SS "Main Configuration Directives" .IX Subsection "Main Configuration Directives" The following main directives can appear at a nesting level of 0. The syntax unit known as \fI\s-1BLOCK\s0\fR is a list of semi-colon terminated directives held within curly braces. .ie n .IP """alias"" \fIlarge_path\fR => \fIshort_path\fR" 4 .el .IP "\f(CWalias\fR \fIlarge_path\fR => \fIshort_path\fR" 4 .IX Item "alias large_path => short_path" Defines an alias to be used during tracing. The \fIlarge_path\fR string is replaced by the \fIshort_path\fR in the logs. .Sp For instance, given: .Sp .Vb 1 \& alias "/home/dehaudtc/lib/CGI" => ""; .Ve .Sp then a trace for file \f(CW\*(C`/home/dehaudtc/lib/CGI/Carp.pm\*(C'\fR would be traced as coming from file \f(CW\*(C`/Carp.pm\*(C'\fR, which is nicer to read. .ie n .IP """cluster"" \fIname1\fR, \fIname2\fR \fI\s-1BLOCK\s0\fR" 4 .el .IP "\f(CWcluster\fR \fIname1\fR, \fIname2\fR \fI\s-1BLOCK\s0\fR" 4 .IX Item "cluster name1, name2 BLOCK" The \fI\s-1BLOCK\s0\fR 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: .Sp .Vb 1 \& cluster "CGI::MxScreen", "Net::MsgLink" { use silent; } .Ve .Sp This would apply to all classes under the \*(L"CGI::MxScreen\*(R" or \*(L"Net::MsgLink\*(R" name scopes, i.e. \f(CW\*(C`CGI::MxScreen::Screen\*(C'\fR would be affected. .Sp An exact match is attempted first, i.e. saying: .Sp .Vb 2 \& cluster "CGI::MxScreen" { use verbose; } \& cluster "CGI::MxScreen::Screen" { use silent; } .Ve .Sp would apply the \fIsilent\fR flags for \f(CW\*(C`CGI::MxScreen::Screen\*(C'\fR but the \fIverbose\fR ones to \f(CW\*(C`CGI::MxScreen::Tie::Stdout\*(C'\fR. .ie n .IP """default"" \fIname\fR|\fI\s-1BLOCK\s0\fR." 4 .el .IP "\f(CWdefault\fR \fIname\fR|\fI\s-1BLOCK\s0\fR." 4 .IX Item "default name|BLOCK." Specifies the default flags that should apply. The default flags can be given by providing the \fIname\fR of flags, defined by the \f(CW\*(C`flags\*(C'\fR directive, or by expansing them in the following \fI\s-1BLOCK\s0\fR. .Sp For instance: .Sp .Vb 1 \& default silent; .Ve .Sp would say that the flags to apply by default are the ones defined by an earlier \f(CW\*(C`flags silent\*(C'\fR directive. Not expanding defaults allows for quick switching by replacing \fIsilent\fR with \fIverbose\fR. It is up to the module user to define what is meant by that though. .ie n .IP """file"" \fIname1\fR, \fIname2\fR \fI\s-1BLOCK\s0\fR" 4 .el .IP "\f(CWfile\fR \fIname1\fR, \fIname2\fR \fI\s-1BLOCK\s0\fR" 4 .IX Item "file name1, name2 BLOCK" The \fI\s-1BLOCK\s0\fR defines the flags to be applied to all named files. File names are given by strings withing double quotes, as in: .Sp .Vb 1 \& file "foo.pm", "bar.pm" { use silent; } .Ve .Sp This would apply to all files named \*(L"foo.pm\*(R" or \*(L"bar.pm\*(R", whatever their directory, i.e. it would apply to \f(CW\*(C`/tmp/foo.pm\*(C'\fR as well as \f(CW\*(C`../bar.pm\*(C'\fR. .Sp An exact match is attempted first, i.e. saying: .Sp .Vb 2 \& file "foo.pm" { use verbose; } \& file "/tmp/foo.pm" { use silent; } .Ve .Sp would apply the \fIsilent\fR flags for \f(CW\*(C`/tmp/foo.pm\*(C'\fR but the \fIverbose\fR ones to \f(CW\*(C`./foo.pm\*(C'\fR. .ie n .IP """flags"" \fIname\fR \fI\s-1BLOCK\s0\fR" 4 .el .IP "\f(CWflags\fR \fIname\fR \fI\s-1BLOCK\s0\fR" 4 .IX Item "flags name BLOCK" Define a symbol \fIname\fR whose flags are described by the following \fI\s-1BLOCK\s0\fR. This \fIname\fR can then be used in \f(CW\*(C`default\*(C'\fR and \f(CW\*(C`use\*(C'\fR directives. .Sp For instance: .Sp .Vb 4 \& flags common { \& all(yes); \& trace(yes): all; \& } .Ve .Sp would define the flags known as \fIcommon\fR, which can then be re-used, as in: .Sp .Vb 4 \& flags other { \& use common; # reuses definiton of common flags \& panic(no); # but switches off panic, enabled in common \& } .Ve .Sp A flag symbol must be defined prior being used. .ie n .IP """routine"" \fIname1\fR, \fIname2\fR \fI\s-1BLOCK\s0\fR" 4 .el .IP "\f(CWroutine\fR \fIname1\fR, \fIname2\fR \fI\s-1BLOCK\s0\fR" 4 .IX Item "routine name1, name2 BLOCK" The \fI\s-1BLOCK\s0\fR defines the flags to be applied to all named routines. Routine names are given by strings within double quotes, as in: .Sp .Vb 1 \& routine "foo", "bar" { use silent; } .Ve .Sp This would apply to all routines named \*(L"foo\*(R" or \*(L"bar\*(R", whatever their package, for instance \f(CW\*(C`main::foo\*(C'\fR and \f(CW\*(C`x::bar\*(C'\fR. .SS "Debugging and Tracing Flags" .IX Subsection "Debugging and Tracing Flags" Debugging (and tracing) flags can be specified only within syntactic \fI\s-1BLOCK\s0\fR items, as expected by main directives such as \f(CW\*(C`flags\*(C'\fR or \f(CW\*(C`file\*(C'\fR. .PP 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 \fIyes\fR/\fIno\fR settings are applied sequentially. .ie n .IP """use"" \fIname\fR" 4 .el .IP "\f(CWuse\fR \fIname\fR" 4 .IX Item "use name" Uses flags defined by a \f(CW\*(C`flags\*(C'\fR directive under \fIname\fR. It acts as a recursive macro expansion (since \f(CW\*(C`use\*(C'\fR can also be specified in \f(CW\*(C`flags\*(C'\fR). The symbol \fIname\fR must have been defined earlier. .IP "flow(yes|no)" 4 .IX Item "flow(yes|no)" Whether to print out the entering/exiting of routines. That implies the invocation of the \f(CW\*(C`DFEATURE\*(C'\fR function in the routines. .IP "return(yes|no)" 4 .IX Item "return(yes|no)" Whether to print out the returned when using the return \&\f(CW\*(C`DVAL\*(C'\fR and \f(CW\*(C`DARY\*(C'\fR routines. .IP "trace(yes|no)" 4 .IX Item "trace(yes|no)" Whether to print out traces specified by the \f(CW\*(C`DTRACE\*(C'\fR function. By default all trace levels are affected. It may be followed by a list of trace levels affected by the directive, as in. .Sp .Vb 1 \& trace(yes): emergency, alert, critical; .Ve .Sp Trace levels are purely conventional, and have a strict one-to-one mapping with \f(CW\*(C`DTM_TRC_\*(C'\fR levels given at the \f(CW\*(C`DTRACE\*(C'\fR call. They are further described in \*(L"Trace Levels\*(R" below. There is one bit per defined trace level, contrary to the convention established by \fIsyslog()\fR, for better tuning. .IP "require(yes|no)" 4 .IX Item "require(yes|no)" Whether to evaluate the pre-condition given by \f(CW\*(C`DREQUIRE\*(C'\fR. But see \&\*(L"Assertion Evaluation Note\*(R" below. .IP "assert(yes|no)" 4 .IX Item "assert(yes|no)" Whether to evaluate the assertion given by \f(CW\*(C`DASSERT\*(C'\fR. But see \&\*(L"Assertion Evaluation Note\*(R" below. .IP "ensure(yes|no)" 4 .IX Item "ensure(yes|no)" Whether to evaluate the post-condition given by \f(CW\*(C`DENSURE\*(C'\fR. But see \&\*(L"Assertion Evaluation Note\*(R" below. .IP "panic(yes|no)" 4 .IX Item "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. .IP "stack(yes|no)" 4 .IX Item "stack(yes|no)" Whether to print out a stack trace upon assertion failure. .IP "all(yes|no)" 4 .IX Item "all(yes|no)" Enable or disables \fBall\fR the previously described items. .SS "Assertion Evaluation Note" .IX Subsection "Assertion Evaluation Note" When \f(CW\*(C`Carp::Datum\*(C'\fR 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 \f(CW\*(C`DREQUIRE\*(C'\fR and friends are not C macros but routines, the assertion expression is evaluated anyway, so it might as well be tested. .PP Therefore, a directive like: .PP .Vb 1 \& require(no); .Ve .PP 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). .SS "Trace Levels" .IX Subsection "Trace Levels" Here is the list of trace flags that can be specified by the configuration: .PP .Vb 11 \& 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 .Ve .PP A user could say something like: .PP .Vb 2 \& trace(no): all; \& trace(yes): emergency, alert, critical, error; .Ve .PP Since flags are applied in sequence, the first directive turns all tracing flags to off, the second enables only the listed ones. .SH "BUGS" .IX Header "BUGS" Some things are not fully documented. .SH "AUTHORS" .IX Header "AUTHORS" Christophe Dehaudt and Raphael Manfredi are the original authors. .PP Send bug reports, hints, tips, suggestions to Dave Hoover at . .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fILog::Agent\fR\|(3).