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.

SEE ALSO
    *   Carp::Always

    *   Carp

    *   Acme::JavaTrace and Devel::SimpleTrace

    *   Carp::Always::Color

    *   Carp::Source::Always

    *   Carp::Always::Dump

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