Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Reflow, eliminates level 
And some general cleanup as an initiation for #2719
  • Loading branch information
@JJ
JJ committed Apr 18, 2019
1 parent e42f328 commit 10db477
Showing 1 changed file with 44 additions and 27 deletions.
71 changes: 44 additions & 27 deletions doc/Type/CallFrame.pod6
View file
Expand Up @@ -2,25 +2,42 @@
=TITLE class CallFrame
=SUBTITLE Capturing current frame state
=SUBTITLE Captures the current frame state
class CallFrame {}
There's no way to instantiate a C<CallFrame>. Instead, it is captured from the current state of a program using the L<callframe|/routine/callframe> subroutine.
A CallFrame will be usually captured from the
current state of a program using the L<callframe|/routine/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 C<callframe>. The file and line annotations will be identical to those in
L«C<$?FILE>|/language/variables#Compile-time_variables» and L«C<$?LINE>|/language/variables#Compile-time_variables».
You may, however, pass a number to C<callframe> to specify a different frame level. The current frame is level 0 (though level of the frame may be different, see L<level|/routine/level> for more information). A positive number will move upward through the levels of frame. A negative number will move downward into the C<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 L<annotations|/routine/annotations>, including the L<file|/routine/file> and L<line|/routine/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 L<code|/routine/code> method. The frame also captures all lexical variables stored with the frame, which are available by calling L<my|/routine/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 C<callframe> interface.
With no arguments the callframe will give you frame information for the line
calling C<callframe>. The file and line annotations will be identical to those
in L«C<$?FILE>|/language/variables#Compile-time_variables» and
L«C<$?LINE>|/language/variables#Compile-time_variables».
You may, however, pass a number to C<callframe> to specify a different frame
level. The current frame is level 0 (though level of the frame may be different,
see L<level|/routine/level> for more information). A positive number will move
upward through the levels of frame. A negative number will move downward into
the C<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 L<annotations|/routine/annotations>, including the
L<file|/routine/file> and L<line|/routine/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
L<code|/routine/code> method. The frame also captures all lexical variables
stored with the frame, which are available by calling L<my|/routine/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 C<callframe> interface.
sub calling-frame() {
for 1..* -> $level {
Expand All @@ -40,10 +57,15 @@ Here's a short example that will find the calling routine and prints the package
calling-frame;
If you just need to trace caller information, L<Backtrace|/type/Backtrace> may provide a better means of getting information. L<CallFrame|/type/CallFrame> contains more information about a specific frame, but provides a tedious interface for enumerating a call stack.
If you just need to trace caller information, L<Backtrace|/type/Backtrace> may
provide a better means of getting information. L<CallFrame|/type/CallFrame>
contains more information about a specific frame, but provides a tedious
interface for enumerating a call stack.
=head1 Methods
B<Note> From version 6.d, C<.perl> can be called on C<CallFrame>.
=head2 method code
method code(CallFrame:D:)
Expand All @@ -54,22 +76,18 @@ Return the callable code for the current block. When called on the object return
method file(CallFrame:D:)
This is a shortcut for looking up the C<file> annotation. Therefore, the following code prints C<True>.
This is a shortcut for looking up the C<file> annotation. Therefore, the
following code prints C<True>.
my $frame = callframe(0);
say $frame.file eq $frame.annotations<file>;
=head2 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 C<callframe(0)>. Using a negative number to retrieve a frame less than 0 will result in an exception.
=head2 method line
method line(CallFrame:D:)
This is a shortcut for looking up the C<line> annotation. For example, the following two calls are identical.
This is a shortcut for looking up the C<line> annotation. For example, the
following two calls are identical.
say callframe(1).line;
say callframe(1).annotations<line>;
Expand All @@ -78,9 +96,9 @@ This is a shortcut for looking up the C<line> annotation. For example, the follo
method annotations(--> Map:D)
Returns a L<Map|/type/Map> containing the invocants annotations, i.e. C<line> and C<file>.
An easier way to get hold of the annotation information is to use one
of the convenience methods instead.
Returns a L<Map|/type/Map> containing the invocants annotations, i.e. C<line>
and C<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␤»
Expand All @@ -90,7 +108,8 @@ of the convenience methods instead.
method my(CallFrame:D:)
Return a L<Hash|/type/Hash> that names all the variables and their values associated with the lexical scope of the frame.
Return a L<Hash|/type/Hash> that names all the variables and their values
associated with the lexical scope of the frame.
sub some-value {
my $the-answer = 42;
Expand All @@ -100,8 +119,6 @@ Return a L<Hash|/type/Hash> that names all the variables and their values associ
my $frame = some-value();
say $frame.my<$the-answer>; # OUTPUT: «42␤»
B<Note> From version 6.d, C<.perl> can be called on C<CallFrame>.
=head1 Routines
=head2 sub callframe
Expand Down

0 comments on commit 10db477

Please sign in to comment.