NAME

       Devel::DollarAt - Give magic abilities to $@

SYNOPSIS

           use Devel::DollarAt;

           eval "0/0";
           print $@, $@->backtrace;
           $@->redie;

DESCRIPTION

       Using eval {}, you may catch Perl exceptions almost like you do it with try {} in Java.
       However there are days when you miss some features of exceptions.  The only thing you know
       about the error that occured is the string $@, which combines the error message and
       technical data like the line number.

       The Devel::DollarAt module gives some functionality to the $@ scalar.  Once you say "use
       Devel::DollarAt", the module is active program-wide.  If an exception occurs anywhere in
       any module, $@ will be globally set to an object of class Devel::DollarAt.  Apart from
       performance, this shouldn't be a problem because $@ tries to be downwardly compatible to
       the normal $@.  However using this package in CPAN modules or large software projects is
       discouraged.

DISCLAIMER

       Use this module only for debugging.  Don't think of it as an exception framework for Perl
       or something like that.  It just gives magic abilities to $@, that's all.

METHODS

       backtrace
               Returns a Devel::Backtrace object, which lets you inspect the callers of the
               fatality.

       filename
               Returns the name of the file in which the error occured.

       inputhandle
               Returns the file handle which has most recently be read from at the time of the
               error.

       inputline
               Returns the line number of "$@->inputhandle" (which is $.) at the time of the
               error.

       line    Returns the number of the line in which the error occured.

       redie   Redispatches this exception to the next eval{}.

       redispatch_points
               Returns a list of objects with information about when this exception was
               redispatched.  Each object has got the accessors "package", "filename" and "line".
               In string context, the objects will look like "redispatched from FooPackage at
               file.pl:17\n".

       to_string
               Returns a string that looks quite like the normal $@, e. g. "Illegal division by
               zero at foo.pl line 42, <> line 13."  Devel::DollarAt overloads the ""
               (stringification) operator to this method.

EXAMPLES

       A very simple (and pointless) way to use Devel::DollarAt is this oneliner:

           perl -MDevel::DollarAt -e '0/0'

       It bails out with "Illegal division by zero at -e line 1." and an exit status of 1, just
       like it would have done if you hadn't supplied -MDevel::DollarAt.  This is because the
       magically modified $@ variable gets stringified when perl prints it as exit reason.  If
       you actually want to see the difference, use

           perl -MDevel::DollarAt=frame -e '0/0'

       This bails out with "[[Illegal division by zero at -e line 1.]]" so you can see that
       something has happened.

KNOWN PROBLEMS

       This module requires that no other code tampers with $SIG{__DIE__} or *CORE::GLOBAL::die.

       A not widely known feature of Perl is that it can propagate $@.  If you call die() without
       parameters or with an empty string or an undefined value, the error message will be
       "Died".  However, if $@ was set to some value before this, the previous error message will
       be used with "\t...propagated" appended:

           perl -e '$@="7"; die"
           7       ...propagated at -e line 1.

       Devel::DollarAt emulates this behaviour.

       If you use the above example but leave out the double quotes, perl's behaviour is
       different as of version 5.8.8:

           perl -e '$@=7; die'
           7 at -e line 1.

       Devel::DollarAt does not emulate this behaviour:

           perl -MDevel::DollarAt -e '$@=7; die'
           7       ...propagated at -e line 1.

       If a previous $@ is propagated, inputhandle and inputline won't work.  They won't be
       interpolated into the stringified $@, either.

       If perl comes across syntax errors, $@ appears to be just a string as usual.  Apparently
       $SIG{__DIE__} won't be called for syntax errors.

AUTHOR

       Christoph Bussenius <pepe@cpan.org>

       If you use this module, I'll be glad if you drop me a note.  You should mention this
       module's name in the subject of your mails, in order to make sure they won't get lost in
       all the spam.

LICENSE

       This module is in the public domain.

       If your country's law does not allow this module being in the public domain or does not
       include the concept of public domain, you may use the module under the same terms as perl
       itself.