class CallFrame

Capturing current frame state

class CallFrame {}

There's no way to instantiate a CallFrame. Instead, it is captured from the current state of a program using the callframe subroutine.

my $frame = callframe;
say "The above line of code ran at {$frame.file}:{$frame.line}.";

With no arguments the callframe will give you frame information for the line calling callframe. The file and line annotations will be identical to those in $?FILE and $?LINE.

You may, however, pass a number to callframe to specify a different frame level. The current frame is level 0 (though level of the frame may be different, see level for more information). A positive number will move upward through the levels of frame. A negative number will move downward into the callframe method and class itself at the point at which they are running to construct this information for you.

The frames themselves do not necessarily match to method or subroutine calls. Perl constructs a frames for blocks and such as well, so if you need a callframe for a particular method call, do not assume it is a fixed number of levels up.

Each frame stores annotations, including the file and line annotations, which have convenience methods for accessing those directly. You can also retrieve a reference to the code block of the currently executing frame using the code method. The frame also captures all lexical variables stored with the frame, which are available by calling my on the frame object.

Here's a short example that will find the calling routine and prints the package of the caller using the callframe interface.

sub calling-frame() {
    for 1..* -> $level {
        given callframe($level-> $frame {
            when $frame ~~ CallFrame {
                    next unless $frame.code ~~ Routine;
                    say $frame.code.package;
                    last;
            }
            default {
                    say "no calling routine or method found";
                    last;
            }
        }
    }
}
 
calling-frame;

If you just need to trace caller information, Backtrace may provide a better means of getting information. CallFrame contains more information about a specific frame, but provides a tedious interface for enumerating a call stack.

Methods

method code

method code(CallFrame:D:)

Return the callable code for the current block. When called on the object returned by callframe(0), this will be the same value found in &?BLOCK.

method file

method file(CallFrame:D:)

This is a shortcut for looking up the file annotation. Therefore, the following code prints True.

my $frame = callframe(0);
say $frame.file eq $frame.annotations<file>;

method level

method level(CallFrame:D:)

Return the absolute level of the frame in the stack. This will usually be higher than 0 when calling callframe(0). Using a negative number to retrieve a frame less than 0 will result in an exception.

method line

method line(CallFrame:D:)

This is a shortcut for looking up the line annotation. For example, the following two calls are identical.

say callframe(1).line;
say callframe(1).annotations<line>;

method annotations

method annotations(--> Map:D)

Returns a Map containing the invocants annotations, i.e. line and file. An easier way to get hold of the annotation information is to use one of the convenience methods instead.

say callframe.annotations.^name;                   # OUTPUT: «Map␤» 
 
say callframe.annotations<file> eq callframe.file# OUTPUT: «True␤» 

method my

method my(CallFrame:D:)

Return a Hash that names all the variables and their values associated with the lexical scope of the frame.

sub some-value {
    my $the-answer = 42;
    callframe(0);
}
 
my $frame = some-value();
say $frame.my<$the-answer># OUTPUT: «42␤» 

Routines

sub callframe

sub callframe(Int $level = 0)

Returns a CallFrame object for the given level. If no level is given, the default level is 0. Positive levels move up the frame stack and negative levels move down (into the call to callframe and deeper).

Returns Mu if there is no call information for the given level. (Negative levels may result in an exception.)

Type Graph

Type relations for CallFrame
perl6-type-graph CallFrame CallFrame Any Any CallFrame->Any Mu Mu Any->Mu

Expand above chart