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

FreeBSD Manual Pages

  
 
  

home | help
Devel::Confess(3)     User Contributed Perl Documentation    Devel::Confess(3)

NAME
       Devel::Confess -	Include	stack traces on	all warnings and errors

SYNOPSIS
       Use on the command line:

	 # Make	every warning and error	include	a full stack trace
	 perl -d:Confess script.pl

	 # Also	usable as a module
	 perl -MDevel::Confess script.pl

	 # display warnings in yellow and errors in red
	 perl -d:Confess=color script.pl

	 # set options by environment
	 export	DEVEL_CONFESS_OPTIONS='color dump'
	 perl -d:Confess script.pl

       Can also	be used	inside a script:

	 use Devel::Confess;

	 use Devel::Confess 'color';

	 # disable stack traces
	 no Devel::Confess;

DESCRIPTION
       This module is meant as a debugging aid.	It can be used to make a
       script complain loudly with stack backtraces when "warn()"ing or
       "die()"ing.  Unlike other similar modules (e.g. Carp::Always), stack
       traces will also	be included when exception objects are thrown.

       The stack traces	are generated using Carp, and will work	for all	types
       of errors.  Carp's "carp" and "croak" functions will also be made to
       include stack traces.

	 # it works for	explicit die's and warn's
	 $ perl	-d:Confess -e 'sub f { die "arghh" }; sub g { f	}; g'
	 arghh at -e line 1.
		 main::f() called at -e	line 1
		 main::g() called at -e	line 1

	 # it works for	interpreter-thrown failures
	 $ perl	-d:Confess -w -e 'sub f	{ $a = shift; @a = @$a };' \
					       -e 'sub g { f(undef) }; g'
	 Use of	uninitialized value $a in array	dereference at -e line 1.
		 main::f(undef)	called at -e line 2
		 main::g() called at -e	line 2

       Internally, this	is implemented with $SIG{__WARN__} and $SIG{__DIE__}
       hooks.

       Stack traces are	also included if raw non-object	references are thrown.

       This module is compatible with all perl versions	back to	5.6.2, without
       additional prerequisites.  It contains workarounds for a	number of bugs
       in the perl interpreter,	some of	which effect comparatively simpler
       modules,	like Carp::Always.

METHODS
   import( @options )
       Enables stack traces and	sets options.  A list of options to enable can
       be passed in.  Prefixing	the options with "no_" will disable them.

       "objects"
	   Enable attaching stack traces to exception objects.	Enabled	by
	   default.

       "builtin"
	   Load	the Devel::Confess::Builtin module to use built	in stack
	   traces on supported exception types.	 Disabled by default.

       "dump"
	   Dumps the contents of references in arguments in stack trace,
	   instead of only showing their stringified version.  Also causes
	   exceptions that are non-object references and objects without
	   string overloads to be dumped if being displayed.  Shows up to
	   three references deep.  Disabled by default.

       "dump0",	"dump1", "dump2", etc
	   The same as the dump	option,	but with a different max depth to
	   dump.  A depth of 0 is treated as infinite.

       "color"
	   Colorizes error messages in red and warnings	in yellow.  Disabled
	   by default.

       "source"
	   Includes a snippet of the source for	each level of the stack	trace.
	   Disabled by default.

       "source0", "source1", "source2",	etc
	   Enables source display, but with a specified	number of lines	of
	   context to show.  Context of	0 will show the	entire source of the
	   files.

       "evalsource"
	   Similar to the source option, but only shows	includes source	for
	   string evals.  Useful for seeing the	results	of code	generation.
	   Disabled by default.	 Overrides the source option.

       "evalsource0", "evalsource1", "evalsource2", etc
	   Enables eval	source display,	but with a specified number of lines
	   of context to show.	Context	of 0 will show the entire source of
	   the evals.

       "better_names"
	   Use more informative	names to string	evals and anonymous subs in
	   stack traces.  Enabled by default.

       "errors"
	   Add stack traces to errors.	Enabled	by default.

       "warnings"
	   Add stack traces to warnings.  Enabled by default.

       The default options can be changed by setting the
       "DEVEL_CONFESS_OPTIONS" environment variable to a space separated list
       of options.

CONFIGURATION
   %Devel::Confess::NoTrace
       Classes or roles	added to this hash will	not have stack traces attached
       to them.	 This is useful	for exception classes that provide their own
       stack traces, or	classes	that don't cope	well with being	re-blessed.
       If Devel::Confess::Builtin is loaded, it	will automatically add its
       supported exception types to this hash.

       Default Entries:

       Throwable::Error
	   Provides a stack trace

       Moose::Error::Default
	   Provides a stack trace

ACKNOWLEDGMENTS
       The idea	and parts of the code and documentation	are taken from
       Carp::Always.

SEE ALSO
       o   Carp::Always

       o   Carp

       o   Acme::JavaTrace and Devel::SimpleTrace

       o   Carp::Always::Color

       o   Carp::Source::Always

       o   Carp::Always::Dump

CAVEATS
       This module uses	several	ugly tricks to do its work and surely has
       bugs.

       o   This	module uses $SIG{__WARN__} and $SIG{__DIE__} to	accomplish its
	   goal, and thus may not play well with other modules that try	to use
	   these hooks.	 Significant effort has	gone into making this work as
	   well	as possible, but global	variables like these can never be
	   fully encapsulated.

       o   To provide stack traces on exception	objects, this module re-
	   blesses the exception objects into a	generated class.  While	it
	   tries to have the smallest effect it	can, some things cannot	be
	   worked around.  In particular, "ref($exception)" will return	a
	   different value than	may be expected.  Any module that relies on
	   the specific	return value from "ref"	like already has bugs though.

SUPPORT
       Please report bugs via CPAN RT
       <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Devel-Confess>.

AUTHORS
       o   Graham Knop <haarg@haarg.org>

CONTRIBUTORS
       o   Adriano Ferreira <ferreira@cpan.org>

COPYRIGHT
       Copyright (c) 2005-2013 the "AUTHORS" and "CONTRIBUTORS"	as listed
       above.

LICENSE
       This library is free software and may be	distributed under the same
       terms as	perl itself. See <http://dev.perl.org/licenses/>.

perl v5.24.1			  2017-02-14		     Devel::Confess(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | CONFIGURATION | ACKNOWLEDGMENTS | SEE ALSO | CAVEATS | SUPPORT | AUTHORS | CONTRIBUTORS | COPYRIGHT | LICENSE

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

home | help