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

Provided by: libdevel-confess-perl_0.009004-3_all

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.

CAVEATS

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

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

       •   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

       •   Graham Knop <haarg@haarg.org>

CONTRIBUTORS

       •   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.36.0                                       2022-10-15                                Devel::Confess(3pm)