{ "content": [ { "type": "text", "text": "# Exception::Class::Base (perldoc)\n\n## NAME\n\nException::Class::Base - A base class for exception objects\n\n## SYNOPSIS\n\nuse Exception::Class 'MyException';\neval { MyException->throw( error => 'I feel funny.' ) };\nprint $@->error;\n\n## DESCRIPTION\n\nThis class is the base class for all exceptions created by Exception::Class. It provides a\nnumber of methods for getting information about the exception.\n\n## Sections\n\n- **NAME**\n- **VERSION**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **METHODS**\n- **LIGHTWEIGHT EXCEPTIONS**\n- **OVERLOADING**\n- **SUPPORT**\n- **SOURCE**\n- **AUTHOR**\n- **COPYRIGHT AND LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Exception::Class::Base", "section": "", "mode": "perldoc", "summary": "Exception::Class::Base - A base class for exception objects", "synopsis": "use Exception::Class 'MyException';\neval { MyException->throw( error => 'I feel funny.' ) };\nprint $@->error;", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "VERSION", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 6, "subsections": [] }, { "name": "DESCRIPTION", "lines": 3, "subsections": [] }, { "name": "METHODS", "lines": 171, "subsections": [] }, { "name": "LIGHTWEIGHT EXCEPTIONS", "lines": 15, "subsections": [] }, { "name": "OVERLOADING", "lines": 31, "subsections": [] }, { "name": "SUPPORT", "lines": 4, "subsections": [] }, { "name": "SOURCE", "lines": 3, "subsections": [] }, { "name": "AUTHOR", "lines": 2, "subsections": [] }, { "name": "COPYRIGHT AND LICENSE", "lines": 7, "subsections": [] } ], "sections": { "NAME": { "content": "Exception::Class::Base - A base class for exception objects\n", "subsections": [] }, "VERSION": { "content": "version 1.45\n", "subsections": [] }, "SYNOPSIS": { "content": "use Exception::Class 'MyException';\n\neval { MyException->throw( error => 'I feel funny.' ) };\n\nprint $@->error;\n", "subsections": [] }, "DESCRIPTION": { "content": "This class is the base class for all exceptions created by Exception::Class. It provides a\nnumber of methods for getting information about the exception.\n", "subsections": [] }, "METHODS": { "content": "MyException->Trace($boolean)\nEach \"Exception::Class::Base\" subclass can be set individually to include a stacktrace when the\n\"asstring\" method is called. The default is to not include a stacktrace. Calling this method\nwith a value changes this behavior. It always returns the current value (after any change is\napplied).\n\nThis value is inherited by any subclasses. However, if this value is set for a subclass, it will\nthereafter be independent of the value in \"Exception::Class::Base\".\n\nDo not call this on the \"Exception::Class::Base\" class directly or you'll change it for all\nexception classes that use Exception::Class, including ones created in modules you don't\ncontrol.\n\nThis is a class method, not an object method.\n\nMyException->UnsafeRefCapture($boolean)\nWhen a \"Devel::StackTrace\" object is created, it walks through the stack and stores the\narguments which were passed to each subroutine on the stack. If any of these arguments are\nreferences, then that means that the \"Devel::StackTrace\" ends up increasing the ref count of\nthese references, delaying their destruction.\n\nSince \"Exception::Class::Base\" uses \"Devel::StackTrace\" internally, this method provides a way\nto tell \"Devel::StackTrace\" not to store these references. Instead, \"Devel::StackTrace\" replaces\nreferences with their stringified representation.\n\nThis method defaults to false. As with \"Trace\", it is inherited by subclasses but setting it in\na subclass makes it independent thereafter.\n\nDo not call this on the \"Exception::Class::Base\" class directly or you'll change it for all\nexception classes that use Exception::Class, including ones created in modules you don't\ncontrol.\n\nMyException->RespectOverload($boolean)\nWhen a \"Devel::StackTrace\" object stringifies, by default it ignores stringification overloading\non any objects being dealt with.\n\nSince \"Exception::Class::Base\" uses \"Devel::StackTrace\" internally, this method provides a way\nto tell \"Devel::StackTrace\" to respect overloading.\n\nThis method defaults to false. As with \"Trace\", it is inherited by subclasses but setting it in\na subclass makes it independent thereafter.\n\nDo not call this on the \"Exception::Class::Base\" class directly or you'll change it for all\nexception classes that use Exception::Class, including ones created in modules you don't\ncontrol.\n\nMyException->MaxArgLength($boolean)\nWhen a \"Devel::StackTrace\" object stringifies, by default it displays the full argument for each\nfunction. This parameter can be used to limit the maximum length of each argument.\n\nSince \"Exception::Class::Base\" uses \"Devel::StackTrace\" internally, this method provides a way\nto tell \"Devel::StackTrace\" to limit the length of arguments.\n\nThis method defaults to 0. As with \"Trace\", it is inherited by subclasses but setting it in a\nsubclass makes it independent thereafter.\n\nDo not call this on the \"Exception::Class::Base\" class directly or you'll change it for all\nexception classes that use Exception::Class, including ones created in modules you don't\ncontrol.\n\nMyException->Fields\nThis method returns the extra fields defined for the given class, as a list.\n\nDo not call this on the \"Exception::Class::Base\" class directly or you'll change it for all\nexception classes that use Exception::Class, including ones created in modules you don't\ncontrol.\n\nMyException->throw( $message )\nMyException->throw( message => $message )\nMyException->throw( error => $error )\nThis method creates a new object with the given error message. If no error message is given,\nthis will be an empty string. It then dies with this object as its argument.\n\nThis method also takes a \"showtrace\" parameter which indicates whether or not the particular\nexception object being created should show a stacktrace when its \"asstring\" method is called.\nThis overrides the value of \"Trace\" for this class if it is given.\n\nThe frames included in the trace can be controlled by the \"ignoreclass\" and \"ignorepackage\"\nparameters. These are passed directly to Devel::Stacktrace's constructor. See\n\"Devel::Stacktrace\" for more details. This class always passes \"PACKAGE\" for \"ignoreclass\"\nand 'Exception::Class' for \"ignorepackage\", in addition to any arguments you provide.\n\nIf only a single value is given to the constructor it is assumed to be the message parameter.\n\nAdditional keys corresponding to the fields defined for the particular exception subclass will\nalso be accepted.\n\nMyException->new(...)\nThis method takes the same parameters as \"throw\", but instead of dying simply returns a new\nexception object.\n\nThis method is always called when constructing a new exception object via the \"throw\" method.\n\nMyException->description\nReturns the description for the given \"Exception::Class::Base\" subclass. The\n\"Exception::Class::Base\" class's description is \"Generic exception\" (this may change in the\nfuture). This is also an object method.\n\n$exception->rethrow\nSimply dies with the object as its sole argument. It's just syntactic sugar. This does not\nchange any of the object's attribute values. However, it will cause \"caller\" to report the die\nas coming from within the \"Exception::Class::Base\" class rather than where rethrow was called.\n\nOf course, you always have access to the original stacktrace for the exception object.\n\n$exception->message\n$exception->error\nReturns the error/message associated with the exception.\n\n$exception->pid\nReturns the pid at the time the exception was thrown.\n\n$exception->uid\nReturns the real user id at the time the exception was thrown.\n\n$exception->gid\nReturns the real group id at the time the exception was thrown.\n\n$exception->euid\nReturns the effective user id at the time the exception was thrown.\n\n$exception->egid\nReturns the effective group id at the time the exception was thrown.\n\n$exception->time\nReturns the time in seconds since the epoch at the time the exception was thrown.\n\n$exception->package\nReturns the package from which the exception was thrown.\n\n$exception->file\nReturns the file within which the exception was thrown.\n\n$exception->line\nReturns the line where the exception was thrown.\n\n$exception->contexthash\nReturns a hash reference with the following keys:\n\n* time\n\n* pid\n\n* uid\n\n* euid\n\n* gid\n\n* egid\n\n$exception->fieldhash\nReturns a hash reference where the keys are any fields defined for the exception class and the\nvalues are the values associated with the field in the given object.\n\n$exception->trace\nReturns the trace object associated with the object.\n\n$exception->showtrace($boolean)\nThis method can be used to set whether or not a stack trace is included when the asstring\nmethod is called or the object is stringified.\n\n$exception->asstring\nReturns a string form of the error message (something like what you'd expect from die). If the\nclass or object is set to show traces then then the full trace is also included. The result\nlooks like \"Carp::confess\".\n\n$exception->fullmessage\nCalled by the \"asstring\" method to get the message. By default, this is the same as calling the\n\"message\" method, but may be overridden by a subclass. See below for details.\n", "subsections": [] }, "LIGHTWEIGHT EXCEPTIONS": { "content": "A lightweight exception is one which records no information about its context when it is\ncreated. This can be achieved by setting \"$class->NoContextInfo\" to a true value.\n\nYou can make this the default for a class of exceptions by setting it after creating the class:\n\nuse Exception::Class (\n'LightWeight',\n'HeavyWeight',\n);\n\nLightWeight->NoContextInfo(1);\n\nA lightweight exception does have a stack trace object, nor does it record the time, pid, uid,\neuid, gid, or egid. It only has a message.\n", "subsections": [] }, "OVERLOADING": { "content": "\"Exception::Class::Base\" objects are overloaded so that stringification produces a normal error\nmessage. This just calls the \"$exception->asstring\" method described above. This means that you\ncan just \"print $@\" after an \"eval\" and not worry about whether or not its an actual object. It\nalso means an application or module could do this:\n\n$SIG{DIE} = sub { Exception::Class::Base->throw( error => join '', @ ); };\n\nand this would probably not break anything (unless someone was expecting a different type of\nexception object from \"die\").\n\nOVERRIDING THE asstring METHOD\nBy default, the \"asstring\" method simply returns the value \"message\" or \"error\" param plus a\nstack trace, if the class's \"Trace\" method returns a true value or \"showtrace\" was set when\ncreating the exception.\n\nHowever, once you add new fields to a subclass, you may want to include those fields in the\nstringified error.\n\nInside the \"asstring\" method, the message (non-stack trace) portion of the error is generated\nby calling the \"fullmessage\" method. This can be easily overridden. For example:\n\nsub fullmessage {\nmy $self = shift;\n\nmy $msg = $self->message;\n\n$msg .= \" and foo was \" . $self->foo;\n\nreturn $msg;\n}\n", "subsections": [] }, "SUPPORT": { "content": "Bugs may be submitted at .\n\nI am also usually active on IRC as 'autarch' on \"irc://irc.perl.org\".\n", "subsections": [] }, "SOURCE": { "content": "The source code repository for Exception-Class can be found at\n.\n", "subsections": [] }, "AUTHOR": { "content": "Dave Rolsky \n", "subsections": [] }, "COPYRIGHT AND LICENSE": { "content": "This software is copyright (c) 2021 by Dave Rolsky.\n\nThis is free software; you can redistribute it and/or modify it under the same terms as the Perl\n5 programming language system itself.\n\nThe full text of the license can be found in the LICENSE file included with this distribution.\n", "subsections": [] } } } }