Provided by: libexception-class-perl_1.45-1_all bug

NAME

       Exception::Class::Base - A base class for exception objects

VERSION

       version 1.45

SYNOPSIS

         use Exception::Class 'MyException';

         eval { MyException->throw( error => 'I feel funny.' ) };

         print $@->error;

DESCRIPTION

       This class is the base class for all exceptions created by Exception::Class.  It provides
       a number of methods for getting information about the exception.

METHODS

   MyException->Trace($boolean)
       Each "Exception::Class::Base" subclass can be set individually to include a stacktrace
       when the "as_string" method is called. The default is to not include a stacktrace. Calling
       this method with a value changes this behavior.  It always returns the current value
       (after any change is applied).

       This value is inherited by any subclasses. However, if this value is set for a subclass,
       it will thereafter be independent of the value in "Exception::Class::Base".

       Do not call this on the "Exception::Class::Base" class directly or you'll change it for
       all exception classes that use Exception::Class, including ones created in modules you
       don't control.

       This is a class method, not an object method.

   MyException->UnsafeRefCapture($boolean)
       When a "Devel::StackTrace" object is created, it walks through the stack and stores the
       arguments which were passed to each subroutine on the stack. If any of these arguments are
       references, then that means that the "Devel::StackTrace" ends up increasing the ref count
       of these references, delaying their destruction.

       Since "Exception::Class::Base" uses "Devel::StackTrace" internally, this method provides a
       way to tell "Devel::StackTrace" not to store these references. Instead,
       "Devel::StackTrace" replaces references with their stringified representation.

       This method defaults to false. As with "Trace", it is inherited by subclasses but setting
       it in a subclass makes it independent thereafter.

       Do not call this on the "Exception::Class::Base" class directly or you'll change it for
       all exception classes that use Exception::Class, including ones created in modules you
       don't control.

   MyException->RespectOverload($boolean)
       When a "Devel::StackTrace" object stringifies, by default it ignores stringification
       overloading on any objects being dealt with.

       Since "Exception::Class::Base" uses "Devel::StackTrace" internally, this method provides a
       way to tell "Devel::StackTrace" to respect overloading.

       This method defaults to false. As with "Trace", it is inherited by subclasses but setting
       it in a subclass makes it independent thereafter.

       Do not call this on the "Exception::Class::Base" class directly or you'll change it for
       all exception classes that use Exception::Class, including ones created in modules you
       don't control.

   MyException->MaxArgLength($boolean)
       When a "Devel::StackTrace" object stringifies, by default it displays the full argument
       for each function. This parameter can be used to limit the maximum length of each
       argument.

       Since "Exception::Class::Base" uses "Devel::StackTrace" internally, this method provides a
       way to tell "Devel::StackTrace" to limit the length of arguments.

       This method defaults to 0. As with "Trace", it is inherited by subclasses but setting it
       in a subclass makes it independent thereafter.

       Do not call this on the "Exception::Class::Base" class directly or you'll change it for
       all exception classes that use Exception::Class, including ones created in modules you
       don't control.

   MyException->Fields
       This method returns the extra fields defined for the given class, as a list.

       Do not call this on the "Exception::Class::Base" class directly or you'll change it for
       all exception classes that use Exception::Class, including ones created in modules you
       don't control.

   MyException->throw( $message )
   MyException->throw( message => $message )
   MyException->throw( error => $error )
       This method creates a new object with the given error message. If no error message is
       given, this will be an empty string. It then dies with this object as its argument.

       This method also takes a "show_trace" parameter which indicates whether or not the
       particular exception object being created should show a stacktrace when its "as_string"
       method is called. This overrides the value of "Trace" for this class if it is given.

       The frames included in the trace can be controlled by the "ignore_class" and
       "ignore_package" parameters. These are passed directly to Devel::Stacktrace's constructor.
       See "Devel::Stacktrace" for more details. This class always passes "__PACKAGE__" for
       "ignore_class" and 'Exception::Class' for "ignore_package", in addition to any arguments
       you provide.

       If only a single value is given to the constructor it is assumed to be the message
       parameter.

       Additional keys corresponding to the fields defined for the particular exception subclass
       will also be accepted.

   MyException->new(...)
       This method takes the same parameters as "throw", but instead of dying simply returns a
       new exception object.

       This method is always called when constructing a new exception object via the "throw"
       method.

   MyException->description
       Returns the description for the given "Exception::Class::Base" subclass. The
       "Exception::Class::Base" class's description is "Generic exception" (this may change in
       the future). This is also an object method.

   $exception->rethrow
       Simply dies with the object as its sole argument. It's just syntactic sugar.  This does
       not change any of the object's attribute values.  However, it will cause "caller" to
       report the die as coming from within the "Exception::Class::Base" class rather than where
       rethrow was called.

       Of course, you always have access to the original stacktrace for the exception object.

   $exception->message
   $exception->error
       Returns the error/message associated with the exception.

   $exception->pid
       Returns the pid at the time the exception was thrown.

   $exception->uid
       Returns the real user id at the time the exception was thrown.

   $exception->gid
       Returns the real group id at the time the exception was thrown.

   $exception->euid
       Returns the effective user id at the time the exception was thrown.

   $exception->egid
       Returns the effective group id at the time the exception was thrown.

   $exception->time
       Returns the time in seconds since the epoch at the time the exception was thrown.

   $exception->package
       Returns the package from which the exception was thrown.

   $exception->file
       Returns the file within which the exception was thrown.

   $exception->line
       Returns the line where the exception was thrown.

   $exception->context_hash
       Returns a hash reference with the following keys:

       •   time

       •   pid

       •   uid

       •   euid

       •   gid

       •   egid

   $exception->field_hash
       Returns a hash reference where the keys are any fields defined for the exception class and
       the values are the values associated with the field in the given object.

   $exception->trace
       Returns the trace object associated with the object.

   $exception->show_trace($boolean)
       This method can be used to set whether or not a stack trace is included when the as_string
       method is called or the object is stringified.

   $exception->as_string
       Returns a string form of the error message (something like what you'd expect from die). If
       the class or object is set to show traces then then the full trace is also included. The
       result looks like "Carp::confess".

   $exception->full_message
       Called by the "as_string" method to get the message. By default, this is the same as
       calling the "message" method, but may be overridden by a subclass. See below for details.

LIGHTWEIGHT EXCEPTIONS

       A lightweight exception is one which records no information about its context when it is
       created. This can be achieved by setting "$class->NoContextInfo" to a true value.

       You can make this the default for a class of exceptions by setting it after creating the
       class:

         use Exception::Class (
             'LightWeight',
             'HeavyWeight',
         );

         LightWeight->NoContextInfo(1);

       A lightweight exception does have a stack trace object, nor does it record the time, pid,
       uid, euid, gid, or egid. It only has a message.

OVERLOADING

       "Exception::Class::Base" objects are overloaded so that stringification produces a normal
       error message. This just calls the "$exception->as_string" method described above. This
       means that you can just "print $@" after an "eval" and not worry about whether or not its
       an actual object. It also means an application or module could do this:

         $SIG{__DIE__} = sub { Exception::Class::Base->throw( error => join '', @_ ); };

       and this would probably not break anything (unless someone was expecting a different type
       of exception object from "die").

OVERRIDING THE as_string METHOD

       By default, the "as_string" method simply returns the value "message" or "error" param
       plus a stack trace, if the class's "Trace" method returns a true value or "show_trace" was
       set when creating the exception.

       However, once you add new fields to a subclass, you may want to include those fields in
       the stringified error.

       Inside the "as_string" method, the message (non-stack trace) portion of the error is
       generated by calling the "full_message" method. This can be easily overridden. For
       example:

         sub full_message {
             my $self = shift;

             my $msg = $self->message;

             $msg .= " and foo was " . $self->foo;

             return $msg;
         }

SUPPORT

       Bugs may be submitted at <https://github.com/houseabsolute/Exception-Class/issues>.

       I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".

SOURCE

       The source code repository for Exception-Class can be found at
       <https://github.com/houseabsolute/Exception-Class>.

AUTHOR

       Dave Rolsky <autarch@urth.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2021 by Dave Rolsky.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.

       The full text of the license can be found in the LICENSE file included with this
       distribution.