class CallFrame {}

A CallFrame will be usually 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. 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 only 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 them 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 print 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 it. CallFrame contains more information about a specific frame, but provides a tedious interface for enumerating a call stack.

Methods

Note From version 6.d, .perl can be called on CallFrame.

method code

method code()

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.

my $frame;
for ^3 { FIRST $frame = callframe; say $_ * 3 };
say $frame.code()

The $frame variable will hold the Code for the block inside the loop in this case.

method file

method file()

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 line

method line()

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()

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()

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:D $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

Expand above chart