1Devel::Confess(3) User Contributed Perl Documentation Devel::Confess(3)
2
6 Devel::Confess - Include stack traces on all warnings and errors
7
9 Use on the command line:
10 # Make every warning and error include a full stack trace
12 perl -d:Confess script.pl
13 # Also usable as a module
15 perl -MDevel::Confess script.pl
16 # display warnings in yellow and errors in red
18 perl -d:Confess=color script.pl
19 # set options by environment
21 export DEVEL_CONFESS_OPTIONS='color dump'
22 perl -d:Confess script.pl
23 Can also be used inside a script:
25 use Devel::Confess;
27 use Devel::Confess 'color';
29 # disable stack traces
31 no Devel::Confess;
32
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 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 # 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 # 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 Internally, this is implemented with $SIG{__WARN__} and $SIG{__DIE__}
57 hooks.
58 Stack traces are also included if raw non-object references are thrown.
60 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
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 "objects"
72 Enable attaching stack traces to exception objects. Enabled by
73 default.
74 "builtin"
76 Load the Devel::Confess::Builtin module to use built in stack
77 traces on supported exception types. Disabled by default.
78 "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 "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 "color"
91 Colorizes error messages in red and warnings in yellow. Disabled
92 by default.
93 "source"
95 Includes a snippet of the source for each level of the stack trace.
96 Disabled by default.
97 "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 "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 "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 "better_names"
114 Use more informative names to string evals and anonymous subs in
115 stack traces. Enabled by default.
116 "errors"
118 Add stack traces to errors. Enabled by default.
119 "warnings"
121 Add stack traces to warnings. Enabled by default.
122 The default options can be changed by setting the
124 "DEVEL_CONFESS_OPTIONS" environment variable to a space separated list
125 of options.
126
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 Default Entries:
136 Throwable::Error
138 Provides a stack trace
139 Moose::Error::Default
141 Provides a stack trace
142
144 The idea and parts of the code and documentation are taken from
145 Carp::Always.
146
148 • Carp::Always
149 • Carp
151 • Acme::JavaTrace and Devel::SimpleTrace
153 • Carp::Always::Color
155 • Carp::Source::Always
157 • Carp::Always::Dump
159
161 This module uses several ugly tricks to do its work and surely has
162 bugs.
163 • 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 • 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
178 Please report bugs via CPAN RT
179 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Devel-Confess>.
180
182 • Graham Knop <haarg@haarg.org>
183
185 • Adriano Ferreira <ferreira@cpan.org>
186
188 Copyright (c) 2005-2013 the "AUTHORS" and "CONTRIBUTORS" as listed
189 above.
190
192 This library is free software and may be distributed under the same
193 terms as perl itself. See <http://dev.perl.org/licenses/>.
194perl v5.36.0 2023-01-20 Devel::Confess(3)