NAME

Devel::Chitin::Stack - An object representing the current execution stack

SYNOPSIS

  # Get the stack
  my $stack = Devel::Chitin::Stack->new();
  my $depth = $stack->depth();

  # Get one particular stack frame
  my $frame = $stack->frame(3);

  # Iterate through the frames from most recent to oldest
  my $iter = $stack->iterator();
  while ($frame = $iter->()) {
      print "Level "        . $frame->level
          . " stopped in "  . $frame->subname
          . " of package "  . $frame->package . "\n";
  }

DESCTIPTION

The Stack object represents the current execution stack in the debugged program. It encapsulates the information from the caller() function, but differs from the raw caller data in that the stack frame locations reflect the currently executing line in each frame. The difference is subtle, but tailored for what a debugger is likely interested in.

The Stack object is composed of several Devel::Chitin::StackFrame objects, one for each call frame.

"TOP" AND "BOTTOM" OF THE STACK

The "top" of the stack refers to the most recent call frame in the debugged program. The "bottom" of the stack is the oldest frame, usually the main program not part of any function call.

For example:

  foo();                # bottom is here, frame 2

  sub foo {
      my @a = bar();    # Frame 1
  }

  sub bar {
      $answer = 1 + 2;  # <-- debugger is stopped here, frame 0
  }

If the debugger is stopped before executing the indicated line, the top of the stack would report line 8 in subroutine main::bar in array context.

The call frame for the main program will look like this: 'hasargs' 1 subroutine main::MAIN package main args @ARGV as it looks in a BEGIN block when the program starts wantarray undef

CONSTRUCTOR

  my $stack = Devel::Chitin::Stack->new();

Returns an instance of Devel::Chitin::stack. The call frames it contains does not include any stack frames within the debugger.

METHODS

$stack->depth()

Returns the number of stack frames in the call stack

$stack->frame($i)

Return the $i-th call frame. 0 is the top of the stack.

$stack->frames()

Return a list of all the call frames.

$stack->iterator()

Returns a coderef to iterate through the call frames. The top of the stack will be the first frame returned. After the bottom frame is returned, the iterator will return undef.

$stack->as_string()

Returns a string representation of the call stack. Useful for showing the user.

StackFrame METHODS

These methods may be called on Devel::Chitin::StackFrame instances:

package

The package this frame is in

filename

The filename this frame is in. For string evals, this will be a string like "(eval 23)[/some/file/path:125]"

line

The line within the file for this frame.

subroutine

The full name of the subroutine for this frame. It will include the package. For the main program's stack frame, subroutine will be "main::MAIN".

For an eval frame, subroutine will be "(eval)"

callsite

If the optional module Devel::Callsite is installed, this will be the opcode address. callsite for the bottom-level stack frame will always be undef.

hasargs

True if this frame has its own instance of @_. In practice, this will be 0 for eval frames, empty string for subroutines called as &subname;, and true otherwise.

wantarray

The wantarray context for this frame. True if in array context, defined but false for scalar context, and undef for void context. Even though perls before 5.12 returned numeric 0 for scalar context, it is normalized to an empty string.

evaltext

For an eval frame, and it was a string eval, this will be the string that is eval-ed. Non-string eval and other frames will have the value undef.

is_require

For an eval frame, this will be true if the frame is part of a "require" or "use".

evalfile

For a string eval frame, this is the file name the original string appeared in. Other frames have the value undef.

evalline

For a string eval frame, this is the line the original string appeared in. Other frames have the value undef.

hints

The hints value returned be caller for this frame

bitmask

The bitmask value returned be caller for this frame

subname

The subroutine name without the package name prepended to it.

autoload

If this call frame was entered because it was handled by an AUTOLOAD function, the 'autoload' attribute will be the function name that was actually called. The value is unreliable if called outside of the debugger system.

level

The number indicating how deep this call frame actually is. This number is not relative to the program being debugged, and so reflects the real number of frames between the caller and the bottom of the stack, including any frames within the debugger.

serial

Each instance of a subroutine call gets a unique identifier as an integer, including the initial frame for MAIN.

eval frames also get serial numbers that are distinct between different function call frames. eval frames within the same function call frame on the same line (such as inside a loop) will, unfortunately, have the same serial number. This bug will hopefully be fixed in the future.

SEE ALSO

Devel::Chitin, Devel::StackTrace

AUTHOR

Anthony Brummett <brummett@cpan.org>

COPYRIGHT

Copyright 2014, Anthony Brummett. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.