{ "content": [ { "type": "text", "text": "# Devel::StackTrace (perldoc)\n\n## NAME\n\nDevel::StackTrace - An object representing a stack trace\n\n## SYNOPSIS\n\nuse Devel::StackTrace;\nmy $trace = Devel::StackTrace->new;\nprint $trace->asstring; # like carp\n# from top (most recent) of stack to bottom.\nwhile ( my $frame = $trace->nextframe ) {\nprint \"Has args\\n\" if $frame->hasargs;\n}\n# from bottom (least recent) of stack to top.\nwhile ( my $frame = $trace->prevframe ) {\nprint \"Sub: \", $frame->subroutine, \"\\n\";\n}\n\n## DESCRIPTION\n\nThe \"Devel::StackTrace\" module contains two classes, \"Devel::StackTrace\" and\nDevel::StackTrace::Frame. These objects encapsulate the information that can retrieved via\nPerl's \"caller\" function, as well as providing a simple interface to this data.\n\n## Sections\n\n- **NAME**\n- **VERSION**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **METHODS**\n- **SUPPORT**\n- **SOURCE**\n- **DONATIONS**\n- **AUTHOR**\n- **CONTRIBUTORS**\n- **COPYRIGHT AND LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Devel::StackTrace", "section": "", "mode": "perldoc", "summary": "Devel::StackTrace - An object representing a stack trace", "synopsis": "use Devel::StackTrace;\nmy $trace = Devel::StackTrace->new;\nprint $trace->asstring; # like carp\n# from top (most recent) of stack to bottom.\nwhile ( my $frame = $trace->nextframe ) {\nprint \"Has args\\n\" if $frame->hasargs;\n}\n# from bottom (least recent) of stack to top.\nwhile ( my $frame = $trace->prevframe ) {\nprint \"Sub: \", $frame->subroutine, \"\\n\";\n}", "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": 16, "subsections": [] }, { "name": "DESCRIPTION", "lines": 27, "subsections": [] }, { "name": "METHODS", "lines": 141, "subsections": [] }, { "name": "SUPPORT", "lines": 4, "subsections": [] }, { "name": "SOURCE", "lines": 3, "subsections": [] }, { "name": "DONATIONS", "lines": 15, "subsections": [] }, { "name": "AUTHOR", "lines": 2, "subsections": [] }, { "name": "CONTRIBUTORS", "lines": 14, "subsections": [] }, { "name": "COPYRIGHT AND LICENSE", "lines": 8, "subsections": [] } ], "sections": { "NAME": { "content": "Devel::StackTrace - An object representing a stack trace\n", "subsections": [] }, "VERSION": { "content": "version 2.04\n", "subsections": [] }, "SYNOPSIS": { "content": "use Devel::StackTrace;\n\nmy $trace = Devel::StackTrace->new;\n\nprint $trace->asstring; # like carp\n\n# from top (most recent) of stack to bottom.\nwhile ( my $frame = $trace->nextframe ) {\nprint \"Has args\\n\" if $frame->hasargs;\n}\n\n# from bottom (least recent) of stack to top.\nwhile ( my $frame = $trace->prevframe ) {\nprint \"Sub: \", $frame->subroutine, \"\\n\";\n}\n", "subsections": [] }, "DESCRIPTION": { "content": "The \"Devel::StackTrace\" module contains two classes, \"Devel::StackTrace\" and\nDevel::StackTrace::Frame. These objects encapsulate the information that can retrieved via\nPerl's \"caller\" function, as well as providing a simple interface to this data.\n\nThe \"Devel::StackTrace\" object contains a set of \"Devel::StackTrace::Frame\" objects, one for\neach level of the stack. The frames contain all the data available from \"caller\".\n\nThis code was created to support my Exception::Class::Base class (part of Exception::Class) but\nmay be useful in other contexts.\n\n'TOP' AND 'BOTTOM' OF THE STACK\nWhen describing the methods of the trace object, I use the words 'top' and 'bottom'. In this\ncontext, the 'top' frame on the stack is the most recent frame and the 'bottom' is the least\nrecent.\n\nHere's an example:\n\nfoo(); # bottom frame is here\n\nsub foo {\nbar();\n}\n\nsub bar {\nDevel::StackTrace->new; # top frame is here.\n}\n", "subsections": [] }, "METHODS": { "content": "This class provide the following methods:\n\nDevel::StackTrace->new(%namedparams)\nReturns a new Devel::StackTrace object.\n\nTakes the following parameters:\n\n* framefilter => $sub\n\nBy default, Devel::StackTrace will include all stack frames before the call to its\nconstructor.\n\nHowever, you may want to filter out some frames with more granularity than 'ignorepackage'\nor 'ignoreclass' allow.\n\nYou can provide a subroutine which is called with the raw frame data for each frame. This is\na hash reference with two keys, \"caller\", and \"args\", both of which are array references.\nThe \"caller\" key is the raw data as returned by Perl's \"caller\" function, and the \"args\" key\nare the subroutine arguments found in @DB::args.\n\nThe filter should return true if the frame should be included, or false if it should be\nskipped.\n\n* filterframesearly => $boolean\n\nIf this parameter is true, \"framefilter\" will be called as soon as the stacktrace is\ncreated, and before refs are stringified (if \"unsaferefcapture\" is not set), rather than\nbeing filtered lazily when Devel::StackTrace::Frame objects are first needed.\n\nThis is useful if you want to filter based on the frame's arguments and want to be able to\nexamine object properties, for example.\n\n* ignorepackage => $packagename OR \\@packagenames\n\nAny frames where the package is one of these packages will not be on the stack.\n\n* ignoreclass => $packagename OR \\@packagenames\n\nAny frames where the package is a subclass of one of these packages (or is the same package)\nwill not be on the stack.\n\nDevel::StackTrace internally adds itself to the 'ignorepackage' parameter, meaning that the\nDevel::StackTrace package is ALWAYS ignored. However, if you create a subclass of\nDevel::StackTrace it will not be ignored.\n\n* skipframes => $integer\n\nThis will cause this number of stack frames to be excluded from top of the stack trace. This\nprevents the frames from being captured at all, and applies before the \"framefilter\",\n\"ignorepackage\", or \"ignoreclass\" options, even with \"filterframesearly\".\n\n* unsaferefcapture => $boolean\n\nIf this parameter is true, then Devel::StackTrace will store references internally when\ngenerating stacktrace frames.\n\nThis option is very dangerous, and should never be used with exception objects. Using this\noption will keep any objects or references alive past their normal lifetime, until the stack\ntrace object goes out of scope. It can keep objects alive even after their \"DESTROY\" sub is\ncalled, resulting it it being called multiple times on the same object.\n\nIf not set, Devel::StackTrace replaces any references with their stringified representation.\n\n* noargs => $boolean\n\nIf this parameter is true, then Devel::StackTrace will not store caller arguments in stack\ntrace frames at all.\n\n* respectoverload => $boolean\n\nBy default, Devel::StackTrace will call \"overload::AddrRef\" to get the underlying string\nrepresentation of an object, instead of respecting the object's stringification overloading.\nIf you would prefer to see the overloaded representation of objects in stack traces, then\nset this parameter to true.\n\n* maxarglength => $integer\n\nBy default, Devel::StackTrace will display the entire argument for each subroutine call.\nSetting this parameter causes truncates each subroutine argument's string representation if\nit is longer than this number of characters.\n\n* message => $string\n\nBy default, Devel::StackTrace will use 'Trace begun' as the message for the first stack\nframe when you call \"asstring\". You can supply an alternative message using this option.\n\n* indent => $boolean\n\nIf this parameter is true, each stack frame after the first will start with a tab character,\njust like \"Carp::confess\".\n\n$trace->nextframe\nReturns the next Devel::StackTrace::Frame object on the stack, going down. If this method hasn't\nbeen called before it returns the first frame. It returns \"undef\" when it reaches the bottom of\nthe stack and then resets its pointer so the next call to \"$trace->nextframe\" or\n\"$trace->prevframe\" will work properly.\n\n$trace->prevframe\nReturns the next Devel::StackTrace::Frame object on the stack, going up. If this method hasn't\nbeen called before it returns the last frame. It returns undef when it reaches the top of the\nstack and then resets its pointer so the next call to \"$trace->nextframe\" or\n\"$trace->prevframe\" will work properly.\n\n$trace->resetpointer\nResets the pointer so that the next call to \"$trace->nextframe\" or \"$trace->prevframe\" will\nstart at the top or bottom of the stack, as appropriate.\n\n$trace->frames\nWhen this method is called with no arguments, it returns a list of Devel::StackTrace::Frame\nobjects. They are returned in order from top (most recent) to bottom.\n\nThis method can also be used to set the object's frames if you pass it a list of\nDevel::StackTrace::Frame objects.\n\nThis is useful if you want to filter the list of frames in ways that are more complex than can\nbe handled by the \"$trace->filterframes\" method:\n\n$stacktrace->frames( myfilter( $stacktrace->frames ) );\n\n$trace->frame($index)\nGiven an index, this method returns the relevant frame, or undef if there is no frame at that\nindex. The index is exactly like a Perl array. The first frame is 0 and negative indexes are\nallowed.\n\n$trace->framecount\nReturns the number of frames in the trace object.\n\n$trace->asstring(\\%p)\nCalls \"$frame->asstring\" on each frame from top to bottom, producing output quite similar to\nthe Carp module's cluck/confess methods.\n\nThe optional \"\\%p\" parameter only has one option. The \"maxarglength\" parameter truncates each\nsubroutine argument's string representation if it is longer than this number of characters.\n\nIf all the frames in a trace are skipped then this just returns the \"message\" passed to the\nconstructor or the string \"Trace begun\".\n\n$trace->message\nReturns the message passed to the constructor. If this wasn't passed then this method returns\n\"undef\".\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 Devel-StackTrace can be found at\n.\n", "subsections": [] }, "DONATIONS": { "content": "If you'd like to thank me for the work I've done on this module, please consider making a\n\"donation\" to me via PayPal. I spend a lot of free time creating free software, and would\nappreciate any support you'd care to offer.\n\nPlease note that I am not suggesting that you must do this in order for me to continue working\non this particular software. I will continue to do so, inasmuch as I have in the past, for as\nlong as it interests me.\n\nSimilarly, a donation made in this way will probably not make me work on this software much\nmore, unless I get so many donations that I can consider working on free software full time\n(let's all have a chuckle at that together).\n\nTo donate, log into PayPal and send money to autarch@urth.org, or use the button at\n.\n", "subsections": [] }, "AUTHOR": { "content": "Dave Rolsky \n", "subsections": [] }, "CONTRIBUTORS": { "content": "* Dagfinn Ilmari Mannsåker \n\n* David Cantrell \n\n* Graham Knop \n\n* Ivan Bessarabov \n\n* Mark Fowler \n\n* Pali \n\n* Ricardo Signes \n", "subsections": [] }, "COPYRIGHT AND LICENSE": { "content": "This software is Copyright (c) 2000 - 2019 by David Rolsky.\n\nThis is free software, licensed under:\n\nThe Artistic License 2.0 (GPL Compatible)\n\nThe full text of the license can be found in the LICENSE file included with this distribution.\n", "subsections": [] } } } }