Devel::Confess(3)

📦
version 0.009004 · 9 versions
, in opensuse-leap 16.0

✨ Devel::Confess — a.k.a. the perl manpage you're reading, bestie ✨

Okay so this is the Devel::Confess(3) page from the User Contributed Perl Documentation section, and honestly? It's a glow-up for your error messages. Let's get into it. 💅

🌸 NAME 🌸

Devel::Confess — literally just "include stack traces on all warnings and errors." That's the whole brand. Periodt.

🦋 SYNOPSIS 🦋

So you can use it on the command line, like this:

# 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

Or you can summon it from inside a script, which? Also iconic:

use Devel::Confess;

use Devel::Confess 'color';

# disable stack traces
no Devel::Confess;

🎀 DESCRIPTION 🎀

So this module is a debugging aid — like, its entire purpose in life is to make your script complain loudly with stack backtraces whenever it warn()s or die()s. Love that for it.

And here's the slay: unlike other similar modules (e.g. Carp::Always), stack traces also get included when exception objects are thrown. Not just regular warnings, not just regular errors — the fancy object ones too. 💖

The stack traces are generated using Carp, and they work for all types of errors. Carp's carp and croak functions also get made over to include stack traces. Everyone's invited.

# 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? It's implemented with $SIG{__WARN__} and $SIG{__DIE__} hooks. Sneaky. Clever. We stan.

Stack traces also get included if raw non-object references are thrown. Yep, even those little guys.

And ngl, this module is compatible with all perl versions back to 5.6.2, with no additional prerequisites. It contains workarounds for a number of bugs in the perl interpreter — some of which affect comparatively simpler modules, like Carp::Always. So it's doing the most so you can do the least. 🫶

⭐ METHODS ⭐

import( @options )

Enables stack traces and sets options. You can pass in a list of options to enable — and here's the trick: prefixing any option with "no_" disables it. Cute, right?

  • "objects" — enable attaching stack traces to exception objects. Enabled by default.
  • "builtin" — load the Devel::Confess::Builtin module so it uses built-in stack traces on supported exception types. Disabled by default.
  • "dump" — dumps the contents of references in arguments in the 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 — same as the dump option, but with a different max depth to dump. A depth of 0 is treated as infinite. (Careful with that one bestie 😭)
  • "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 shows the entire source of the files.
  • "evalsource" — similar to the source option, but only shows 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 shows the entire source of the evals.
  • "better_names" — use more informative names for 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.

Oh and the default options can be changed by setting the "DEVEL_CONFESS_OPTIONS" environment variable to a space-separated list of options. Set it and forget it. ✨

🌈 CONFIGURATION 🌈

%Devel::Confess::NoTrace

Classes or roles added to this hash will not have stack traces attached to them. Super useful for exception classes that already provide their own stack traces, or classes that don't cope well with being re-blessed. And if Devel::Confess::Builtin is loaded, it automatically adds its supported exception types to this hash. Teamwork. 🤝

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. Credit where credit is due, fr fr.

🔥 SEE ALSO 🔥

  • Carp::Always
  • Carp
  • Acme::JavaTrace and Devel::SimpleTrace
  • Carp::Always::Color
  • Carp::Source::Always
  • Carp::Always::Dump

Go read them. Or don't. I'm a manpage, not a cop. 🦋

💀 CAVEATS 💀

Okay bestie, deep breath. This module uses several ugly tricks to do its work and surely has bugs. It said it, not me.

  • 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. It's giving unavoidable chaos, honestly.
  • 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" already has bugs though — so like, that's on them. 🙈

🍓 SUPPORT 🍓

Please report bugs via CPAN RT <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Devel-Confess>. The link is literally right there, use it. 💅

👑 AUTHORS 👑

  • Graham Knop <haarg@haarg.org>

🧚 CONTRIBUTORS 🧚

  • Adriano Ferreira <ferreira@cpan.org>

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

Okay that's the whole page! 🎀 This little gem landed on 2017-02-21, ships with perl v5.42.0, and lives in the User Contributed Perl Documentation. Go forth and confess your stack traces, bestie — you got this. 💖✨
📦 where this page comes from