Exception::Class::Base - phpMan

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