projekt kivitendo

=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