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 -MDevel::Confess script.pl
# equivalent short form
perl -d: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), it includes stack traces even
when exception objects are thrown.
The stack traces are generated using Carp, and will look work for all
types of errors. Carp's "carp" and "confess" functions will also be made
to include stack traces.
# it works for explicit die's and warn's
$ perl -MDevel::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 -MDevel::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.
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. 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.
"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
* Carp::Always
* Carp
* Acme::JavaTrace and Devel::SimpleTrace
* Carp::Always::Color
* Carp::Source::Always
* Carp::Always::Dump
Please report bugs via CPAN RT
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Devel-Confess.
BUGS
This module uses several ugly tricks to do its work and surely has bugs.
* This module does not play well with other modules which fusses
around with "warn", "die", $SIG{'__WARN__'}, $SIG{'__DIE__'}.
AUTHORS
* Graham Knop, <haarg@haarg.org>
* Adriano Ferreira, <ferreira@cpan.org>
CONTRIBUTORS
None yet.
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/>.