view release on metacpan or  search on metacpan

lib/Exception/Stringy.pm  view on Meta::CPAN

By default, the methods are prefixed by C<x> (mnemonic: eXception) but you
can change that by specifying a other C<method_prefix> option at import time
(see L<IMPORT OPTIONS> below)

=head2 $xthrow(), $xrethrow(), $xraise()

  $exception->$xthrow();
  $exception->$xrethrow();
  $exception->$xraise();

Throws the exception.

=head2 $xclass()

  my $class = $exception->$xclass();

Returns the exception class name.

=head2 $xisa()

  if ($exception->$xisa('ExceptionClass')) {... }

Returns true if the class of the given exception C<->isa()> the class given in
parameter. Otherwise, return false.

C<$xisa> is more useful than it seems:

=over

=item *

When applied on an C<Exception::Stringy> exception, it'll properly etract the
exception class and perform the C<isa> call on it.

=item *

When applied on a blessed reference, it'll do the right thing, and work like standard C<isa()>.

=item *

When applied on something else, it won't die, but return false.

=back

So it means that you can safely use C<$exception->$xisa('SomeClass')> whatever
C<$exception> is, no need to do additional testing on it.

=head2 $xfields()

  my @fields = $exception->$xfields();

Returns the list of field names that are in the exception.

=head2 $xfield()

  my $value = $exception->$xfield('field_name');

  $exception->$xfield(field_name => $value);

Set or get the given field. If the value contains one of the following
caracters, then it is transparently base64 encoded and decoded.

The list of forbidden caracters are:

=over

=item C<:>

the semicolon

=item C<|>

the pipe

=item C<\034>

C<\034>, the 0x28 seperator ASCII caracter.

=back

=head2 $xmessage(), $xerror()

  my $text = $exception->$xmessage();
  my $text = $exception->$xerror();

  $exception->$xmessage("Error message");
  $exception->$xerror("Error message");

Set or get the error message of the exception

=head1 GOOD PRACTISES

=head2 exceptions declaration

It's often useful to gather exceptions declarations in a common module. You can
easily do that, because declaring new exceptions is decoupled from C<use>-ing
the module. All you need is to implement a module that uses
C<<Exception::Stringy->declare_exceptions(...)>> one or more times. Other
modules can then use this module. Note however that they also will have to
C<use> C<Exception::Stringy> to have pseudo-methods imported in their
namespaces.

=head2 exceptions naming

It's recommended to use normal class names, with a common prefix, like
C<MyException::Network::Connection>, and to reflect the inheritance
relationship within the name. So C<MyException::Networking::Connection> would
inherit from C<MyException::Networking>. Multiple inheritance or roles aren't
provided by this package.

=head2 mixing with exception objects

Sometimes, you'll have to work with some of the exceptions being
C<Exception::Stringy> exceptions, and some other exceptions being objects
(blessedd references), for example coming from C<Exception::Class>.

In this case, I recommend using C<$xisa> method to handle them appropriately,
as C<$exception->$xisa('SomeClass')> will work on any type of C<$exception>,
and will not die. Instead, it'll always return a true or false value.

=head1 IMPORT OPTIONS