local-lib5/man/man3/Devel::StackTrace.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "Devel::StackTrace 3"
 127 .TH Devel::StackTrace 3 "2009-07-15" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 Devel::StackTrace \- Stack trace and stack trace frame objects
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 1
 137 \&  use Devel::StackTrace;
 138 \&
 139 \&  my $trace = Devel::StackTrace\->new;
 140 \&
 141 \&  print $trace\->as_string; # like carp
 142 \&
 143 \&  # from top (most recent) of stack to bottom.
 144 \&  while (my $frame = $trace\->next_frame)
 145 \&  {
 146 \&      print "Has args\en" if $frame\->hasargs;
 147 \&  }
 148 \&
 149 \&  # from bottom (least recent) of stack to top.
 150 \&  while (my $frame = $trace\->prev_frame)
 151 \&  {
 152 \&      print "Sub: ", $frame\->subroutine, "\en";
 153 \&  }
 154 .Ve
 155 .SH "DESCRIPTION"
 156 .IX Header "DESCRIPTION"
 157 The Devel::StackTrace module contains two classes, Devel::StackTrace
 158 and Devel::StackTraceFrame.  The goal of this object is to encapsulate
 159 the information that can found through using the \fIcaller()\fR function, as
 160 well as providing a simple interface to this data.
 161 .PP
 162 The Devel::StackTrace object contains a set of Devel::StackTraceFrame
 163 objects, one for each level of the stack.  The frames contain all the
 164 data available from \f(CW\*(C`caller()\*(C'\fR.
 165 .PP
 166 This code was created to support my Exception::Class::Base class
 167 (part of Exception::Class) but may be useful in other contexts.
 168 .SH "'TOP' AND 'BOTTOM' OF THE STACK"
 169 .IX Header "'TOP' AND 'BOTTOM' OF THE STACK"
 170 When describing the methods of the trace object, I use the words 'top'
 171 and 'bottom'.  In this context, the 'top' frame on the stack is the
 172 most recent frame and the 'bottom' is the least recent.
 173 .PP
 174 Here's an example:
 175 .PP
 176 .Vb 1
 177 \&  foo();  # bottom frame is here
 178 \&
 179 \&  sub foo
 180 \&  {
 181 \&     bar();
 182 \&  }
 183 \&
 184 \&  sub bar
 185 \&  {
 186 \&     Devel::StackTrace\->new;  # top frame is here.
 187 \&  }
 188 .Ve
 189 .SH "Devel::StackTrace METHODS"
 190 .IX Header "Devel::StackTrace METHODS"
 191 .IP "\(bu" 4
 192 Devel::StackTrace\->new(%named_params)
 193 .Sp
 194 Returns a new Devel::StackTrace object.
 195 .Sp
 196 Takes the following parameters:
 197 .RS 4
 198 .IP "\(bu" 8
 199 frame_filter => \f(CW$sub\fR
 200 .Sp
 201 By default, Devel::StackTrace will include all stack frames before the
 202 call to its its constructor.
 203 .Sp
 204 However, you may want to filter out some frames with more granularity
 205 than 'ignore_package' or 'ignore_class' allow.
 206 .Sp
 207 You can provide a subroutine which is called with the raw frame data
 208 for each frame. This is a hash reference with two keys, \*(L"caller\*(R", and
 209 \&\*(L"args\*(R", both of which are array references. The \*(L"caller\*(R" key is the
 210 raw data as returned by Perl's \f(CW\*(C`caller()\*(C'\fR function, and the \*(L"args\*(R"
 211 key are the subroutine arguments found in \f(CW@DB::args\fR.
 212 .Sp
 213 The filter should return true if the frame should be included, or
 214 false if it should be skipped.
 215 .IP "\(bu" 8
 216 ignore_package => \f(CW$package_name\fR \s-1OR\s0 \e@package_names
 217 .Sp
 218 Any frames where the package is one of these packages will not be on
 219 the stack.
 220 .IP "\(bu" 8
 221 ignore_class => \f(CW$package_name\fR \s-1OR\s0 \e@package_names
 222 .Sp
 223 Any frames where the package is a subclass of one of these packages
 224 (or is the same package) will not be on the stack.
 225 .Sp
 226 Devel::StackTrace internally adds itself to the 'ignore_package'
 227 parameter, meaning that the Devel::StackTrace package is \fB\s-1ALWAYS\s0\fR
 228 ignored.  However, if you create a subclass of Devel::StackTrace it
 229 will not be ignored.
 230 .IP "\(bu" 8
 231 no_refs => \f(CW$boolean\fR
 232 .Sp
 233 If this parameter is true, then Devel::StackTrace will not store
 234 references internally when generating stacktrace frames.  This lets
 235 your objects go out of scope.
 236 .Sp
 237 Devel::StackTrace replaces any references with their stringified
 238 representation.
 239 .IP "\(bu" 8
 240 respect_overload => \f(CW$boolean\fR
 241 .Sp
 242 By default, Devel::StackTrace will call \f(CW\*(C`overload::AddrRef()\*(C'\fR to get
 243 the underlying string representation of an object, instead of
 244 respecting the object's stringification overloading.  If you would
 245 prefer to see the overloaded representation of objects in stack
 246 traces, then set this parameter to true.
 247 .IP "\(bu" 8
 248 max_arg_length => \f(CW$integer\fR
 249 .Sp
 250 By default, Devel::StackTrace will display the entire argument for
 251 each subroutine call. Setting this parameter causes it to truncate the
 252 argument's string representation if it is longer than this number of
 253 characters.
 254 .RE
 255 .RS 4
 256 .RE
 257 .IP "\(bu" 4
 258 \&\f(CW$trace\fR\->next_frame
 259 .Sp
 260 Returns the next Devel::StackTraceFrame object down on the stack.  If
 261 it hasn't been called before it returns the first frame.  It returns
 262 undef when it reaches the bottom of the stack and then resets its
 263 pointer so the next call to \f(CW\*(C`next_frame\*(C'\fR or \f(CW\*(C`prev_frame\*(C'\fR will work
 264 properly.
 265 .IP "\(bu" 4
 266 \&\f(CW$trace\fR\->prev_frame
 267 .Sp
 268 Returns the next Devel::StackTraceFrame object up on the stack.  If it
 269 hasn't been called before it returns the last frame.  It returns undef
 270 when it reaches the top of the stack and then resets its pointer so
 271 pointer so the next call to \f(CW\*(C`next_frame\*(C'\fR or \f(CW\*(C`prev_frame\*(C'\fR will work
 272 properly.
 273 .IP "\(bu" 4
 274 \&\f(CW$trace\fR\->reset_pointer
 275 .Sp
 276 Resets the pointer so that the next call \f(CW\*(C`next_frame\*(C'\fR or
 277 \&\f(CW\*(C`prev_frame\*(C'\fR will start at the top or bottom of the stack, as
 278 appropriate.
 279 .IP "\(bu" 4
 280 \&\f(CW$trace\fR\->frames
 281 .Sp
 282 Returns a list of Devel::StackTraceFrame objects.  The order they are
 283 returned is from top (most recent) to bottom.
 284 .IP "\(bu" 4
 285 \&\f(CW$trace\fR\->frame ($index)
 286 .Sp
 287 Given an index, returns the relevant frame or undef if there is not
 288 frame at that index.  The index is exactly like a Perl array.  The
 289 first frame is 0 and negative indexes are allowed.
 290 .IP "\(bu" 4
 291 \&\f(CW$trace\fR\->frame_count
 292 .Sp
 293 Returns the number of frames in the trace object.
 294 .IP "\(bu" 4
 295 \&\f(CW$trace\fR\->as_string
 296 .Sp
 297 Calls as_string on each frame from top to bottom, producing output
 298 quite similar to the Carp module's cluck/confess methods.
 299 .SH "Devel::StackTraceFrame METHODS"
 300 .IX Header "Devel::StackTraceFrame METHODS"
 301 See the caller documentation for more information on what these
 302 methods return.
 303 .IP "\(bu" 4
 304 \&\f(CW$frame\fR\->package
 305 .IP "\(bu" 4
 306 \&\f(CW$frame\fR\->filename
 307 .IP "\(bu" 4
 308 \&\f(CW$frame\fR\->line
 309 .IP "\(bu" 4
 310 \&\f(CW$frame\fR\->subroutine
 311 .IP "\(bu" 4
 312 \&\f(CW$frame\fR\->hasargs
 313 .IP "\(bu" 4
 314 \&\f(CW$frame\fR\->wantarray
 315 .IP "\(bu" 4
 316 \&\f(CW$frame\fR\->evaltext
 317 .Sp
 318 Returns undef if the frame was not part of an eval.
 319 .IP "\(bu" 4
 320 \&\f(CW$frame\fR\->is_require
 321 .Sp
 322 Returns undef if the frame was not part of a require.
 323 .IP "\(bu" 4
 324 \&\f(CW$frame\fR\->args
 325 .Sp
 326 Returns the arguments passed to the frame.  Note that any arguments
 327 that are references are returned as references, not copies.
 328 .IP "\(bu" 4
 329 \&\f(CW$frame\fR\->hints
 330 .IP "\(bu" 4
 331 \&\f(CW$frame\fR\->bitmask
 332 .SH "SUPPORT"
 333 .IX Header "SUPPORT"
 334 Please submit bugs to the \s-1CPAN\s0 \s-1RT\s0 system at
 335 http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Devel%3A%3AStackTrace
 336 or via email at bug\-devel\-stacktrace@rt.cpan.org.
 337 .SH "AUTHOR"
 338 .IX Header "AUTHOR"
 339 Dave Rolsky, <autarch@urth.org>
 340 .SH "COPYRIGHT"
 341 .IX Header "COPYRIGHT"
 342 Copyright (c) 2000\-2006 David Rolsky.  All rights reserved.  This
 343 program is free software; you can redistribute it and/or modify it
 344 under the same terms as Perl itself.
 345 .PP
 346 The full text of the license can be found in the \s-1LICENSE\s0 file included
 347 with this module.