Exception::Class::Base man page on Mandriva

Man page or keyword search:  
man Server   17060 pages
apropos Keyword Search (all sections)
Output format
Mandriva logo
[printable version]

Exception::Class::BaseUser Contributed Perl DocumentaException::Class::Base(3)

NAME
       Exception::Class::Base - Base class for exception classes created by
       Exception::Class

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 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->NoRefs($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 refcount 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 true.  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 an
       array.

       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.

       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->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;
	 }

AUTHOR
       Dave Rolsky, >autarch@urth.org<

COPYRIGHT
       Copyright (c) 2000-2009 David Rolsky.  All rights reserved.  This
       program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

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

perl v5.10.1			  2010-03-20	     Exception::Class::Base(3)
[top]

List of man pages available for Mandriva

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net