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