1Devel::Confess(3)     User Contributed Perl Documentation    Devel::Confess(3)
2
3
4

NAME

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

SYNOPSIS

9       Use on the command line:
10
11         # Make every warning and error include a full stack trace
12         perl -d:Confess script.pl
13
14         # Also usable as a module
15         perl -MDevel::Confess script.pl
16
17         # display warnings in yellow and errors in red
18         perl -d:Confess=color script.pl
19
20         # set options by environment
21         export DEVEL_CONFESS_OPTIONS='color dump'
22         perl -d:Confess script.pl
23
24       Can also be used inside a script:
25
26         use Devel::Confess;
27
28         use Devel::Confess 'color';
29
30         # disable stack traces
31         no Devel::Confess;
32

DESCRIPTION

34       This module is meant as a debugging aid. It can be used to make a
35       script complain loudly with stack backtraces when "warn()"ing or
36       "die()"ing.  Unlike other similar modules (e.g. Carp::Always), stack
37       traces will also be included when exception objects are thrown.
38
39       The stack traces are generated using Carp, and will work for all types
40       of errors.  Carp's "carp" and "croak" functions will also be made to
41       include stack traces.
42
43         # it works for explicit die's and warn's
44         $ perl -d:Confess -e 'sub f { die "arghh" }; sub g { f }; g'
45         arghh at -e line 1.
46                 main::f() called at -e line 1
47                 main::g() called at -e line 1
48
49         # it works for interpreter-thrown failures
50         $ perl -d:Confess -w -e 'sub f { $a = shift; @a = @$a };' \
51                                               -e 'sub g { f(undef) }; g'
52         Use of uninitialized value $a in array dereference at -e line 1.
53                 main::f(undef) called at -e line 2
54                 main::g() called at -e line 2
55
56       Internally, this is implemented with $SIG{__WARN__} and $SIG{__DIE__}
57       hooks.
58
59       Stack traces are also included if raw non-object references are thrown.
60
61       This module is compatible with all perl versions back to 5.6.2, without
62       additional prerequisites.  It contains workarounds for a number of bugs
63       in the perl interpreter, some of which effect comparatively simpler
64       modules, like Carp::Always.
65

METHODS

67   import( @options )
68       Enables stack traces and sets options.  A list of options to enable can
69       be passed in.  Prefixing the options with "no_" will disable them.
70
71       "objects"
72           Enable attaching stack traces to exception objects.  Enabled by
73           default.
74
75       "builtin"
76           Load the Devel::Confess::Builtin module to use built in stack
77           traces on supported exception types.  Disabled by default.
78
79       "dump"
80           Dumps the contents of references in arguments in stack trace,
81           instead of only showing their stringified version.  Also causes
82           exceptions that are non-object references and objects without
83           string overloads to be dumped if being displayed.  Shows up to
84           three references deep.  Disabled by default.
85
86       "dump0", "dump1", "dump2", etc
87           The same as the dump option, but with a different max depth to
88           dump.  A depth of 0 is treated as infinite.
89
90       "color"
91           Colorizes error messages in red and warnings in yellow.  Disabled
92           by default.
93
94       "source"
95           Includes a snippet of the source for each level of the stack trace.
96           Disabled by default.
97
98       "source0", "source1", "source2", etc
99           Enables source display, but with a specified number of lines of
100           context to show.  Context of 0 will show the entire source of the
101           files.
102
103       "evalsource"
104           Similar to the source option, but only shows includes source for
105           string evals.  Useful for seeing the results of code generation.
106           Disabled by default.  Overrides the source option.
107
108       "evalsource0", "evalsource1", "evalsource2", etc
109           Enables eval source display, but with a specified number of lines
110           of context to show.  Context of 0 will show the entire source of
111           the evals.
112
113       "better_names"
114           Use more informative names to string evals and anonymous subs in
115           stack traces.  Enabled by default.
116
117       "errors"
118           Add stack traces to errors.  Enabled by default.
119
120       "warnings"
121           Add stack traces to warnings.  Enabled by default.
122
123       The default options can be changed by setting the
124       "DEVEL_CONFESS_OPTIONS" environment variable to a space separated list
125       of options.
126

CONFIGURATION

128   %Devel::Confess::NoTrace
129       Classes or roles added to this hash will not have stack traces attached
130       to them.  This is useful for exception classes that provide their own
131       stack traces, or classes that don't cope well with being re-blessed.
132       If Devel::Confess::Builtin is loaded, it will automatically add its
133       supported exception types to this hash.
134
135       Default Entries:
136
137       Throwable::Error
138           Provides a stack trace
139
140       Moose::Error::Default
141           Provides a stack trace
142

ACKNOWLEDGMENTS

144       The idea and parts of the code and documentation are taken from
145       Carp::Always.
146

SEE ALSO

148       •   Carp::Always
149
150       •   Carp
151
152       •   Acme::JavaTrace and Devel::SimpleTrace
153
154       •   Carp::Always::Color
155
156       •   Carp::Source::Always
157
158       •   Carp::Always::Dump
159

CAVEATS

161       This module uses several ugly tricks to do its work and surely has
162       bugs.
163
164       •   This module uses $SIG{__WARN__} and $SIG{__DIE__} to accomplish its
165           goal, and thus may not play well with other modules that try to use
166           these hooks.  Significant effort has gone into making this work as
167           well as possible, but global variables like these can never be
168           fully encapsulated.
169
170       •   To provide stack traces on exception objects, this module re-
171           blesses the exception objects into a generated class.  While it
172           tries to have the smallest effect it can, some things cannot be
173           worked around.  In particular, "ref($exception)" will return a
174           different value than may be expected.  Any module that relies on
175           the specific return value from "ref" like already has bugs though.
176

SUPPORT

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

AUTHORS

182       •   Graham Knop <haarg@haarg.org>
183

CONTRIBUTORS

185       •   Adriano Ferreira <ferreira@cpan.org>
186
188       Copyright (c) 2005-2013 the "AUTHORS" and "CONTRIBUTORS" as listed
189       above.
190

LICENSE

192       This library is free software and may be distributed under the same
193       terms as perl itself. See <http://dev.perl.org/licenses/>.
194
195
196
197perl v5.34.0                      2021-07-22                 Devel::Confess(3)
Impressum