gitpan / carp-always-andrefs Goto Github PK

NAME
    Carp::Always::AndRefs - Warns and dies noisily with stack backtraces

SYNOPSIS
      use Carp::Always::AndRefs;

    makes every "warn()" and "die()" complains loudly in the calling package
    and elsewhere. More often used on the command line:

      perl -MCarp::Always::AndRefs script.pl

    Also includes Devel::Confess as an alias:

      perl -MDevel::Confess script.pl

    or

      perl -d:Confess script.pl

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.

    Here are how stack backtraces produced by this module looks:

      # it works for explicit die's and warn's
      $ perl -MCarp::Always::AndRefs -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 -MCarp::Always::AndRefs -w -e 'sub f { $a = shift; @a = @$a };' \
                                        -e 'sub g { f(undef) }; g'
      Use of uninitialized value in array dereference at -e line 1.
              main::f('undef') called at -e line 2
              main::g() called at -e line 2

    In the implementation, the "Carp" module does the heavy work, through
    "longmess()". The actual implementation sets the signal hooks
    $SIG{__WARN__} and $SIG{__DIE__} to emit the stack backtraces.

    Oh, by the way, "carp" and "croak" when requiring/using the "Carp"
    module are also made verbose, behaving like "cluck" and "confess",
    respectively.

    Stack traces will also be included for exception objects and non-object
    references.

METHODS
  import( @options )
    Enables stack traces and sets options. Options can be prefixed with no_
    to disable them.

    "objects"
        Enable attaching stack traces to exception objects. Defaults to on.

    "hacks"
        Load the Carp::Always::AndRefs::Hacks module to use built in stack
        traces on supported exception types.

CONFIGURATION
  %Carp::Always::AndRefs::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
    Carp::Always::AndRefs::Hacks 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

    Ouch
        Conflicts with mechanism used to attach stack traces.

ACKNOWLEDGMENTS
    The idea, part of the code, and most of the documentation are taken from
    Carp::Always.

SEE ALSO
    *   Carp::Always

    *   Carp

    *   Acme::JavaTrace and Devel::SimpleTrace

    *   Carp::Always::Color

    *   Carp::Source::Always

    Please report bugs via CPAN RT
    http://rt.cpan.org/NoAuth/Bugs.html?Dist=Carp-Always-AndRefs.

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

    *   This module does not play well with other modules which fusses
        around with "warn", "die", $SIG{'__WARN__'}, $SIG{'__DIE__'}.

AUTHORS
    *   Graham Knop, <[email protected]>

    *   Adriano Ferreira, <[email protected]>

CONTRIBUTORS
    None yet.

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