Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Datum::Cfg(3)	      User Contributed Perl Documentation	 Datum::Cfg(3)

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).

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 605:
	   You forgot a	'=back'	before '=head2'

perl v5.32.0			  2002-01-16			 Datum::Cfg(3)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLE | INTERFACE | CONFIGURATION DIRECTIVES | BUGS | AUTHORS | SEE ALSO | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Carp::Datum::Cfg&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help