Rules / Types, classes & roles / exception

Backtrace Reference

Snapshot of the dynamic call stack

What it is #

Routines #

Signatures are reproduced from the documentation, including their declared return types. A routine listed here is part of the type's published interface; whether Raku++ implements it is a separate question, answered by the examples below.

method new #

multi method new()
multi method new(Int:D $offset)
multi method new(Mu \ex)
multi method new(Mu \ex, Int:D $offset)
multi method new(List:D $bt)
multi method new(List:D $bt, Int:D $offset)

Creates a new backtrace, using its calling location as the origin of the backtrace or the $offset that is passed as a parameter. If an object or a list (that will already contain a backtrace in list form) is passed, they will be used instead of the current code.

method gist #

multi method gist(Backtrace:D:)

Returns string "Backtrace(42 frames)" where the number indicates the number of frames available via list method.

method Str #

multi method Str(Backtrace:D:)

Returns a concise string representation of the backtrace, omitting routines marked as is hidden-from-backtrace, and at the discretion of the implementation, also some routines from the setting.

method next-interesting-index #

method next-interesting-index(Backtrace:D: Int $idx = 0, :$named, :$noproto, :$setting)

Returns the index of the next interesting frame, once hidden and other settings are taken into account. $named will decide whether to printed only those with a name, $noproto will hide protos, and $setting will hide those are considered setting.

method outer-caller-idx #

method outer-caller-idx(Backtrace:D: Int $startidx)

Returns as a list the index of the frames that called the current one.

method nice #

method nice(Backtrace:D: :$oneline)

Returns the backtrace as a list of interesting frames. If :$oneline is set, will stop after the first frame.

method full #

multi method full(Backtrace:D:)

Returns a full string representation of the backtrace, including hidden frames, compiler-specific frames, and those from the setting.

method list #

multi method list(Backtrace:D:)

Returns a list of Backtrace::Frame objects for this backtrace.

method summary #

method summary(Backtrace:D: --> Str:D)

Returns Str:D.

Returns a summary string representation of the backtrace, filtered by !.is-hidden && (.is-routine || !.is-setting). This program: results in:

method concise #

method concise(Backtrace:D:)

Returns a concise string representation of the backtrace, filtered by !.is-hidden && .is-routine && !.is-setting. This program: results in:

method map #

multi method map(Backtrace:D: &block --> Seq:D)

Returns Seq:D.

It invokes &block for each element and gathers the return values in a sequence and returns it. This program: results in:

method flat #

multi method flat(Backtrace:D:)

Returns the backtrace same as list.

Examples, run three ways #

Every example below comes from the official documentation, together with the output that documentation asserts. Each was then executed by Rakudo and by Raku++ when this page was built. Where the three agree, one result is shown; where they do not, all three are — because which of them is wrong is exactly the information worth having.

2 all-differ · 11 no-output · 1 rakupp-differs

class Backtrace {}

Not executed: the documentation states no expected output for this example.

sub zipi { { { die "Something bad happened" }() }() };
try {
zipi;
}
if ($!) {
say $!.backtrace[*-1].raku;
}

Not executed: the documentation states no expected output for this example.

my $backtrace = Backtrace.new;

Not executed: the documentation states no expected output for this example.

my $backtrace = Backtrace.new;
say $backtrace.Str;

Not executed: the documentation states no expected output for this example.

sub zipi { { { die "Something bad happened" }() }() };
try zipi;
say $!.backtrace.next-interesting-index;           # OUTPUT: «2␤»
say $!.backtrace.next-interesting-index( :named ); #  OUTPUT: «4␤»
Documentation
2
Rakudo
2
4
Raku++

All three differ. Needs a human.

Not yet examined. Which of these is correct has not been established — do not treat either engine as settled here.

sub zipi { { { die "Something bad happened" }() }() };
try zipi;
say $!.backtrace.outer-caller-idx( 4 ); # OUTPUT: «[6]␤»
Documentation
[6]
Rakudo
[6]
Raku++

Raku++ disagrees with both the documentation and Rakudo — a defect.

sub zipi { { { die "Something bad happened" }() }() };
try zipi;
say $!.backtrace.nice( :oneline ) if $!;
# OUTPUT: «  in sub zipi at /tmp/... line 1␤␤»
Documentation
  in sub zipi at /tmp/... line 1
Rakudo
  in sub zipi at -e line 1
Raku++

All three differ. Needs a human.

Not yet examined. Which of these is correct has not been established — do not treat either engine as settled here.

my $backtrace = Backtrace.new;
say $backtrace.full;

Not executed: the documentation states no expected output for this example.

sub inner { say Backtrace.new.summary }
sub outer { inner; }
outer;

Not executed: the documentation states no expected output for this example.

in method new at SETTING::src/core.c/Backtrace.rakumod line 85
in sub inner at test.raku line 1
in sub outer at test.raku line 2
in block <unit> at test.raku line 3

Not executed: the documentation states no expected output for this example.

sub inner { say Backtrace.new.concise }
sub outer { inner; }
outer;

Not executed: the documentation states no expected output for this example.

in sub inner at test.raku line 1
in sub outer at test.raku line 2

Not executed: the documentation states no expected output for this example.

sub inner { Backtrace.new.map({ say "{$_.file}: {$_.line}" }); }
sub outer { inner; }
outer;

Not executed: the documentation states no expected output for this example.

SETTING::src/core.c/Backtrace.rakumod: 85
SETTING::src/core.c/Backtrace.rakumod: 85
test.raku: 1
test.raku: 2
test.raku: 3
test.raku: 1

Not executed: the documentation states no expected output for this example.