+++ /dev/null
-# Copyright (c) 2010 Elizabeth Grace Frank-Backman.
-# All rights reserved.
-# Liscenced under the "Artistic Liscence"
-# (see http://dev.perl.org/licenses/artistic.html)
-
-use 5.8.8;
-use strict;
-use warnings;
-use overload;
-
-package Exception::Lite;
-our @ISA = qw(Exporter);
-our @EXPORT_OK=qw(declareExceptionClass isException isChainable
- onDie onWarn);
-our %EXPORT_TAGS
- =( common => [qw(declareExceptionClass isException isChainable)]
- , all => [@EXPORT_OK]
- );
-my $CLASS='Exception::Lite';
-
-#------------------------------------------------------------------
-
-our $STRINGIFY=3;
-our $FILTER=1;
-our $UNDEF='<undef>';
-our $TAB=3;
-our $LINE_LENGTH=120;
-
-# provide command line control over amount and layout of debugging
-# information, e.g. perl -mException::Lite=STRINGIFY=4
-
-sub import {
- Exception::Lite->export_to_level(1, grep {
- if (/^(\w+)=(.*)$/) {
- my $k = $1;
- my $v = $2;
- if ($k eq 'STRINGIFY') { $STRINGIFY=$v;
- } elsif ($k eq 'FILTER') { $FILTER=$v;
- } elsif ($k eq 'LINE_LENGTH') { $LINE_LENGTH=$v;
- } elsif ($k eq 'TAB') { $TAB=$v;
- }
- 0;
- } else {
- 1;
- }
- } @_);
-}
-
-#------------------------------------------------------------------
-# Note to source code divers: DO NOT USE THIS. This is intended for
-# internal use but must be declared with "our" because we need to
-# localize it. This is an implementation detail and cannot be relied
-# on for future releases.
-
-our $STACK_OFFSET=0;
-
-#------------------------------------------------------------------
-
-use Scalar::Util ();
-use constant EVAL => '(eval)';
-
-#==================================================================
-# EXPORTABLE FUNCTIONS
-#==================================================================
-
-sub declareExceptionClass {
- my ($sClass, $sSuperClass, $xFormatRule, $bCustomizeSubclass) = @_;
- my $sPath = $sClass; $sPath =~ s/::/\//g; $sPath .= '.pm';
- if ($INC{$sPath}) {
- # we want to start with the caller's frame, not ours
- local $STACK_OFFSET = $STACK_OFFSET + 1;
- die 'Exception::Lite::Any'->new("declareExceptionClass failed: "
- . "$sClass is already defined!");
- return undef;
- }
-
- my $sRef=ref($sSuperClass);
- if ($sRef) {
- $bCustomizeSubclass = $xFormatRule;
- $xFormatRule = $sSuperClass;
- $sSuperClass=undef;
- } else {
- $sRef = ref($xFormatRule);
- if (!$sRef && defined($xFormatRule)) {
- $bCustomizeSubclass = $xFormatRule;
- $xFormatRule = undef;
- }
- }
-
- # set up things dependent on whether or not the class has a
- # format string or expects a message for each instance
-
- my ($sLeadingParams, $sAddOrOmit, $sRethrowMsg, $sMakeMsg);
- my $sReplaceMsg='';
-
- if ($sRef) {
- $sLeadingParams='my $e; $e=shift if ref($_[0]);';
- $sAddOrOmit='added an unnecessary message or format';
- $sRethrowMsg='';
-
- #generate format rule
- $xFormatRule=$xFormatRule->($sClass) if ($sRef eq 'CODE');
-
- my $sFormat= 'q{' . $xFormatRule->[0] . '}';
- if (scalar($xFormatRule) == 1) {
- $sMakeMsg='my $msg='.$sFormat;
- } else {
- my $sSprintf = 'Exception::Lite::_sprintf(' . $sFormat
- . ', map {defined($_)?$_:\''. $UNDEF .'\'} @$h{qw('
- . join(' ', @$xFormatRule[1..$#$xFormatRule]) . ')});';
- $sMakeMsg='my $msg='.$sSprintf;
- $sReplaceMsg='$_[0]->[0]='.$sSprintf;
- }
-
- } else {
- $sLeadingParams = 'my $e=shift; my $msg;'.
- 'if(ref($e)) { $msg=shift; $msg=$e->[0] if !defined($msg);}'.
- 'else { $msg=$e;$e=undef; }';
- $sAddOrOmit='omitted a required message';
- $sRethrowMsg='my $msg=shift; $_[0]->[0]=$msg if defined($msg);';
- $sMakeMsg='';
- }
-
- # put this in an eval so that it doesn't cause parse errors at
- # compile time in no-threads versions of Perl
-
- my $sTid = eval q{defined(&threads::tid)?'threads->tid':'undef'};
-
- my $sDeclare = "package $sClass;".
- 'sub new { my $cl=shift;'. $sLeadingParams .
- 'my $st=Exception::Lite::_cacheStackTrace($e);'.
- 'my $h= Exception::Lite::_shiftProperties($cl' .
- ',$st,"'.$sAddOrOmit.'",@_);' . $sMakeMsg .
- 'my $self=bless([$msg,$h,$st,$$,'.$sTid.',$e,[]],$cl);';
-
- # the remainder depends on the type of subclassing
-
- if ($bCustomizeSubclass) {
- $sDeclare .= '$self->[7]={}; $self->_new(); return $self; }'
- . 'sub _p_getSubclassData { $_[0]->[7]; }';
- } else {
- $sDeclare .= 'return $self;}'.
- 'sub replaceProperties {'.
- 'my $h={%{$_[0]->[1]},%{$_[1]}}; $_[0]->[1]=$h;'.$sReplaceMsg.
- '}'.
- 'sub rethrow {' .
- 'my $self=shift;' . $sRethrowMsg .
- 'Exception::Lite::_rethrow($self,"'.$sAddOrOmit.'",@_)' .
- '}';
-
- unless (isExceptionClass($sSuperClass)) {
- $sDeclare .=
- 'sub _getInterface { \'Exception::Lite\' }' .
- 'sub getMessage { $_[0]->[0] };' .
- 'sub getProperty { $_[0]->[1]->{$_[1]} }' .
- 'sub isProperty { exists($_[0]->[1]->{$_[1]})?1:0 }' .
- 'sub getStackTrace { $_[0]->[2] }' .
- 'sub getFrameCount { scalar(@{$_[0]->[2]}); }' .
- 'sub getFile { $_[0]->[2]->[ $_[1]?$_[1]:0 ]->[0] };' .
- 'sub getLine { $_[0]->[2]->[ $_[1]?$_[1]:0 ]->[1] };' .
- 'sub getSubroutine { $_[0]->[2]->[ $_[1]?$_[1]:0 ]->[2] };' .
- 'sub getArgs { $_[0]->[2]->[ $_[1]?$_[1]:0 ]->[3] };' .
- 'sub getPackage {$_[0]->[2]->[-1]->[2] =~ /(\w+)>$/;$1}'.
- 'sub getPid { $_[0]->[3] }' .
- 'sub getTid { $_[0]->[4] }' .
- 'sub getChained { $_[0]->[5] }' .
- 'sub getPropagation { $_[0]->[6]; }' .
- 'use overload '.
- 'q{""} => \&Exception::Lite::_dumpMessage ' .
- ', q{0+} => \&Exception::Lite::_refaddr, fallback=>1;' .
- 'sub PROPAGATE { push @{$_[0]->[6]},[$_[1],$_[2]]; $_[0]}';
- }
- }
- $sDeclare .= 'return 1;';
-
- local $SIG{__WARN__} = sub {
- my ($p,$f,$l) = caller(2);
- my $s=$_[0]; $s =~ s/at \(eval \d+\)\s+line\s+\d+\.//m;
- print STDERR "$s in declareExceptionClass($sClass,...) "
- ."in file $f, line $l\n";
- };
-
- eval $sDeclare or do {
- my ($p,$f,$l) = caller(1);
- print STDERR "Can't create class $sClass at file $f, line $l\n";
- if ($sClass =~ /\w:\w/) {
- print STDERR "Bad class name: "
- ."At least one ':' is not doubled\n";
- } elsif ($sClass !~ /^\w+(?:::\w+)*$/) {
- print STDERR "Bad class name: $sClass\n";
- } else {
- $sDeclare=~s/(sub |use )/\n$1/g; print STDERR "$sDeclare\n";
- }
- };
-
- # this needs to be separate from the eval, otherwise it never
- # ends up in @INC or @ISA, at least in Perl 5.8.8
- $INC{$sPath} = __FILE__;
- eval "\@${sClass}::ISA=qw($sSuperClass);" if $sSuperClass;
-
- return $sClass;
-}
-
-#------------------------------------------------------------------
-
-sub isChainable { return ref($_[0])?1:0; }
-
-#------------------------------------------------------------------
-
-sub isException {
- my ($e, $sClass) = @_;
- my $sRef=ref($e);
- return !defined($sClass)
- ? ($sRef ? isExceptionClass($sRef) : 0)
- : $sClass eq ''
- ? ($sRef eq '' ? 1 : 0)
- : ($sRef eq '')
- ? 0
- : $sRef->isa($sClass)
- ?1:0;
-}
-
-#------------------------------------------------------------------
-
-sub isExceptionClass {
- return defined($_[0]) && $_[0]->can('_getInterface')
- && ($_[0]->_getInterface() eq __PACKAGE__) ? 1 : 0;
-}
-
-#------------------------------------------------------------------
-
-sub onDie {
- my $iStringify = $_[0];
- $SIG{__DIE__} = sub {
- $Exception::Lite::STRINGIFY=$iStringify;
- warn 'Exception::Lite::Any'->new('Unexpected death:'.$_[0])
- unless $^S || isException($_[0]);
- };
-}
-
-#------------------------------------------------------------------
-
-sub onWarn {
- my $iStringify = $_[0];
- $SIG{__WARN__} = sub {
- $Exception::Lite::STRINGIFY=$iStringify;
- print STDERR 'Exception::Lite::Any'->new("Warning: $_[0]");
- };
-}
-
-#==================================================================
-# PRIVATE SUBROUTINES
-#==================================================================
-
-#------------------------------------------------------------------
-
-sub _cacheCall {
- my $iFrame = $_[0];
-
- my @aCaller;
- my $aArgs;
-
- # caller populates @DB::args if called within DB package
- eval {
- # this 2 line wierdness is needed to prevent Module::Build from finding
- # this and adding it to the provides list.
- package
- DB;
-
- #get rid of eval and call to _cacheCall
- @aCaller = caller($iFrame+2);
-
- # mark leading undefined elements as maybe shifted away
- my $iDefined;
- if ($#aCaller < 0) {
- @DB::args=@ARGV;
- }
- $aArgs = [ map {
- defined($_)
- ? do {$iDefined=1;
- "'$_'" . (overload::Method($_,'""')
- ? ' ('.overload::StrVal($_).')':'')}
- : 'undef' . (defined($iDefined)
- ? '':' (maybe shifted away?)')
- } @DB::args];
- };
-
- return $#aCaller < 0 ? \$aArgs : [ @aCaller[0..3], $aArgs ];
-}
-
-#------------------------------------------------------------------
-
-sub _cacheStackTrace {
- my $e=$_[0]; my $st=[];
-
- # set up initial frame
- my $iFrame= $STACK_OFFSET + 1; # call to new
- my $aCall = _cacheCall($iFrame++);
- my ($sPackage, $iFile, $iLine, $sSub, $sArgs) = @$aCall;
- my $iLineFrame=$iFrame;
-
- $aCall = _cacheCall($iFrame++); #context of call to new
- while (ref($aCall) ne 'REF') {
- $sSub = $aCall->[3]; # subroutine containing file,line
- $sArgs = $aCall->[4]; # args used to call $sSub
-
- #print STDERR "debug-2: package=$sPackage file=$iFile line=$iLine"
- # ." sub=$sSub, args=@$sArgs\n";
-
- # in evals we want the line number within the eval, but the
- # name of the sub in which the eval was located. To get this
- # we wait to push on the stack until we get an actual sub name
- # and we avoid overwriting the location information, hence 'ne'
-
- if (!$FILTER || ($sSub ne EVAL)) {
- my $aFrame=[ $iFile, $iLine, $sSub, $sArgs ];
- ($sPackage, $iFile, $iLine) = @$aCall;
- $iLineFrame=$iFrame;
-
- my $sRef=ref($FILTER);
- if ($sRef eq 'CODE') {
- my $x = $FILTER->(@$aFrame, $iFrame, $iLineFrame);
- if (ref($x) eq 'ARRAY') {
- $aFrame=$x;
- } elsif (!$x) {
- $aFrame=undef;
- }
- } elsif (($sRef eq 'ARRAY') && ! _isIgnored($sSub, $FILTER)) {
- $aFrame=undef;
- } elsif (($sRef eq 'Regexp') && !_isIgnored($sSub, [$FILTER])) {
- $aFrame=undef;
- }
- push(@$st, $aFrame) if $aFrame;
- }
-
- $aCall = _cacheCall($iFrame++);
- }
-
- push @$st, [ $iFile, $iLine, "<package: $sPackage>", $$aCall ];
- if ($e) { my $n=$#{$e->[2]}-$#$st;$e->[2]=[@{$e->[2]}[0..$n]]};
- return $st;
-}
-
-#-----------------------------
-
-sub _isIgnored {
- my ($sSub, $aIgnore) = @_;
- foreach my $re (@$aIgnore) { return 1 if $sSub =~ $re; }
- return 0;
-}
-
-#------------------------------------------------------------------
-
-sub _dumpMessage {
- my ($e, $iDepth) = @_;
-
- my $sMsg = $e->getMessage();
- return $sMsg unless $STRINGIFY;
- if (ref($STRINGIFY) eq 'CODE') {
- return $STRINGIFY->($sMsg);
- }
-
- $iDepth = 0 unless defined($iDepth);
- my $sIndent = ' ' x ($TAB*$iDepth);
- $sMsg = "\n${sIndent}Exception! $sMsg";
- return $sMsg if $STRINGIFY == 0;
-
- my ($sThrow, $sReach);
- my $sTab = ' ' x $TAB;
-
- $sIndent.= $sTab;
- if ($STRINGIFY > 2) {
- my $aPropagation = $e->getPropagation();
- for (my $i=$#$aPropagation; $i >= 0; $i--) {
- my ($f,$l) = @{$aPropagation->[$i]};
- $sMsg .= "\n${sIndent}rethrown at file $f, line $l";
- }
- $sMsg .= "\n";
- $sThrow='thrown ';
- $sReach='reached ';
- } else {
- $sThrow='';
- $sReach='';
- }
-
- my $st=$e->getStackTrace();
- my $iTop = scalar @$st;
-
- for (my $iFrame=0; $iFrame<$iTop; $iFrame++) {
- my ($f,$l,$s,$aArgs) = @{$st->[$iFrame]};
-
- if ($iFrame) {
- #2nd and following stack frame
- my $sVia="${sIndent}${sReach}via file $f, line $l";
- my $sLine="$sVia in $s";
- $sMsg .= (length($sLine)>$LINE_LENGTH
- ? "\n$sVia\n$sIndent${sTab}in $s" : "\n$sLine");
- } else {
- # first stack frame
- my $tid=$e->getTid();
- my $sAt="${sIndent}${sThrow}at file $f, line $l";
- my $sLine="$sAt in $s";
- $sMsg .= (length($sLine)>$LINE_LENGTH
- ? "\n$sAt\n$sIndent${sTab}in $s" : "\n$sLine")
- . ", pid=" . $e->getPid() . (defined($tid)?", tid=$tid":'');
-
- return "$sMsg\n" if $STRINGIFY == 1;
- }
-
- if ($STRINGIFY > 3) {
- my $bTop = ($iFrame+1) == $iTop;
- my $sVar= ($bTop && !$iDepth) ? '@ARGV' : '@_';
- my $bMaybeEatenByGetOpt = $bTop && !scalar(@$aArgs)
- && exists($INC{'Getopt/Long.pm'});
-
- my $sVarIndent = "\n${sIndent}" . (' ' x $TAB);
- my $sArgPrefix = "${sVarIndent}".(' ' x length($sVar)).' ';
- if ($bMaybeEatenByGetOpt) {
- $sMsg .= $sArgPrefix . $sVar
- . '() # maybe eaten by Getopt::Long?';
- } else {
- my $sArgs = join($sArgPrefix.',', @$aArgs);
- $sMsg .= "${sVarIndent}$sVar=($sArgs";
- $sMsg .= $sArgs ? "$sArgPrefix)" : ')';
- }
- }
- }
- $sMsg.="\n";
- return $sMsg if $STRINGIFY == 2;
-
- my $eChained = $e->getChained();
- if (defined($eChained)) {
- my $sTrigger = isException($eChained)
- ? _dumpMessage($eChained, $iDepth+1)
- : "\n${sIndent}$eChained\n";
- $sMsg .= "\n${sIndent}Triggered by...$sTrigger";
- }
- return $sMsg;
-}
-
-#------------------------------------------------------------------
-
-# refaddr has a prototype($) so we can't use it directly as an
-# overload operator: it complains about being passed 3 parameters
-# instead of 1.
-sub _refaddr { Scalar::Util::refaddr($_[0]) };
-
-#------------------------------------------------------------------
-
-sub _rethrow {
- my $self = shift; my $sAddOrOmit = shift;
- my ($p,$f,$l)=caller(1);
- $self->PROPAGATE($f,$l);
-
- if (@_%2) {
- warn sprintf('bad parameter list to %s->rethrow(...)'
- .'at file %d, line %d: odd number of elements in property-value '
- .'list, property value has no property name and will be '
- ."discarded (common causes: you have %s string)\n"
- ,$f, $l, $sAddOrOmit);
- shift @_;
- }
- $self->replaceProperties({@_}) if (@_);
- return $self;
-}
-
-#------------------------------------------------------------------
-# Traps warnings and reworks them so that they tell the user how
-# to fix the problem rather than obscurely complain about an
-# invisible sprintf with uninitialized values that seem to come from
-# no where (and make Exception::Lite look like it is broken)
-
-sub _sprintf {
- my $sMsg;
- my $sWarn;
-
- {
- local $SIG{__WARN__} = sub { $sWarn=$_[0] if !defined($sWarn) };
-
- # sprintf has prototype ($@)
- my $sFormat = shift;
- $sMsg = sprintf($sFormat, @_);
- }
-
- if (defined($sWarn)) {
- my $sReason='';
- my ($f, $l, $s) = (caller(1))[1,2,3];
- $s =~ s/::(\w+)\z/->$1/;
- $sWarn =~ s/sprintf/$s/;
- $sWarn =~ s/\s+at\s+[\w\/\.]+\s+line\s+\d+\.\s+\z//;
- if ($sWarn
- =~ m{^Use of uninitialized value in|^Missing argument}) {
- my $p=$s; $p =~ s/->\w+\z//;
- $sReason ="\n Most likely cause: "
- . "Either you are missing property-value pairs needed to"
- . "build the message or your exception class's format"
- . "definition mistakenly has too many placeholders "
- . "(e.g. %s,%d,etc)\n";
- }
- warn "$sWarn called at file $f, line $l$sReason\n";
- }
- return $sMsg;
-}
-
-#------------------------------------------------------------------
-
-sub _shiftProperties {
- my $cl= shift; my $st=shift; my $sAddOrOmit = shift;
- if (@_%2) {
- $"='|';
- warn sprintf('bad parameter list to %s->new(...) at '
- .'file %s, line %d: odd number of elements in property-value '
- .'list, property value has no property name and will be '
- .'discarded (common causes: you have %s string -or- you are '
- ."using a string as a chained exception)\n"
- ,$cl,$st->[0]->[0],$st->[0]->[1], $sAddOrOmit);
- shift @_;
- }
- return {@_};
-}
-
-#==================================================================
-# MODULE INITIALIZATION
-#==================================================================
-
-declareExceptionClass(__PACKAGE__ .'::Any');
-1;
+++ /dev/null
-=head1 NAME
-
-Exception::Lite - light weight exception handling class with smart
-stack tracing, chaining, and localization support.
-
-=head1 SYNOPSIS
-
- # --------------------------------------------------------
- # making this module available to your code
- # --------------------------------------------------------
-
- #Note: there are NO automatic exports
-
- use Exception::Lite qw(declareExceptionClass
- isException
- isChainable
- onDie
- onWarn);
-
- # imports only: declareExceptionClass isException isChainable
- use Exception::Lite qw(:common);
-
- # imports all exportable methods listed above
- use Exception::Lite qw(:all);
-
-
- # --------------------------------------------------------
- # declare an exception class
- # --------------------------------------------------------
-
- # no format rule
- declareExceptionClass($sClass);
- declareExceptionClass($sClass, $sSuperClass);
-
- # with format rule
- declareExceptionClass($sClass, $aFormatRule);
- declareExceptionClass($sClass, $sSuperClass, $aFormatRule);
-
- # with customized subclass
- declareExceptionClass($sClass, $sSuperClass, 1);
- declareExceptionClass($sClass, $aFormatRule, 1);
- declareExceptionClass($sClass, $sSuperClass, $aFormatRule, 1);
-
- # --------------------------------------------------------
- # throw an exception
- # --------------------------------------------------------
-
- die $sClass->new($sMsg, $prop1 => $val1, ...); #no format rule
- die $sClass->new($prop1 => $val1, ...); #has format rule
-
- #-or-
-
- $e = $sClass->new($sMsg, $prop1 => $val1, ...); #no format rule
- $e = $sClass->new($prop1 => $val1, ...); #has format rule
-
- die $e;
-
- # --------------------------------------------------------
- # catch and test an exception
- # --------------------------------------------------------
-
- # Note: for an explanation of why we don't use if ($@)... here,
- # see Catching and Rethrowing exceptions below
-
- eval {
- .... some code that may die here ...
- return 1;
- } or do {
- my $e=$@;
-
- if (isException($e, 'Class1')) {
- ... do something ...
- } elsif (isExcption($e, 'Class2')) {
- ... do something else ...
- }
- };
-
- isException($e); # does $e have the above exception methods?
- isException($e,$sClass) # does $e belong to $sClass or a subclass?
-
- # --------------------------------------------------------
- # getting information about an exception object
- # --------------------------------------------------------
-
- $e->getMessage();
- $e->getProperty($sName);
- $e->isProperty($sName);
- $e->replaceProperties($hOverride);
-
- $e->getPid();
- $e->getPackage();
- $e->getTid();
-
- $e->getStackTrace();
- $e->getFrameCount();
- $e->getFile($i);
- $e->getLine($i);
- $e->getSubroutine($i);
- $e->getArgs($i);
-
- $e->getPropagation();
- $e->getChained();
-
-
- # --------------------------------------------------------
- # rethrowing exceptions
- # --------------------------------------------------------
-
- # using original properties and message
-
- $@=$e; die; # pure Perl way (reset $@ in case wiped out)
-
- die $e->rethrow(); # same thing, but a little less cryptic
-
-
- # overriding original message/properties
-
- die $e->rethrow(path=>$altpath, user=>$nameReplacingId);
-
-
- # --------------------------------------------------------
- # creation of chained exceptions (one triggered by another)
- # (new exception with "memory" of what caused it and stack
- # trace from point of cause to point of capture)
- # --------------------------------------------------------
-
- isChainable($e); # can $e be used as a chained exception?
-
- die $sClass->new($e, $sMsg, $prop1 => $val1, ...);#no format rule
- die $sClass->new($e, $prop1 => $val1, ...); #has format rule
-
- # --------------------------------------------------------
- # print out full message from an exception
- # --------------------------------------------------------
-
- print $e # print works
- warn $e # warn works
- print "$e\n"; # double quotes work
- my $sMsg=$e."\n"; print $sMsg; # . operator works
-
-
- # --------------------------------------------------------
- # global control variables (maybe set on the command line)
- # --------------------------------------------------------
-
- $Exception::Lite::STRINGIFY #set rule for stringifying messages
-
- = 1; # message and file/line where it occured
- = 2; # 1 + what called what (simplified stack trace)
- = 3; # 2 + plus any chained exceptions and where message
- # was caught, if propagated and rethrown
- = 4; # 3 + arguments given to each call in stack trace
- = coderef # custom formatting routine
-
- $Exception::Lite::TAB # set indentation for stringified
- # messages, particularly indentation for
- # call parameters and chained exceptions
-
- $Exception::Lite::FILTER
- = 0 # see stack exactly as Perl does
- = 1 # remove frames added by eval blocks
- = coderef # custom filter - see getStackTrace for details
-
- # --------------------------------------------------------
- # controlling the stack trace from the command line
- # --------------------------------------------------------
-
- perl -mException::Lite=STRINGIFY=1,FILTER=0,TAB=4
- perl -m'Exception::Lite qw(STRINGIFY=1 FILTER=0 TAB=4)'
-
- # --------------------------------------------------------
- # built in exception classes
- # --------------------------------------------------------
-
- # generic wrapper for converting exception strings and other
- # non-Exception::Lite exceptions into exception objects
-
- Exception::Class::Any->new($sMessageText);
-
-To assist in debugging and testing, this package also includes
-two methods that set handlers for die and warn. These methods
-should I<only> be used temporarily during active debugging. They
-should not be used in production software, least they interfere
-with the way other programmers using your module wish to do their
-debugging and testing.
-
- # --------------------------------------------------------
- # force all exceptions/warnings to use Exception::Lite to
- # print out messages and stack traces
- # --------------------------------------------------------
-
- # $stringify is the value for EXCEPTION::Lite::STRINGIFY
- # that you want to use locally to print out messages. It
- # will have no effect outside of the die handler
-
- Exception::Lite::onDie($stringify);
- Exception::Lite::onWarn($stringify);
-
-=head1 DESCRIPTION
-
-The C<Exception::Lite> class provides an easy and very light weight
-way to generate context aware exceptions. It was developed because
-the exception modules on CPAN as of December,2010 were heavy on
-features I didn't care for and did not have the features I most
-needed to test and debug code efficiently.
-
-=head2 Features
-
-This module provides a light weight but powerful exception class
-that
-
-=over
-
-=item *
-
-provides an uncluttered stack trace that clearly shows what
-called what and what exception triggered what other exception.
-It significantly improves on the readability of the stack trace
-dumps provided by C<carp> and other exception modules on
-CPAN (as of 12/2010). For further discussion and a sample, see
-L</More intelligent stack trace>.
-
-=item *
-
-gives the user full control over the amount of debugging
-information displayed when exceptions are thrown.
-
-=item *
-
-permits global changes to the amount of debugging information
-displayed via the command line.
-
-=item *
-
-closely integrates exception classes, messages, and properties
-so that they never get out of sync with one another. This in
-turn eliminates redundant coding and helps reduce the cost of
-writing,validating and maintaining a set of exceptions.
-
-=item *
-
-is easy to retrofit with native language support, even if this
-need appears late in the development process.This makes it
-suitable for use with agile development strategies.
-
-=item *
-
-act like strings in string context but are in fact objects with
-a class hierarchy and properties.They can be thrown and rethrown
-with standard Perl syntax. Like any object, they can be uniquely
-identified in numeric context where they equal their reference
-address (the value returned by C<Scalar::Util::refaddr()>.
-
-=item *
-
-does not interfere with signal handlers or the normal Perl syntax
-and the assumptions of Perl operators.
-
-=item *
-
-can be easily extended and subclassed
-
-=back
-
-=head2 Lightweight how?
-
-Despite these features C<Exception::Lite> maintains its "lite"
-status by
-
-=over
-
-=item *
-
-using only core modules
-
-=item *
-
-generating tiny exception classes (30-45LOC per class).
-
-=item *
-
-eliminating excess baggage by customizing generated classes to
- reflect the actual needs of exception message generation. For
- instance an exception wrapped around a fixed string message would
- omit code for message/property integration and would be little
- more than a string tied to a stack trace and property hash.
-
-=item *
-
-storing only the minimum amount of stack trace data needed to
- generate exception messages and avoiding holding onto references
- from dead stack frames. (Note: some CPAN modules hold onto
- actual variables from each frame, possibly interfering with
- garbage collection).
-
-=item *
-
-doing all its work, including class generation and utilities in
- a single file that is less than half the size of the next smallest
- similarly featured all-core exception class on CPAN (support for
- both properties and a class heirarchy). C<Exception::Lite>
- contains about 400 lines when developer comments are excluded). The
- next smallest all core module is L<Exception::Base|Exception::Base>
- which clocks in at just over 1000 lines after pod and developer
- comments are excluded).
-
-=item *
-
-avoiding a heavy-weight base class. Code shared by
- C<Exception::Lite> classes are stored in function calls that total
- 230 or so lines of code relying on nothing but core modules. This
- is significantly less code than is needed by the two CPAN packages
- with comparable features. The all core
- L<Exception::Base|Exception::Base> class contains 700+ lines of
- code. The base class of L<Exception::Class|Exception::Class> has
- 200 lines of its own but drags in two rather large non-core
- modules as dependencies: L<Devel::StackTrace|Devel::StackTrace>
- L<Class::Data::Inheritable|Class::Data::Inheritable>.
-
-=back
-
-C<Exception::Lite> has more features (chaining, message/property
-integration) but less code due to the following factors:
-
-=over
-
-=item *
-
-working with Perl syntax rather than trying to replace it.
-
-=item *
-
-using a light approach to OOP - exception classes have just enough
-and no more OO features than are needed to be categorized by a
-class, participate in a class heirarchy and to have properties.
-
-=item *
-
-respecting separation of concerns. C<Exception::Lite> focuses
-on the core responsibility of an exception and leaves the bulk of
-syntax creation (e.g. Try/Catch) to specialist modules like
-L<Try::Tiny|Try::Tiny>. Other modules try to double as
-comprehensive providers of exception related syntactic sugar.
-
-=item *
-
-not trying to be the only kind of exception that an application
-uses.
-
-=back
-
-=head1 USAGE
-
-=head2 Defining Exception Classes
-
-C<Exception::Lite> provides two different ways to define messages.
-The first way, without a format rule, lets you compose a freeform
-message for each exception. The second way, with a format rule,
-lets you closely integrate messages and properties and facilitates
-localization of messages for any packages using your software.
-
-=head3 Defining freeform messages
-
-If you want to compose a free form message for each and every
-exception, the class declaration is very simple:
-
- declareExceptionClass($sClass);
- declareExceptionClass($sClass, $sSuperClass);
-
- # with customized subclass
- declareExceptionClass($sClass, $sSuperClass, 1);
-
-C<$sClass> is the name of the exception class.
-
-C<$sSuperClass> is the name of the superclass, if there is one.
-The superclass can be any class created by C<Exception::Lite>. It
-can also be any role class, i.e. a class that has methods but no
-object data of its own.
-
-The downside of this simple exception class is that there is
-absolutely no integration of your messages and any properties that
-you assign to the exception. If you would like to see your property
-values included in the message string,consider using a formatted
-message instead.
-
-=head3 Defining formatted messages
-
-If you wish to include property values in your messages, you need
-to declare a formatted message class. To do this, you define a
-format rule and pass it to the constructor:
-
- $aFormatRule = ['Cannot copy %s to %s', qw(from to) ];
-
- declareExceptionClass($sClass, $aFormatRule);
- declareExceptionClass($sClass, $sSuperClass, $aFormatRule);
-
- # with customized subclass
- declareExceptionClass($sClass, $aFormatRule, 1);
- declareExceptionClass($sClass, $sSuperClass, $aFormatRule, 1);
-
-Format rules are nothing more than a sprintf message string
-followed by a list of properties in the same order as the
-placeholders in the message string. Later on when an exception
-is generated, the values of the properties will replace the
-property names. Some more examples of format rules:
-
-
- $aFormatRule = ['Illegal argument <%s>: %s', qw(arg reason)];
- declareExceptionClass('BadArg', $aFormatRule);
-
- $aFormatRule = ['Cannot open file <%s>> %s', qw(file reason)];
- declareExceptionClass('OpenFailed', $aFormatRule);
-
- $sFormatRule = ['Too few %s, must be at least %s', qw(item min)];
- declareExceptionClass('TooFewWidgets', $aFormatRule);
-
-
-Later on when you throw an exception you can forget about the message
-and set the properties, the class will do the rest of the work:
-
- die BadArg->new(arg=>$sPassword, reason=>'Too few characters');
-
-
- open(my $fh, '>', $sFile)
- or die OpenFailed->new(file=>$sFile, reason=>$!);
-
-And still later when you catch the exception, you have two kinds
-of information for the price of one:
-
- # if you catch BadArg
-
- $e->getProperty('arg') # mine
- $e->getProperty('reason') # too few characters
- $e->getMessage() # Illegal argument <mine>: too few characters
-
-
- # if you catch OpenFailed
-
- $e->getProperty('file') # foo.txt
- $e->getProperty('reason') # path not found
- $e->getMessage() # Cannot open <foo.txt>: path not found
-
-
-=head2 Creating and throwing exceptions
-
-When it comes times to create an exception, you create and
-throw it like this (C<$sClass> is a placeholder for the name of
-your exception class);
-
-
- die $sClass->new($sMsg, prop1 => $val1, ...); #no format rule
- die $sClass->new(prop1 => $val1, ...); #has format rule
-
- #-or-
-
- $e = $sClass->new($sMsg, prop1 => $val1, ...); #no format rule
- $e = $sClass->new(prop1 => $val1, ...); #has format rule
-
- die $e;
-
-
-For example:
-
- # Freeform exceptions (caller composes message, has message
- # parameter ($sMsg) before the list of properties)
-
- close $fh or die UnexpectedException
- ->new("Couldn't close file handle (huh?): $!");
-
- die PropertySettingError("Couldn't set property"
- , prop=>foo, value=>bar);
-
- # Formatted exceptions (no $sMsg parameter)
-
- if (length($sPassword) < 8) {
- die BadArg->new(arg=>$sPassword, reason=>'Too few characters');
- }
-
- open(my $fh, '>', $sFile)
- or die OpenFailed->new(file=>$sFile, reason=>$!);
-
-In the above examples the order of the properties does not matter.
-C<Exception::Lite> is using the property names, not the order of
-the properties to find the right value to plug into the message
-format string.
-
-=head2 Catching and testing exceptions
-
-In Perl there are two basic ways to work with exceptions:
-
-* native Perl syntax
-
-* Java like syntax (requires non-core modules)
-
-=head3 Catching exceptions the Java way
-
-Java uses the following idiom to catch exceptions:
-
- try {
- .... some code here ...
- } catch (SomeExceptionClass e) {
- ... error handling code here ...
- } catch (SomeOtherExceptionClass e) {
- ... error handling code here ...
- } finally {
- ... cleanup code here ...
- }
-
-There are several CPAN modules that provide some sort of syntactic
-sugar so that you can emulate java syntax. The one recommended
-for C<Exception::Lite> users is L<Try::Tiny|Try::Tiny>.
-L<Try::Tiny|Try::Tiny> is an elegant class that concerns itself
-only with making it possible to use java-like syntax. It can be
-used with any sort of exception.
-
-Some of the other CPAN modules that provide java syntax also
-require that you use their exception classes because the java like
-syntax is part of the class definition rather than a pure
-manipulation of Perl syntax.
-
-
-=head3 Catching exceptions the Perl way
-
-The most reliable and fastest way to catch an exception is to use
-C< eval/do >:
-
- eval {
- ...
- return 1;
- } or do {
- # save $@ before using it - it can easily be clobbered
- my $e=$@;
-
- ... do something with the exception ...
-
- warn $e; #use $e as a string
- warn $e->getMessage(); # use $e as an object
- }
-
-
-The C<eval> block ends with C<return 1;> to insure that successful
-completion of the eval block never results in an undefined value.
-In certain cases C<undef> is a valid return value for a statement,
-We don't want to enter the C<do> block for any reason other than
-a thrown exception.
-
-C< eval/do > is both faster and more reliable than the C< eval/if>
-which is commonly promoted in Perl programming tutorials:
-
- # eval ... if
-
- eval {...};
- if ($@) {....}
-
-It is faster because the C<do> block is executed if and only
-if the eval fails. By contrast the C<if> must be evaluated both
-in cases of succes and failure.
-
-C< eval/do > is more reliable because the C<do> block is guaranteed
-to be triggered by any die, even one that accidentally throws undef
-or '' as the "exception". If an exception is thrown within the C<eval>
-block, it will always evaluate to C<undef> therefore triggering the
-C<do> block.
-
-On the other hand we can't guarentee that C<$@> will be defined
-even if an exception is thrown. If C<$@> is C<0>, C<undef>, or an
-empty string, the C<if> block will never be entered. This happens
-more often then many programmers realize. When eval exits the
-C< eval > block, it calls destructors of any C<my> variables. If
-any of those has an C< eval > statement, then the value of C<$@> is
-wiped clean or reset to the exception generated by the destructor.
-
-Within the C<do> block, it is a good idea to save C<$@> immediately
-into a variable before doing any additional work. Any subroutine
-you call might also clobber it. Even built-in commands that don't
-normally set C<$@> can because Perl lets a programmer override
-built-ins with user defined routines and those user define routines
-might set C<$@> even if the built-in does not.
-
-=head3 Testing exceptions
-
-Often when we catch an exception we want to ignore some, rethrow
-others, and in still other cases, fix the problem. Thus we need a
-way to tell what kind of exception we've caught. C<Exception::Lite>
-provides the C<isException> method for this purpose. It can be
-passed any exception, including scalar exceptions:
-
- # true if this exception was generated by Exception::Line
- isException($e);
-
-
- # true if this exception belongs to $sClass. It may be a member
- # of the class or a subclass. C<$sClass> may be any class, not
- # just an Exception::Lite generated class. You can even use this
- # method to test for string (scalar) exceptions:
-
- isException($e,$sClass);
-
- isException($e,'Excption::Class');
- isException($e, 'BadArg');
- isException($e, '');
-
-And here is an example in action. It converts an exception to a
-warning and determines how to do it by checing the class.
-
-
- eval {
- ...
- return 1;
- } or do {
- my $e=$@;
- if (Exception::Lite::isException($e)) {
-
- # get message w/o stack trace, "$e" would produce trace
- warn $e->getMessage();
-
- } elsif (Exception::Lite::isException('Exception::Class') {
-
- # get message w/o stack trace, "$e" would produce trace
- warn $e->message();
-
- } elsif (Exception::Lite::isException($e,'')) {
-
- warn $e;
- }
- }
-
-=head2 Rethrowing exceptions
-
-Perl doesn't have a C<rethrow> statement. To reliably rethrow an
-exception, you must set C<$@> to the original exception (in case it
-has been clobbered during the error handling process) and then call
-C<die> without any arguments.
-
- eval {
- ...
- return 1;
- } or do {
- my $e=$@;
-
- # do some stuff
-
- # rethrow $e
- $@=$e; die;
- }
-
-The above code will cause the exception's C<PROPAGATE> method to
-record the file and line number where the exception is rethrown.
-See C<getLine>, C<getFile>, and C<getPropagation> in the class
-reference below for more information.
-
-As this Perl syntax is not exactly screaming "I'm a rethrow",
-C<Exception::Lite> provides an alternative and hopefully more
-intuitive way of propagating an exception. There is no magic here,
-it just does what perl would do had you used the normal syntax,
-i.e. call the exception's C<PROPAGATE> method.
-
- eval {
- ...
- return 1;
- } or do {
- my $e=$@;
-
- # rethrow $e
- die $e->rethrow();
- }
-
-=head2 Chaining Messages
-
-As an exception moves up the stack, its meaning may change. For
-example, suppose a subroutine throws the message "File not open".
-The immediate caller might be able to use that to try and open
-a different file. On the other hand, if the message gets thrown
-up the stack, the fact that a file failed to open might not
-have any meaning at all. That higher level code only cares that
-the data it needed wasn't available. When it notifies the user,
-it isn't going to say "File not found", but "Can't run market
-report: missing data feed.".
-
-When the meaning of the exception changes, it is normal to throw
-a new exception with a class and message that captures the new
-meaning. However, if this is all we do, we lose the original
-source of the problem.
-
-Enter chaining. Chaining is the process of making one exception
-"know" what other exception caused it. You can create a new
-exception without losing track of the original source of the
-problem.
-
-To chain exceptions is simple: just create a new exception and
-pass the caught exception as the first parameter to C<new>. So
-long as the exception is a non-scalar, it will be interpreted
-as a chained exception and not a property name or message text
-(the normal first parameter of C<new>).
-
-Chaining is efficient, especially if the chained exception is
-another C<Exception::Lite> exception. It does not replicate
-the stack trace. Rather the original stack trace is shorted to
-include only the those fromes frome the time it was created to
-the time it was chained.
-
-Any non-scalar exception can be chained. To test whether or not
-a caught exception is chainable, you can use the method
-C<isChainable>. This method is really nothing more than
-a check to see if the exception is a non-scalar, but it helps
-to make your code more self documenting if you use that method
-rather than C<if (ref($e))>.
-
-If an exception isn't chainable, and you still want to chain
-it, you can wrap the exception in an exception class. You
-can use the built-in C<Exception::Class::Any> or any class of
-your own choosing.
-
- #-----------------------------------------------------
- # define some classes
- #-----------------------------------------------------
-
- # no format rule
- declareExceptionClass('HouseholdDisaster');
-
- # format rule
- declareExceptionClass('ProjectDelay'
- , ['The project was delayed % days', qw(days)]);
-
- #-----------------------------------------------------
- # chain some exceptins
- #-----------------------------------------------------
-
- eval {
- .... some code here ...
- return 1;
- } or do {
- my $e=$@;
- if (Exception::Lite::isChainable($e)) {
- if (Exception::Lite::isException($e, 'FooErr') {
- die 'SomeNoFormatException'->new($e, "Caught a foo");
- } else {
- die 'SomeFormattedException'->new($e, when => 'today');
- }
- } elsif ($e =~ /fire/) {
- die 'Exception::Lite::Any'->new($e);
- die 'SomeFormattedException'->new($e, when => 'today');
- } else {
- # rethrow it since we can't chain it
- $@=$e; die;
- }
- }
-
-=head2 Reading Stack Traces
-
-At its fullest level of detail, a stack trace looks something
-like this:
-
- Exception! Mayhem! and then ...
-
- thrown at file Exception/Lite.t, line 307
- in main::weKnowBetterThanYou, pid=24986, tid=1
- @_=('ARRAY(0x83a8a90)'
- ,'rot, rot, rot'
- ,'Wikerson brothers'
- ,'triculous tripe'
- ,'There will be no more talking to hoos who are not!'
- ,'black bottom birdie'
- ,'from the three billionth flower'
- ,'Mrs Tucanella returns with uncles and cousins'
- ,'sound off! sound off! come make yourself known!'
- ,'Apartment 12J'
- ,'Jo Jo the young lad'
- ,'the whole world was saved by the smallest of all'
- )
- reached via file Exception/Lite.t, line 281
- in main::notAWhatButAWho
- @_=()
- reached via file Exception/Lite.t, line 334 in main::__ANON__
- @_=()
- reached via file Exception/Lite.t, line 335 in <package: main>
- @ARGV=()
-
- Triggered by...
- Exception! Horton hears a hoo!
- rethrown at file Exception/Lite.t, line 315
-
- thrown at file Exception/Lite.t, line 316
- in main::horton, pid=24986, tid=1
- @_=('15th of May'
- ,'Jungle of Nool'
- ,'a small speck of dust on a small clover'
- ,'a person's a person no matter how small'
- )
- reached via file Exception/Lite.t, line 310 in main::hoo
- @_=('Dr Hoovey'
- ,'hoo-hoo scope'
- ,'Mrs Tucanella'
- ,'Uncle Nate'
- )
- reached via file Exception/Lite.t, line 303
- in main::weKnowBetterThanYou
- @_=('ARRAY(0x83a8a90)'
- ,'rot, rot, rot'
- ,'Wikerson brothers'
- ,'triculous tripe'
- ,'There will be no more talking to hoos who are not!'
- ,'black bottom birdie'
- ,'from the three billionth flower'
- ,'Mrs Tucanella returns with uncles and cousins'
- ,'sound off! sound off! come make yourself known!'
- ,'Apartment 12J'
- ,'Jo Jo the young lad'
- ,'the whole world was saved by the smallest of all'
- )
-
-
-=over
-
-=item *
-
-lines begining with "thrown" indicate a line where a new exception
-was thrown. If an exception was chained, there might be multiple
-such lines.
-
-=item *
-
-lines beginning with "reached via" indicate the path travelled
-I<down> to the point where the exception was thrown. This is the
-code that was excuted before the exception was triggered.
-
-=item *
-
-lines beginning with "rethrown at" indicate the path travelled
-I<up> the stack by the exception I<after> it was geenerated. Each
-line indicates a place where the exception was caught and rethrown.
-
-=item *
-
-lines introduced with "Triggered by" are exceptions that were
-chained together. The original exception is the last of the
-triggered exceptions. The original line is the "thrown" line
-for the original exception.
-
-=item *
-
-C<@_> and <C@ARGV> below a line indicates what is left of the
-parameters passed to a method, function or entry point routine.
-In ideal circumstances they are the parameters passed to the
-subroutine mentioned in the line immediately above C<@_>. In
-reality, they can be overwritten or shifted away between the
-point when the subroutine started and the line was reached.
-
-Note: if you use L<Getopt::Long> to process C<@ARGV>, C<@ARGV>
-will be empty reduced to an empty array. If this bothers you, you
-can localize <@ARGV> before calling C<GetOptions>, like this:
-
- my %hARGV;
- {
- local @ARGV = @ARGV;
- GetOptions(\%hARGV,...);
- }
-
-=item *
-
-pid is the process id where the code was running
-
-=item *
-
-tid is the thread id where the code was running
-
-=back
-
-=head1 SPECIAL TOPICS
-
-=head2 Localization of error messages
-
-Rather than treat the error message and properties as entirely
-separate entities, it gives you the option to define a format string
-that will take your property values and insert them automatically
-into your message. Thus when you generate an exception, you can
-specify only the properties and have your message automatically
-generated without any need to repeat the property values in messy
-C<sprintf>'s that clutter up your program.
-
-One can localize from the very beginning when one declares the
-class or later on after the fact if you are dealing with legacy
-software or developing on an agile module and only implementing
-what you need now.
-
-To localize from the get-go:
-
- # myLookupSub returns the arguments to declareException
- # e.g. ('CopyError', [ 'On ne peut pas copier de %s a %s'
- , qw(from to)])
-
- declareExceptionClass( myLookupSub('CopyError', $ENV{LANG}) );
-
-
- # .... later on, exception generation code doesn't need to
- # know or care about the language. it just sets the properties
-
-
- # error message depends on locale:
- # en_US: 'Cannot copy A.txt to B.txt'
- # fr_FR: 'On ne peut pas copier de A.txt a B.txt'
- # de_DE: 'Kann nicht kopieren von A.txt nach B.txt'
-
- die 'CopyError'->new(from => 'A.txt', to => 'B.txt');
-
-
-Another alternative if you wish to localize from the get-go is
-to pass a code reference instead of a format rule array. In this
-case, C<Exception::Lite> will automatically pass the class name
-to the subroutine and retrieve the value returned.
-
-
- # anothherLookupSub has parameters ($sClass) and returns
- # a format array, for example:
- #
- # %LOCALE_FORMAT_HASH = (
- # CopyError => {
- # en_US => ['Cannot copy %s to %s', qw(from to)]
- # ,fr_FR => ['On ne peut pas copier de %s a %s', qw(from to)]
- # ,de_DE => ['Kann nicht kopieren von %s nach %s''
- # , qw(from to)]
- #
- # AddError => ...
- # );
- #
- # sub anotherLookupSub {
- # my ($sClass) = @_;
- # my $sLocale = $ENV{LANG}
- # return $LOCALE_FORMAT_HASH{$sClass}{$sLocale};
- # }
- #
-
- declareExceptionClass('CopyError', &anotherLookupSub);
- declareExceptionClass('AddError', &anotherLookupSub);
-
-
- # error message depends on locale:
- # en_US: 'Cannot copy A.txt to B.txt'
- # fr_FR: 'On ne peut pas copier de A.txt a B.txt'
- # de_DE: 'Kann nicht kopieren von A.txt nach B.txt'
-
- die CopyError->new(from => 'A.txt', to => 'B.txt');
- die AddError->new(path => 'C.txt');
-
-
-If you need to put in localization after the fact, perhaps for a
-new user interface you are developing, the design pattern might
-look like this:
-
- # in the code module you are retrofitting would be an exception
- # that lived in a single language world.
-
- declareExceptionClass('CopyError'
- ['Cannot copy %s to %s', [qw(from to)]);
-
-
- # in your user interface application.
-
- if (isException($e, 'CopyError') && isLocale('fr_FR')) {
- my $sFrom = $e->getProperty('from');
- my $sTo = $e->getProperty('to');
- warn sprintf('On ne peut pas copier de %s a %s', $sFrom,$sTo);
- }
-
-=head2 Controlling verbosity and stack tracing
-
-You don't need to print out the fully verbose stack trace and in
-fact, by default you won't. The default setting, prints out
-only what called what. To make it easier to see what called what,
-it leaves out all of the dumps of C<@_> and C<@ARGV>.
-
-If you want more or less verbosity or even an entirely different
-trace, C<Exception::Lite> is at your sevice. It provides a variety
-of options for controlling the output of the exception:
-
-* Adjusting the level of debugging information when an exception is
- thrown by setting C<$Exception::Lite::STRINGIFY>
- in the program or C<-mException::Lite=STRINGIFY=level> on the
- command line. This can be set to either a verbosity level or to
- an exception stringification routine of your own choosing.
-
-* Control which stack frames are displayed by setting
- C<$Exception::Lite::FILTER>. By default, only calls within named
- and anonymous subroutines are displayed in the stack trace. Perl
- sometimes creates frames for blocks of code within a subroutine.
- These are omitted by default. If you want to see them, you can
- turn filterin off. Alternatively you can set up an entirely
- custon stack filtering rule by assigning a code reference to
- C<$Exception::Lite::FILTER>.
-
-* By default, exceptions store and print a subset of the data
- available for each stack frame. If you would like to display
- richer per-frame information, you can do that too. See below
- for details.
-
-=head3 Verbosity level
-
-The built-in rules for displaying exceptions as strings offer five
-levels of detail.
-
-* 0: Just the error message
-
-* 1: the error message and the file/line number where it occured
- along with pid and tid.
-
-* 2: the error message and the calling sequence from the point where
- the exception was generated to the package or script entry point
- The calling sequence shows only file, line number and the name
- of the subroutine where the exception was generated. It is not
- cluttered with parameters, making it easy to scan.
-
-* 3: similar to 2, except that propagation and chained exceptions
- are also displayed.
-
-* 4: same as 3, except that the state of C<@_> or C<@ARGV> at the
- time the exception was thrown is also displayed. usually this
- is the parameters that were passed in, but it may include several
- leading C<undef> if C<shift> was used to process the parameter
- list.
-
-Here are some samples illustrating different level of debugging
-information and what happens when the filter is turned off
-
- #---------------------------------------------------
- #Sample exception STRINGIFY=0 running on thread 5
- #---------------------------------------------------
-
- Exception! Mayhem! and then ...
-
- #---------------------------------------------------
- #Sample exception STRINGIFY=1 running on thread 5
- #---------------------------------------------------
-
- Exception! Mayhem! and then ...
- at file Exception/Lite.t, line 307 in main::weKnowBetterThanYou, pid=24986, tid=5
-
- #---------------------------------------------------
- #Sample exception STRINGIFY=2 running on thread 4
- #---------------------------------------------------
-
- Exception! Mayhem! and then ...
- at file Exception/Lite.t, line 307 in main::weKnowBetterThanYou, pid=24986, tid=4
- via file Exception/Lite.t, line 281 in main::notAWhatButAWho
- via file Exception/Lite.t, line 373 in main::__ANON__
- via file Exception/Lite.t, line 374 in <package: main>
-
- #---------------------------------------------------
- #Sample exception STRINGIFY=3 running on thread 3
- #---------------------------------------------------
-
- Exception! Mayhem! and then ...
-
- thrown at file Exception/Lite.t, line 307 in main::weKnowBetterThanYou, pid=24986, tid=3
- reached via file Exception/Lite.t, line 281 in main::notAWhatButAWho
- reached via file Exception/Lite.t, line 362 in main::__ANON__
- reached via file Exception/Lite.t, line 363 in <package: main>
-
- Triggered by...
- Exception! Horton hears a hoo!
- rethrown at file Exception/Lite.t, line 315
-
- thrown at file Exception/Lite.t, line 316 in main::horton, pid=24986, tid=3
- reached via file Exception/Lite.t, line 310 in main::hoo
- reached via file Exception/Lite.t, line 303 in main::weKnowBetterThanYou
-
- #---------------------------------------------------
- #Sample exception STRINGIFY=3 running on thread 2
- #FILTER=OFF (see hidden eval frames)
- #---------------------------------------------------
-
- Exception! Mayhem! and then ...
-
- thrown at file Exception/Lite.t, line 307 in main::weKnowBetterThanYou, pid=24986, tid=2
- reached via file Exception/Lite.t, line 281 in main::notAWhatButAWho
- reached via file Exception/Lite.t, line 348 in (eval)
- reached via file Exception/Lite.t, line 348 in main::__ANON__
- reached via file Exception/Lite.t, line 350 in (eval)
- reached via file Exception/Lite.t, line 350 in <package: main>
-
- Triggered by...
- Exception! Horton hears a hoo!
- rethrown at file Exception/Lite.t, line 315
-
- thrown at file Exception/Lite.t, line 316 in main::horton, pid=24986, tid=2
- reached via file Exception/Lite.t, line 310 in (eval)
- reached via file Exception/Lite.t, line 315 in main::hoo
- reached via file Exception/Lite.t, line 303 in (eval)
- reached via file Exception/Lite.t, line 305 in main::weKnowBetterThanYou
-
- #---------------------------------------------------
- #Sample exception STRINGIFY=4 running on thread 1
- #FILTER=ON
- #---------------------------------------------------
-
- Exception! Mayhem! and then ...
-
- thrown at file Exception/Lite.t, line 307 in main::weKnowBetterThanYou, pid=24986, tid=1
- @_=('ARRAY(0x83a8a90)'
- ,'rot, rot, rot'
- ,'Wikerson brothers'
- ,'triculous tripe'
- ,'There will be no more talking to hoos who are not!'
- ,'black bottom birdie'
- ,'from the three billionth flower'
- ,'Mrs Tucanella returns with Wikerson uncles and cousins'
- ,'sound off! sound off! come make yourself known!'
- ,'Apartment 12J'
- ,'Jo Jo the young lad'
- ,'the whole world was saved by the tiny Yopp! of the smallest of all'
- )
- reached via file Exception/Lite.t, line 281 in main::notAWhatButAWho
- @_=()
- reached via file Exception/Lite.t, line 334 in main::__ANON__
- @_=()
- reached via file Exception/Lite.t, line 335 in <package: main>
- @ARGV=()
-
- Triggered by...
- Exception! Horton hears a hoo!
- rethrown at file Exception/Lite.t, line 315
-
- thrown at file Exception/Lite.t, line 316 in main::horton, pid=24986, tid=1
- @_=('15th of May'
- ,'Jungle of Nool'
- ,'a small speck of dust on a small clover'
- ,'a person's a person no matter how small'
- )
- reached via file Exception/Lite.t, line 310 in main::hoo
- @_=('Dr Hoovey'
- ,'hoo-hoo scope'
- ,'Mrs Tucanella'
- ,'Uncle Nate'
- )
- reached via file Exception/Lite.t, line 303 in main::weKnowBetterThanYou
- @_=('ARRAY(0x83a8a90)'
- ,'rot, rot, rot'
- ,'Wikerson brothers'
- ,'triculous tripe'
- ,'There will be no more talking to hoos who are not!'
- ,'black bottom birdie'
- ,'from the three billionth flower'
- ,'Mrs Tucanella returns with Wikerson uncles and cousins'
- ,'sound off! sound off! come make yourself known!'
- ,'Apartment 12J'
- ,'Jo Jo the young lad'
- ,'the whole world was saved by the tiny Yopp! of the smallest of all'
- )
-
-
-=head3 Custom stringification subroutines
-
-The custom stringification subroutine expects one parameter, the
-exception to be stringified. It returns the stringified form of
-the exception. Here is an example of a fairly silly custom
-stringification routine that just prints out the chained messages
-without any stack trace:
-
- $Exception::Lite::STRINGIFY = sub {
- my $e=$_[0]; # exception is sole input parameter
- my $sMsg='';
- while ($e) {
- $sMsg .= $e->getMessage() . "\n";
- $e= $e->getChained();
- }
- return $sMsg; # return string repreentation of message
- };
-
-=head3 Adding information to the stack trace
-
-By default, each frame of the stack trace contains only the file,
-line, containing subroutine, and the state of C<@_> at the time
-C<$sFile>,C<$iLine> was reached.
-
-If your custom subroutine needs more information about the stack
-than C<Exception::Lite> normally provides, you can change the
-contents of the stack trace by assigning a custom filter routine
-to C<$Exception::Lite::FILTER>.
-
-The arguments to this subroutine are:
-
-
- ($iFrame, $sFile, $iLine $sSub, $aArgs, $iSubFrame, $iLineFrame)
-
-where
-
-* C<$sFile> is the file of the current line in that frame
-
-* C<$iLine> is the line number of current line in that frame
-
-* C<$sSub> is the name of the subroutine that contains C<$sFile> and
- C<$iLine>
-
-* C<$aArgs> is an array that holds the stringified value of each
- member of @_ at the time the line at C<$sFile>, C<$sLine> was
- called. Usually, this is the parameters passed into C<$sSub>,
- but may not be.
-
-* C<$iSubFrame> is the stack frame that provided the name of the sub
- and the contents of $aArgs.
-
-* C<$iLineFrame> is the stack frame that provided the file and line
- number for the frame.
-
-Please be aware that each line of the stack trace passed into the
-filter subroutine is a composite drawn from two different frames of
-the Perl stack trace, C<$iSubFrame> and C<$iLineFrame>. This
-composition is necessary because the Perl stack trace contains the
-subroutine that was called at C<$sFile>, C<$iLine> rather than the
-subroutine that I<contains> C<$sFile>,C<$iLine>.
-
-The subroutine returns 0 or any other false value if the stack frame
-should be omitted. It returns to 1 accept the default stack frame as
-is. If it accepts the stack frame but wants to insert extra data
-in the frame, it returns
-C<[$sFile,$iLine,$sSub,$aArgs, $extra1, $extra2, ...]>
-
-The extra data is always placed at the end after the C<$aArgs>
-member.
-
-=head3 Stack trace filtering
-
-To avoid noise, by default, intermediate frames that are associated
-with a block of code within a subroutine other than an anonymous
-sub (e.g. the frame created by C<eval {...} or do {...} >) are
-omitted from the stack trace.
-
-These omissions add to readability for most debugging purposes.
-In most cases one just wants to see which subroutine called which
-other subroutine. Frames created by eval blocks don't provide
-useful information for that purpose and simply clutter up the
-debugging output.
-
-However, there are situations where one either wants more or less
-stack trace filtering. Stack filtering can turned on or off or
-customized by setting C<$Exception::Lite::FILTER> to any of the
-following values:
-
-Normally the filtering rule is set at the start of the program or
-via the command line. It can also be set anywhere in code, with one
-caveat: an error handling block.
-
-=over
-
-=item 0
-
-Turns all filtering off so that you see each and every frame
-in the stack trace.
-
-=item 1
-
-Turns on filtering of eval frames only (default)
-
-=item C<[ regex1, regex2, ... ]>
-
-A list of regexes. If the fully qualified subroutine name matches
-any one of these regular expressions it will be omitted from the
-stack trace.
-
-=item C<$regex>
-
-A single regular expression. If the fully qualified subroutine name
-matches this regular expression, it will be omitted from the stack
-trace.
-
-=item C<$codeReference>
-
-The address of a named or anonymous routine that returns a boolean
-value: true if the frame should be includeed, false if it should be
-omitted. For parameters and return value of this subroutine see
-L</Adding information to the stack trace>.
-
-
-=back
-
-If filtering strategies change and an exception is chained, some of
-its stack frames might be lost during the chaining process if the
-filtering strategy that was in effect when the exception was
-generated changes before it is chained to another exception.
-
-
-=head2 Subclassing
-
-To declare a subclass with custom data and methods, use a three step
-process:
-
-=over
-
-=item *
-
-choose an exception superclass. The choice of superclass follows
-the rule, "like gives birth to like". Exception superclasses that
-have formats must have a superclass that also takes a format.
-Exception subclasses that have no format, must use an exception.
-
-=item *
-
-call C<declareExceptionClass> with its C<$bCustom> parameter set
-to 1
-
-=item *
-
-define a C<_new(...)> method (note the leading underscore _) and
-subclass specific methods in a block that sets the package to
-the subclass package.
-
-=back
-
-
-When the C<$bCustom> flag is set to true, it might be best to think
-of C<declareExceptionClass> as something like C<use base> or
-C<use parent> except that there is no implicit BEGIN block. Like
-both these methods it handles all of the setup details for the
-class so that you can focus on defining methods and functionality.
-
-Wnen C<Exception::Lite> sees the C<$bCustom> flag set to true, it
-assumes you plan on customizing the class. It will set up inhertance,
-and generate all the usual method definition for an C<Exception::Lite>
-class. However, on account of C<$bCustom> being true, it will add a
-few extra things so that and your custom code can play nicely
-together:
-
-=over
-
-=item *
-
-a special hash reserved for your subclsses data. You can get
-access to this hash by calling C<_p_getSubclassData()>. You are
-free to add, change, or remove entries in the hash as needed.
-
-=item *
-
-at the end of its C<new()> method, it calls
-C<< $sClass->_new($self) >>. This is why you must define a C<_new()>
-method in your subclass package block. The C<_new> method is
-responsible for doing additional setup of exception data. Since
-this method is called last it can count on all of the normally
-expected methods and data having been set up, including the
-stack trace and the message generated by the classes format rule
-(if there is one).
-
-=back
-
-For example, suppose we want to define a subclass that accepts
-formats:
-
- #define a superclass that accepts formats
-
- declareExceptionClass('AnyError'
- , ['Unexpected exception: %s','exception']);
-
-
- # declare Exception subclass
-
- declareExceptionClass('TimedException', 'AnyError', $aFormatData,1);
- {
- package TimedException;
-
- sub _new {
- my $self = $_[0]; #exception object created by Exception::Lite
-
- # do additional setup of properties here
- my $timestamp=time();
- my $hMyData = $self->_p_getSubclassData();
- $hMyData->{when} = time();
- }
-
- sub getWhen {
- my $self=$_[0];
- return $self->_p_getSubclassData()->{when};
- }
- }
-
-
-Now suppose we wish to extend our custom class further. There is
-no difference in the way we do things just because it is a subclass
-of a customized C<Exception::Lite> class:
-
- # extend TimedException further so that it
- #
- # - adds two additional bits of data - the effective gid and uid
- # at the time the exception was thrown
- # - overrides getMessage() to include the time, egid, and euid
-
- declareExceptionClass('SecureException', 'TimedException'
- , $aFormatData,1);
- {
- package TimedException;
-
- sub _new {
- my $self = $_[0]; #exception object created by Exception::Lite
-
- # do additional setup of properties here
- my $timestamp=time();
- my $hMyData = $self->_p_getSubclassData();
- $hMyData->{euid} = $>;
- $hMyData->{egid} = $);
- }
-
- sub getEuid {
- my $self=$_[0];
- return $self->_p_getSubclassData()->{euid};
- }
- sub getEgid {
- my $self=$_[0];
- return $self->_p_getSubclassData()->{egid};
- }
- sub getMessage {
- my $self=$_[0];
- my $sMsg = $self->SUPER::getMessage();
- return sprintf("%s at %s, euid=%s, guid=%s", $sMsg
- , $self->getWhen(), $self->getEuid(), $self->getGuid());
- }
- }
-
-=head2 Converting other exceptions into Exception::Lite exceptions
-
-If you decide that you prefer the stack traces of this package, you
-can temporarily force all exceptions to use the C<Exception::Lite>
-stack trace, even those not generated by your own code.
-
-There are two ways to do this:
-
-* production code: chaining/wrapping
-
-* active debugging: die/warn handlers
-
-
-=head3 Wrapping and chaining
-
-The preferred solution for production code is wrapping and/or
-chaining the exception. Any non-string exception, even one
-of a class not created by C<Exception::Lite> can be chained
-to an C<Exception::Lite> exception.
-
-To chain a string exception, you first need to wrap it in
-an exception class. For this purpose you can create a special
-purpose class or use the generic exception class provided by
-the C<Exception::Lite> module: C<Exception::Lite::Any>.
-
-If you don't want to chain the exception, you can also just
-rethrow the wrapped exception, as is. Some examples:
-
- #-----------------------------------------------------
- # define some classes
- #-----------------------------------------------------
-
- # no format rule
- declareExceptionClass('HouseholdRepairNeeded');
-
- # format rule
- declareExceptionClass('ProjectDelay'
- , ['The project was delayed % days', qw(days)]);
-
- #-----------------------------------------------------
- # chain and/or wrap some exceptins
- #-----------------------------------------------------
-
- eval {
- .... some code here ...
- return 1;
- } or do {
-
- my $e=$@;
- if (Exception::Lite::isChainable($e)) {
- if ("$e" =~ /project/) {
-
- # chain formatted message
- die 'ProjectDelay'->new($e, days => 3);
-
- } elsif ("$e" =~ /water pipe exploded/) {
-
- # chain unformatted message
- die 'HouseholdRepairNeeded'->new($e, 'Call the plumber');
-
- }
- } elsif ($e =~ 'repairman') { #exception is a string
-
- # wrapping a scalar exception so it has the stack trace
- # up to this point, but _no_ chaining
- #
- # since the exception is a scalar, the constructor
- # of a no-format exception class will treat the first
- # parameter as a message rather than a chained exception
-
- die 'HouseholdRepairNeeded'->new($e);
-
- } else {
-
- # if we do want to chain a string exception, we need to
- # wrap it first in an exception class:
-
- my $eWrapped = Exception::Lite::Any->new($e);
- die 'HouseholdRepairNeeded'
- ->new($eWrapped, "Call the repair guy");
- }
- }
-
-=head3 Die/Warn Handlers
-
-Die/Warn handlers provide a quick and dirty way to at Exception::Lite
-style stack traces to all warnings and exceptions. However,
-it should ONLY BE USED DURING ACTIVE DEBUGGING. They should never
-be used in production code. Setting these handlers
-can interfere with the debugging style and techiniques of other
-programmers and that is not nice.
-
-However, so long as you are actiely debugging, setting a die or
-warn handler can be quite useful, especially if a third party module
-is generating an exception or warning and you have no idea where it
-is coming from.
-
-To set a die handler, you pass your desired stringify level or
-code reference to C<onDie>:
-
- Exception::Lite::onDie(4);
-
-This is roughly equivalent to:
-
- $SIG{__DIE__} = sub {
- $Exception::Lite::STRINGIFY=4;
- warn 'Exception::Lite::Any'->new('Unexpected death:'.$_[0])
- unless ($^S || Exception::Lite::isException($_[0]));
- };
-
-To set a warning handler, you pass your desired stringify level or
-code reference to C<onWarn>:
-
- Exception::Lite::onWarn(4);
-
-This is roughly equivalent to:
-
- $SIG{__WARN__} = sub {
- $Exception::Lite::STRINGIFY=4;
- print STDERR 'Exception::Lite::Any'->new("Warning: $_[0]");
- };
-
-Typically these handlers are placed at the top of a test script
-like this:
-
- use strict;
- use warnings;
- use Test::More tests => 25;
-
- use Exception::Lite;
- Exception::Lite::onDie(4);
- Exception::Lite::onWarn(3);
-
- ... actual testing code here ...
-
-
-
-=head1 WHY A NEW EXCEPTION CLASS
-
-Aren't there enough already? Well, no. This class differs from
-existing classes in several significant ways beyond "lite"-ness.
-
-=head2 Simplified integration of properties and messages
-
-C<Exception::Lite> simplifies the creation of exceptions by
-minimizing the amount of metadata that needs to be declared for
-each exception and by closely integrating exception properties
-and error messages. Though there are many exception modules
-that let you define message and properties for exceptions, in
-those other modules you have to manually maintain any connection
-between the two either in your code or in a custom subclass.
-
-In L<Exception::Class|Exception::Class>, for example, you have to
-do something like this:
-
- #... at the start of your code ...
- # notice how exception definition and message format
- # string constant are in two different places and need
- # to be manually coordinated by the programmer.
-
- use Exception::Class {
- 'Exception::Copy::Mine' {
- fields => [qw(from to)];
- }
- # ... lots of other exceptions here ...
- }
- my $MSG_COPY='Could not copy A.txt to B.txt";
-
- ... later on when you throw the exception ...
-
- # notice the repetition in the use of exception
- # properties; the repetition is error prone and adds
- # unnecessary extra typing
-
- my $sMsg = sprintf($MSG_COPY, 'A.txt', 'B.txt');
- Exception::Copy::Mine->throw(error => $sMsg
- , from => 'A.txt'
- , to => 'B.txt');
-
-
-C<Exception::Lite> provides a succinct and easy to maintain
-method of declaring those same exceptions
-
- # the declaration puts the message format string and the
- # class declaration together for the programmer, thus
- # resulting in less maintenence work
-
- declareExceptionClass("Exception::Mine::Copy"
- , ["Could not copy %s to %s", qw(from, to) ]);
-
-
- .... some where else in your code ...
-
-
- # there is no need to explicitly call sprintf or
- # repetitively type variable names, nor even remember
- # the order of parameters in the format string or check
- # for undefined values. Both of these will produce
- # the same error message:
- # "Could not copy A.txt to B.txt"
-
- die "Exception::Mine:Copy"->new(from =>'A.txt', to=>'B.txt');
- die "Exception::Mine:Copy"->new(to =>'B.txt', from=>'A.txt');
-
- # and this will politely fill in 'undef' for the
- # property you leave out:
- # "Could not copy A.txt to <undef>"
-
- die "Exception::Mine::Copy"->new(from=>'A.txt');
-
-
-=head2 More intelligent stack trace
-
-The vast majority, if not all, of the exception modules on CPAN
-essentially reproduce Carp's presentation of the stack trace. They
-sometimes provide parameters to control the level of detail, but
-make only minimal efforts, if any, to improve on the quality of
-debugging information.
-
-C<Exception::Lite> improves on the traditional Perl stack trace
-provided by Carp in a number of ways.
-
-=over
-
-=item *
-
-Error messages are shown in full and never truncated (a problem with
- C<Carp::croak>.
-
-=item *
-
-The ability to see a list of what called what without the clutter
- of subroutine parameters.
-
-=item *
-
-The ability to see the context of a line that fails rather than
-a pinhole snapshot of the line itself. Thus one sees
-"at file Foo.pm, line 13 in sub doTheFunkyFunk" rather
- than the contextless stack trace line displayed by nearly every,
- if not all Perl stacktraces, including C<Carp::croak>:
- "called foobar(...) at line 13 in Foo.pm".
- When context rather than line snapshots
- are provided, it is often enough simply to scan the list of what
- called what to see where the error occurred.
-
-=item *
-
-Automatic filtering of stack frames that do not show the actual
-Flow from call to call. Perl internally creates stack frames for
-each eval block. Seeing these in the stack trace make it harder
-to scan the stack trace and see what called what.
-
-=item *
-
-The automatic filtering can be turned off or, alternatively
-customized to include/exclude arbitrary stack frames.
-
-=item *
-
-One can chain together exceptions and then print out what exception
-triggered what other exception. Sometimes what a low level module
-considers important about an exception is not what a higher level
-module considers important. When that happens, the programmer can
-create a new exception with a more relevant error message that
-"remembers" the exception that inspired it. If need be, one can
-see the entire history from origin to destination.
-
-=back
-
-The "traditional" stack trace smushes together all parameters into
-a single long line that is very hard to read. C<Exception::Lite>
-provides a much more readable parametr listing:
-
-=over
-
-=item *
-
-They are displayed one per line so that they can be easily read
- and distinguished one from another
-
-=item *
-
-The string value <i>and</i> the normal object representation is
- shown when an object's string conversion is overloaded. That way
- there can be no confusion about whether the actual object or a
- string was passed in as a parameter.
-
-=item *
-
-It doesn't pretend that these are the parameters passed to the
- subroutine. It is impossible to recreate the actual values in
- the parameter list because the parameter list for any sub is
- just C<@_> and that can be modified when a programmer uses shift
- to process command line arguments. The most Perl can give (through
- its DB module) is the way C<@_> looked at the time the next frame
- in the stack was set up. Instead of positioning the parameters
- as if they were being passed to the subroutine, they are listed
- below the stacktrace line saying "thrown at in line X in
- subroutine Y". In reality, the "parameters" are the value of
- @_ passed to subroutine Y (or @ARGV if this is the entry point),
- or what was left of it when we got to line X.
-
-=item
-
-A visual hint that leading C<undef>s in C<@_> or C<@ARGV> may be
- the result of shifts rather than a heap of C<undef>s passed into
- the subroutine. This lets the programmer focus on the code, not
- on remembering the quirks of Perl stack tracing.
-
-=back
-
-=head1 CLASS REFERENCE
-
-=head2 Class factory methods
-
-=head3 C<declareExceptionClass>
-
- declareExceptionClass($sClass);
- declareExceptionClass($sClass, $sSuperclass);
- declareExceptionClass($sClass, $sSuperclass, $bCustom);
-
- declareExceptionClass($sClass, $aFormatRule);
- declareExceptionClass($sClass, $sSuperclass, $aFormatRule);
- declareExceptionClass($sClass, $sSuperclass, $aFormatRule
- , $bCustom);
-
-Generates a lightweight class definition for an exception class. It
-returns the name of the created class, i.e. $sClass.
-
-=over
-
-=item C<$sClass>
-
-The name of the class (package) to be created. Required.
-
-Any legal Perl package name may be used, so long as it hasn't
-already been used to define an exception or any other class.
-
-=item C<$sSuperclass>
-
-The name of the superclass of C<$sClass>. Optional.
-
-If missing or undefed, C<$sClass> will be be a base class
-whose only superclass is C<UNIVERSAL>, the root class of all Perl
-classes. There is no special "Exception::Base" class that all
-exceptions have to descend from, unless you want it that way
-and choose to define your set of exception classes that way.
-
-=item C<$aFormatRule>
-
-An array reference describing how to use properties to construct
-a message. Optional.
-
-If provided, the format rule is essential the same parameters as
-used by sprintf with one major exception: instead of using actual
-values as arguments, you use property names, like this:
-
- # insert value of 'from' property in place of first %s
- # insert value of 'to' property in place of first %s
-
- [ 'Cannot copy from %s to %s, 'from', 'to' ]
-
-When a format rule is provided, C<Exception::Lite> will auto-generate
-the message from the properties whenever the properties are set or
-changed. Regeneration is a lightweight process that selects property
-values from the hash and sends them to C<sprintf> for formatting.
-
-Later on, when you are creating exceptions, you simply pass in the
-property values. They can be listed in any order and extra properties
-that do not appear in the message string can also be provided. If
-for some reason the value of a property is unknown, you can assign it
-C<undef> and C<Exception::Lite> will politely insert a placeholder
-for the missing value. All of the following are valid:
-
-
- # These all generate "Cannot copy A.txt to B.txt"
-
- $sClass->new(from => 'A.txt', to => 'B.txt');
- $sClass->new(to => 'B.txt', from => 'A.txt');
- $sClass->new(to => 'B.txt', from => 'A.txt'
- , reason => 'source doesn't exist'
- , seriousness => 4
- );
- $sClass->new(reason => 'source doesn't exist'
- , seriousness => 4
- , to => 'B.txt', from => 'A.txt'
- );
-
- # These generate "Cannot copy A.txt to <undef>"
-
- $sClass->new(from => 'A.txt');
- $sClass->new(from => 'A.txt', to => 'B.txt');
-
-=item C<$bCustom>
-
-True if the caller intends to add custom methods and/or a custom
-constructor to the newly declared class. This will force the
-L<Excepton::Lite> to generate some extra methods and data so
-that the subclass can have its own private data area in the class.
-See L</Subclassing> for more information.
-
-
-=back
-
-=head2 Object construction methods
-
-=head3 C<new>
-
- # class configured for no generation from properties
-
- $sClass->new($sMsg);
- $sClass->new($sMsg,$prop1 => $val1, ....);
- $sClass->new($e);
- $sClass->new($e, $sMsg);
- $sClass->new($e, $sMsg,$prop1 => $val1, ....);
-
- # class configured to generate messages from properties
- # using a per-class format string
-
- $sClass->new($prop1 => $val1, ....);
- $sClass->new($e, $prop1 => $val1, ....);
-
-
-Creates a new instance of exception class C<$sClass>. The exception
-may be independent or chained to the exception that triggered it.
-
-=over
-
-=item $e
-
-The exception that logically triggered this new exception.
-May be omitted or left undefined. If defined, the new exception is
-considered chained to C<$e>.
-
-=item $sMsg
-
-The message text, for classes with no autogeneration from properties,
-that is, classes declared like
-
- declareExceptionClass($sClass);
- declareExceptionClass($sClass, $sSuperclass);
-
-In the constructor, C< $sClass->new($e) >>, the message defaults to
-the message of C<$e>. Otherwise the message is required for any
-class that id declared in the above two ways.
-
-=item $prop1 => $val1
-
-The first property name and its associated value. There can be
-as many repetitions of this as there are properties. All types
-of exception classes may have property lists.
-
-=back
-
-If you have chosen to have the message be completely independent
-of properties:
-
- declareExceptionClass('A');
-
- # unchained exception - print output "Hello"
-
- my $e1 = A->new("Hello", importance => 'small', risk => 'large');
- print "$e1\n";
-
- # chained exception - print output "Hello"
-
- my $e2 = A->new($e1,'Goodbye');
-
- $e2->getChained(); # returns $e1
- print $e1->getMessage(); # outputs "Goodbye"
- print $e1; # outputs "Goodbye"
- print $e2->getChained()->getMessage(); # outputs "Hello"
-
-
-If you have chosen to have the message autogenerated from properties
-your call to C<new> will look like this:
-
- $sFormat ='the importance is %s, but the risk is %s';
- declareExceptionClass('B', [ $sFormat, qw(importance risk)]);
-
-
- # unchained exception
-
- my $e1 = B->new(importance=>'small', risk=>'large');
-
- $e1->getChained(); # returns undef
- print "$e1\n"; # outputs "The importance is small, but the
- # risk is large"
-
- # chained exception
-
- $e2 = B->new($e1, importance=>'yink', risk=>'hooboy');
- $e2->getChained(); # returns $e1
- "$e2" # evaluates to "The importance is yink, but
- # the risk is hooboy"
- $e2->getMessage() # same as "$e2"
- $e2->getChained()->getMessage(); # same as "$e1"
-
-
-
-=head2 Object methods
-
-=head3 C<getMessage>
-
- $e->getMessage();
-
-Returns the messsage, i.e. the value displayed when this exception
-is treated as a string. This is the value without line numbers
-stack trace or other information. It includes only the format
-string with the property values inserted.
-
-=head3 C<getProperty>
-
- $e->getProperty($sName);
-
-Returns the property value for the C<$sName> property.
-
-=head3 C<isProperty>
-
- $e->isProperty($sName)
-
-Returns true if the exception has the C<$sName> property, even if
-the value is undefined. (checks existance, not definition).
-
-=head3 C<getPid>
-
- $e->getPid();
-
-Returns the process id of the process where the exception was
-thrown.
-
-=head3 C<getPackage>
-
- $e->getPackage();
-
-Returns the package contining the entry point of the process, i.e.
-the package identified at the top of the stack.
-
-
-=head3 C<getTid>
-
-Returns the thread where the exception was thrown.
-
- $e->getTid();
-
-=head3 C<getStackTrace>
-
- $e->getStackTrace();
-
-Returns the stack trace from the point where the exception was
-thrown (frame 0) to the entry point (frame -1). The stack trace
-is structured as an array of arrays (AoA) where each member array
-represents a single lightweight frame with four data per frame:
-
- [0] the file
- [1] the line number within the file
- [2] the subroutine where the exception was called. File and
- line number will be within this subroutine.
- [3] a comma delimited string containing string representations
- of the values that were stored in @_ at the time the
- exception was thrown. If shift was used to process the
- incoming subroutine arguments, @_ will usually contain
- several leading undefs.
-
-For more information about each component of a stack frame, please
-see the documentation below for the following methods:
-
-* C<getFile> - explains what to expect in [0] of stack frame
-
-* C<getLine> - explains what to expect in [1] of stack frame
-
-* C<getSubroutine> - explains what to expect in [2] of stack frame
-
-* C<getArgs> - explains what to expect in [3] of stack frame
-
-The frame closest to the thrown exception is numbered 0. In fact
-frame 0, stores information about the actual point where the exception
-was thrown.
-
-
-=head3 C<getFrameCount>
-
- $e->getFrameCount();
-
-Returns the number of frames in the stack trace.
-
-=head3 C<getFile>
-
- $e->getFile(0); # gets frame where exception was thrown
- $e->getFile(-1); # gets entry point frame
-
- $e->getFile(); # short hand for $e->getFile(0)
- $e->getFile($i);
-
-Without an argument, this method returns the name of the file where
-the exception was thrown. With an argument it returns the name of
-the file in the C<$i>th frame of the stack trace.
-
-Negative values of C<$i> will be counted from the entry point with
-C<-1> representing the entry point frame, C<-2> representing the
-first call made within the script and so on.
-
-=head3 C<getLine>
-
- $e->getLine(0); # gets frame where exception was thrown
- $e->getLine(-1); # gets entry point frame
-
- $e->getLine(); # short hand for $e->getLine(0)
- $e->getLine($i);
-
-Without an argument, this method returns the line number where the
-exception was thrown. With an argument it returns the line number
-in the C<$i>th frame of the stack trace.
-
-Negative values of C<$i> will be counted from the entry point with
-C<-1> representing the entry point frame, C<-2> representing the
-first call made within the script and so on.
-
-=head3 C<getSubroutine>
-
- $e->getSubroutine(0); # gets frame where exception was thrown
- $e->getSubroutine(-1); # gets entry point frame
-
- $e->getSubroutine(); # short hand for $e->getSubroutine(0)
- $e->getSubroutine($i);
-
-Without an argument, this method returns the name of the subroutine
-where this exception was created via C<new(...)>. With an argument
-it returns the value of the subroutine (or package entry point) in
-the C<$i>th frame of the stack trace.
-
-Negative values of C<$i> will be counted from the entry point with
-C<-1> representing the entry point frame, C<-2> representing the
-first call made within the script and so on.
-
-Note: This is not the same value as returned by C<caller($i)>. C<caller> returns the name of the subroutine that was being called
-at the time of death rather than the containing subroutine.
-
-The subroutine name in array element [2] includes the package name
-so it will be 'MyPackage::Utils::doit' and not just 'doit'. In the
-entry point frame there is, of course, no containing subroutine so
-the value in this string is instead the package name embedded in
-the string "<package: packageName>".
-
-
-=head3 C<getArgs>
-
- $e->getArgs(0); # gets frame where exception was thrown
- $e->getArgs(-1); # gets entry point frame
-
- $e->getArgs(); # short hand for $e->getArgs(0)
- $e->getArgs($i);
-
-Without an argument, this method returns the value of C<@_> (or
-C<@ARGV> for an entry point frame) at the time the exception was
-thrown. With an argument it returns the name of
-the file in the C<$i>th frame of the stack trace.
-
-Negative values of C<$i> will be counted from the entry point with
-C<-1> representing the entry point frame, C<-2> representing the
-first call made within the script and so on.
-
- @_, is the best approximation Perl provides for the arguments
-used to call the subroutine. At the start of the subroutine it does
-in fact reflect the parameters passed in, but frequently programmers
-will process this array with the C<shift> operator which will set
-leading arguments to C<undef>. The debugger does not cache the
-oiginal value of @_, so all you can get from its stack trace is the
-value at the time the exception was thrown, not the value when the
-subroutine was entered.
-
-=head3 C<getPropagation>
-
- $e->getPropagation();
-
-Returns an array reference with one element for each time this
-exception was caught and rethrown using either Perl's own rethrow
-syntax C<$@=$e; die;> or this packages: C<< die->rethrow() >>.
-
-Each element of the array contains a file and line number where
-the exception was rethrown:
-
- [0] file where exception was caught and rethrown
- [1] line number where the exception was caught and rethrown
-
-Note: do not confuse the stack trace with propagation. The stack
-trace is the sequence of calls that were made I<before> the
-exception was thrown. The propagation file and line numbers
-refer to where the exception was caught in an exception handling
-block I<after> the exception was thrown.
-
-Generally, bad data is the reason behind an exception. To see
-where the bad data came from, it is generally more useful to
-look at the stack and see what data was passed down to the point
-where the exception was generated than it is to look at where
-the exception was caught after the fact.
-
-=head3 C<getChained>
-
- my $eChained = $e->getChained();
-
-Returns the chained exception, or undef if the exception is not
-chained. Chained exceptions are created by inserting the triggering
-exception as the first parameter to C<new(...)>.
-
- # class level format
- MyException1->new(reason=>'blahblahblah'); #unchained
- MyException1->new($e, reason=>'blahblahblah'); #chained
-
- # no format string
- MyException1->new('blahblahblah'); #unchained
- MyException1->new($e, reason=>'blahblahblah'); #chained
-
-
-The chained exception can be a reference to any sort of data. It
-does not need to belong to the same class as the new exception,
-nor does it even have to belong to a class generated by
-C<Exception::Lite>. Its only restriction is that it may not be
-a scalar(string, number, ec). To see if an exception
-may be chained you can call C<Exception::Lite::isChainable()>:
-
- if (Exception::Lite::isChainable($e)) {
- die MyException1->new($e, reason=>'blahblahblah');
- } else {
-
- # another alternative for string exceptions
- my $eWrapper=MyWrapperForStringExceptions->new($e);
- die MyException1->new($eWrapper, reason=>'blahblahblah');
-
- # another alternative for string exceptions
- die MyException1->new($eWrapper, reason=>"blahblahblah: $e");
- }
-
-
-=head3 C<rethrow>
-
- $e->rethrow();
- $e->rethrow($prop => $newValue); # format rule
-
- $e->rethrow($newMsg, $p1 => $newValue); # no format rule
- $e->rethrow(undef, $pl => $newValue); # no format rule
- $e->rethrow($sNewMsg); # no format rule
-
-
-Propagates the exception using the method (C<PROPAGATE>) as would
-be called were one to use Perl's native 'rethrow' syntax,
-C<$@=$e; die>.
-
-The first form with no arguments simply rethrows the exception.
-The remain formats let one override property values and/or update
-the message. The argument list is the same as for C<new> except
-that exceptions with no or object level format strings may have
-an undefined message.
-
-For class format exceptions, the message will automatically be
-updated if any of the properties used to construct it have changed.
-
-For exception classes with no formatting, property and message
-changes are independent of each other. If C<$sMsg> is set to C<undef>
-the properties will be changed and the message will be left alone.
-If C<$sMsg> is provided, but no override properties are provided,
-the message will change but the properties will be left untouched.
-
-=head3 C<_p_getSubclassData>
-
-Method for internal use by custom subclasses. This method retrieves
-the data hash reserved for use by custom methods.
-
-
-=head1 SEE ALSO
-
-=head2 Canned test modules
-
-Test modules for making sure your code generates the right
-exceptions. They work with any OOP solution, even C<Exception::Lite>
-
-* L<Test::Exception|Test::Exception> - works with any OOP solution
-
-* L<Test::Exception::LessClever|Test::Exception::LessClever> - works
- with any OOP solution
-
-=head2 Alternate OOP solutions
-
-=head3 L<Exception::Class|Exception::Class>
-
-This module has a fair number of non-core modules. There are several
-extension modules. Most are adapter classes that convert exceptions
-produced by popular CPAN modules into Exception::Class modules:
-
-* L<Exception::Class::Nested|Exception::Class::Nested> - changes
- the syntax for declaring exceptions.
-
-* L<MooseX::Error::Exception::Class|MooseX::Error::Exception::Class>
- - converts Moose exceptions to
- C<Exception::Class> instances.
-
-* L<HTTP::Exception|HTTP::Exception> - wrapper around HTTP exceptions
-
-* L<Mail::Log::Exceptions|Mail::Log::Exceptions> - wrapper around
- Mail::Log exceptions
-
-* L<Exception::Class::DBI|Exception::Class::DBI> - wrapper around
- DBI exceptions
-
-* L<Error::Exception|Error::Exception> - prints out exception
- properties as part of exception stringification.
-
-It takes a heavy approach to OOP, requiring all properties to be
-predeclared. It also stores a lot of information about an exception,
-not all of which is likely to be important to the average user, e.g.
-pid, uid, guid and even the entire stack trace.
-
-There is no support for auto-generating messages based on
-properties.
-
-For an extended discussion of C<Exception::Class>, see
-L<http://www.drdobbs.com/web-development/184416129>.
-
-=head3 L<Exception::Base|Exception::Base>
-
-A light weight version of L<Exception::Class|Exception::Class>.
-Uses only core modules but is fairly new and has no significant
-eco-system of extensions (yet).
-Like C<Exception::Class> properties must be explicitly declared and
-there is no support for autogenerating messages based on properties.
-
-
-=head3 L<Class::Throwable|Class::Throwable>
-
-Another light weight version of L<Exception::Class|Exception::Class>.
-Unlike C<Exception::Class> you can control the amount of system
-state and stack trace information stored at the time an exception
-is generated.
-
-=head2 Syntactic sugar solutions
-
-Syntactical sugar solutions allow java like try/catch blocks to
-replace the more awkward C<die>, C<eval/do>, and C<$@=$e; die>
-pattern. Take care in chosing these methods as they sometimes
-use coding strategies known to cause problems:
-
-=over
-
-=item *
-
-overriding signal handlers - possible interference with your own
-code or third party module use of those handlers.
-
-=item *
-
-source code filtering - can shift line numbers so that the reported
-line number and the actual line number may not be the same.
-
-=item *
-
-closures - there is a apparently a problem with nested closures
-causing memory leaks in some versions of Perl (pre 5.8.4). This
-has been since fixed since 5.8.4.
-
-=back
-
-Modules providing syntactic sugar include:
-
-* L<Try::Catch|Try::Catch>
-
-* L<Try::Tiny|Try::Tiny>
-
-* C<Error|Error>
-
-* L<Exception::Caught|Exception::Caught>
-
-* L<Exception::SEH|Exception::SEH>
-
-* C<Exception|Exception>
-
-* L<Exception::Class::TryCatch|Exception::Class::TryCatch> - extension of L<Exception::Class|Exception::Class>
-
-* L<Exception::Class::TCF|Exception::Class::TCF> - extension of L<Exception::Class|Exception::Class>
-
-
-=head1 EXPORTS
-
-No subroutines are exported by default. See the start of the synopsis
-for optional exports.
-
-
-=head1 AUTHOR
-
-Elizabeth Grace Frank-Backman
-
-=head1 COPYRIGHT
-
-Copyright (c) 2011 Elizabeth Grace Frank-Backman.
-All rights reserved.
-
-=head1 LICENSE
-
-This program is free software; you can redistribute it and/or
-modify it under the same terms as Perl itself.
projects / kivitendo-erp.git / commitdiff