{ "content": [ { "type": "text", "text": "# Exception::Class::Base (info)\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\nException::Class. It provides a number of methods for getting\ninformation about the exception.\n\n## Sections\n\n- **Exception::Class::BaseUser)Contributed Perl DocumenException::Class::Base(3pm)**\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": "info", "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": "Exception::Class::BaseUser)Contributed Perl DocumenException::Class::Base(3pm)", "lines": 1, "subsections": [] }, { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "VERSION", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 6, "subsections": [] }, { "name": "DESCRIPTION", "lines": 4, "subsections": [] }, { "name": "METHODS", "lines": 196, "subsections": [] }, { "name": "LIGHTWEIGHT EXCEPTIONS", "lines": 17, "subsections": [] }, { "name": "OVERLOADING", "lines": 34, "subsections": [] }, { "name": "SUPPORT", "lines": 5, "subsections": [] }, { "name": "SOURCE", "lines": 3, "subsections": [] }, { "name": "AUTHOR", "lines": 2, "subsections": [] }, { "name": "COPYRIGHT AND LICENSE", "lines": 9, "subsections": [] } ], "sections": { "Exception::Class::BaseUser)Contributed Perl DocumenException::Class::Base(3pm)": { "content": "", "subsections": [] }, "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\nException::Class. It provides a number of methods for getting\ninformation about the exception.\n", "subsections": [] }, "METHODS": { "content": "MyException->Trace($boolean)\nEach \"Exception::Class::Base\" subclass can be set individually to\ninclude a stacktrace when the \"asstring\" method is called. The default\nis to not include a stacktrace. Calling this method with a value\nchanges this behavior. It always returns the current value (after any\nchange is applied).\n\nThis value is inherited by any subclasses. However, if this value is\nset for a subclass, it will thereafter be independent of the value in\n\"Exception::Class::Base\".\n\nDo not call this on the \"Exception::Class::Base\" class directly or\nyou'll change it for all exception classes that use Exception::Class,\nincluding ones created in modules you don't control.\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\nstack and stores the arguments which were passed to each subroutine on\nthe stack. If any of these arguments are references, then that means\nthat the \"Devel::StackTrace\" ends up increasing the ref count of these\nreferences, delaying their destruction.\n\nSince \"Exception::Class::Base\" uses \"Devel::StackTrace\" internally,\nthis method provides a way to tell \"Devel::StackTrace\" not to store\nthese references. Instead, \"Devel::StackTrace\" replaces references with\ntheir stringified representation.\n\nThis method defaults to false. As with \"Trace\", it is inherited by\nsubclasses but setting it in a subclass makes it independent\nthereafter.\n\nDo not call this on the \"Exception::Class::Base\" class directly or\nyou'll change it for all exception classes that use Exception::Class,\nincluding ones created in modules you don't control.\n\nMyException->RespectOverload($boolean)\nWhen a \"Devel::StackTrace\" object stringifies, by default it ignores\nstringification overloading on any objects being dealt with.\n\nSince \"Exception::Class::Base\" uses \"Devel::StackTrace\" internally,\nthis method provides a way to tell \"Devel::StackTrace\" to respect\noverloading.\n\nThis method defaults to false. As with \"Trace\", it is inherited by\nsubclasses but setting it in a subclass makes it independent\nthereafter.\n\nDo not call this on the \"Exception::Class::Base\" class directly or\nyou'll change it for all exception classes that use Exception::Class,\nincluding ones created in modules you don't control.\n\nMyException->MaxArgLength($boolean)\nWhen a \"Devel::StackTrace\" object stringifies, by default it displays\nthe full argument for each function. This parameter can be used to\nlimit the maximum length of each argument.\n\nSince \"Exception::Class::Base\" uses \"Devel::StackTrace\" internally,\nthis method provides a way to tell \"Devel::StackTrace\" to limit the\nlength of arguments.\n\nThis method defaults to 0. As with \"Trace\", it is inherited by\nsubclasses but setting it in a subclass makes it independent\nthereafter.\n\nDo not call this on the \"Exception::Class::Base\" class directly or\nyou'll change it for all exception classes that use Exception::Class,\nincluding ones created in modules you don't control.\n\nMyException->Fields\nThis method returns the extra fields defined for the given class, as a\nlist.\n\nDo not call this on the \"Exception::Class::Base\" class directly or\nyou'll change it for all exception classes that use Exception::Class,\nincluding ones created in modules you don't control.\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\nerror message is given, this will be an empty string. It then dies with\nthis object as its argument.\n\nThis method also takes a \"showtrace\" parameter which indicates whether\nor not the particular exception object being created should show a\nstacktrace when its \"asstring\" method is called. This overrides the\nvalue of \"Trace\" for this class if it is given.\n\nThe frames included in the trace can be controlled by the\n\"ignoreclass\" and \"ignorepackage\" parameters. These are passed\ndirectly to Devel::Stacktrace's constructor. See \"Devel::Stacktrace\"\nfor more details. This class always passes \"PACKAGE\" for\n\"ignoreclass\" and 'Exception::Class' for \"ignorepackage\", in addition\nto any arguments you provide.\n\nIf only a single value is given to the constructor it is assumed to be\nthe message parameter.\n\nAdditional keys corresponding to the fields defined for the particular\nexception subclass will also be accepted.\n\nMyException->new(...)\nThis method takes the same parameters as \"throw\", but instead of dying\nsimply returns a new exception object.\n\nThis method is always called when constructing a new exception object\nvia the \"throw\" method.\n\nMyException->description\nReturns the description for the given \"Exception::Class::Base\"\nsubclass. The \"Exception::Class::Base\" class's description is \"Generic\nexception\" (this may change in the future). This is also an object\nmethod.\n\n$exception->rethrow\nSimply dies with the object as its sole argument. It's just syntactic\nsugar. This does not change any of the object's attribute values.\nHowever, it will cause \"caller\" to report the die as coming from within\nthe \"Exception::Class::Base\" class rather than where rethrow was\ncalled.\n\nOf course, you always have access to the original stacktrace for the\nexception 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\nwas 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\no time\n\no pid\n\no uid\n\no euid\n\no gid\n\no egid\n\n$exception->fieldhash\nReturns a hash reference where the keys are any fields defined for the\nexception class and the values are the values associated with the field\nin 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\nwhen the asstring method is called or the object is stringified.\n\n$exception->asstring\nReturns a string form of the error message (something like what you'd\nexpect from die). If the class or object is set to show traces then\nthen the full trace is also included. The result looks like\n\"Carp::confess\".\n\n$exception->fullmessage\nCalled by the \"asstring\" method to get the message. By default, this\nis the same as calling the \"message\" method, but may be overridden by a\nsubclass. See below for details.\n", "subsections": [] }, "LIGHTWEIGHT EXCEPTIONS": { "content": "A lightweight exception is one which records no information about its\ncontext when it is created. This can be achieved by setting\n\"$class->NoContextInfo\" to a true value.\n\nYou can make this the default for a class of exceptions by setting it\nafter 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\nrecord the time, pid, uid, euid, gid, or egid. It only has a message.\n", "subsections": [] }, "OVERLOADING": { "content": "\"Exception::Class::Base\" objects are overloaded so that stringification\nproduces a normal error message. This just calls the\n\"$exception->asstring\" method described above. This means that you can\njust \"print $@\" after an \"eval\" and not worry about whether or not its\nan actual object. It also 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\nexpecting a different type of exception object from \"die\").\n\nOVERRIDING THE asstring METHOD\nBy default, the \"asstring\" method simply returns the value \"message\"\nor \"error\" param plus a stack trace, if the class's \"Trace\" method\nreturns a true value or \"showtrace\" was set when creating the\nexception.\n\nHowever, once you add new fields to a subclass, you may want to include\nthose fields in the stringified error.\n\nInside the \"asstring\" method, the message (non-stack trace) portion of\nthe error is generated by calling the \"fullmessage\" method. This can\nbe 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.\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\nthe same terms as the Perl 5 programming language system itself.\n\nThe full text of the license can be found in the LICENSE file included\nwith this distribution.\n\nperl v5.32.1 2021-09-12 Exception::Class::Base(3pm)", "subsections": [] } } } }