class Backtrace

Snapshot of the dynamic call stack
class Backtrace {}

A backtrace contains the dynamic call stack, usually leading up to a point where an exception was thrown, and is a List of Backtrace::Frame objects. Its default stringification excludes backtrace frames that are deemed unnecessary or confusing; for example routines like &die are hidden by default. Being a list, you can also access individual elements.

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

This will print the last frame in the list, pointing at the line where it's happened.

Methods

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.

my $backtrace = Backtrace.new;

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.

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

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.

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

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.

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

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.

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

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.

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

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 a summary string representation of the backtrace, filtered by !.is-hidden && (.is-routine || !.is-setting).

This program:

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

results in:

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

method concise

method concise(Backtrace:D:)

Returns a concise string representation of the backtrace, filtered by !.is-hidden && .is-routine && !.is-setting.

This program:

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

results in:

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

method map

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

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

This program:

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

results in:

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

method flat

multi method flat(Backtrace:D:)

Returns the backtrace same as list.

See Also

class Backtrace::Frame

Single frame of a Backtrace

role CX::Done

Done control exception

role CX::Emit

Emit control exception

role CX::Last

Last control exception

role CX::Next

Next control exception

role CX::Proceed

Proceed control exception

role CX::Redo

Redo control exception

role CX::Return

Return control exception

role CX::Succeed

Succeed control exception

role CX::Take

Take control exception

role CX::Warn

Control exception warning

class Exception

Anomalous event capable of interrupting normal control-flow

class Failure

Delayed exception

class X::AdHoc

Error with a custom message

class X::Anon::Augment

Compilation error due to augmenting an anonymous package

class X::Anon::Multi

Compilation error due to declaring an anonymous multi

class X::Assignment::RO

Exception thrown when trying to assign to something read-only

class X::Attribute::NoPackage

Compilation error due to declaring an attribute outside of a package

class X::Attribute::Package

Compilation error due to declaring an attribute in an ineligible package

class X::Attribute::Required

Compilation error due to not declaring an attribute with the is required trait

class X::Attribute::Undeclared

Compilation error due to an undeclared attribute

class X::Augment::NoSuchType

Compilation error due to augmenting a non-existing type

class X::Bind

Error due to binding to something that is not a variable or container

class X::Bind::NativeType

Compilation error due to binding to a natively typed variable

class X::Bind::Slice

Error due to binding to a slice

class X::Caller::NotDynamic

Error while trying to access a non dynamic variable through CALLER

class X::Cannot::Empty

Error due to inappropriate usage of an empty collection

class X::Cannot::Lazy

Error due to inappropriate usage of a lazy list

class X::Channel::ReceiveOnClosed

Error due to calling receive on a closed channel

class X::Channel::SendOnClosed

Error due to calling send on a closed channel

class X::Composition::NotComposable

Compilation error due to composing an ineligible type

class X::Constructor::Positional

Error due to passing positional arguments to a default constructor

role X::Control

Role for control exceptions

class X::ControlFlow

Error due to calling a loop control command in an ineligible scope

class X::ControlFlow::Return

Error due to calling return outside a routine

class X::DateTime::TimezoneClash

Error due to using both time zone offset and :timezone

class X::Declaration::Scope

Compilation error due to a declaration with an ineligible scope

class X::Declaration::Scope::Multi

Compilation error due to declaring a multi with an ineligible scope

class X::Does::TypeObject

Error due to mixing into a type object

class X::Dynamic::NotFound

Runtime error thrown when a dynamic variable does not exist

class X::Eval::NoSuchLang

Error due to specifying an unknown language for EVAL

class X::Export::NameClash

Compilation error due to exporting the same symbol twice

class X::Inheritance::NotComposed

Error due to inheriting from a type that's not composed yet

class X::Inheritance::Unsupported

Compilation error due to inheriting from an ineligible type

class X::IO::BinaryMode

Error while invoking methods on a handle in binary mode.

class X::IO::Chdir

Error while trying to change the working directory

class X::IO::Chmod

Error while trying to change file permissions

class X::IO::Chown

Error while trying to change file ownership

class X::IO::Copy

Error while trying to copy a file

class X::IO::Cwd

Error while trying to determine the current working directory

class X::IO::Dir

Error while trying to get a directory's contents

class X::IO::DoesNotExist

Error while doing file tests on a non existing path

class X::IO::Link

Error while trying to create a link

class X::IO::Mkdir

Error while trying to create a directory

class X::IO::Move

Error while trying to move a file

class X::IO::Rename

Error while trying to rename a file or directory

class X::IO::Rmdir

Error while trying to remove a directory

class X::IO::Symlink

Error while trying to create a symbolic link

class X::IO::Unlink

Error while trying to remove a file

class X::Method::InvalidQualifier

Error due to calling a qualified method from an ineligible class

class X::Method::NotFound

Error due to calling a method that isn't there

class X::Method::Private::Permission

Compilation error due to calling a private method without permission

class X::Method::Private::Unqualified

Compilation error due to an unqualified private method call

class X::Mixin::NotComposable

Error due to using an ineligible type as a mixin

class X::NoDispatcher

Error due to calling a dispatch command in an ineligible scope

class X::Numeric::CannotConvert

Error while trying to coerce a number to another type

class X::Numeric::DivideByZero

Error while trying to divide by zero

class X::Numeric::Real

Error while trying to coerce a number to a Real type

class X::NYI

Error due to use of an unimplemented feature

class X::Obsolete

Compilation error due to use of obsolete syntax

class X::OutOfRange

Error due to indexing outside of an allowed range

class X::Package::Stubbed

Compilation error due to a stubbed package that is never defined

class X::Parameter::Default

Compilation error due to an unallowed default value in a signature

class X::Parameter::MultipleTypeConstraints

Compilation error due to a parameter with multiple type constraints

class X::Parameter::Placeholder

Compilation error due to an unallowed placeholder in a signature

class X::Parameter::Twigil

Compilation error due to an unallowed twigil in a signature

class X::Parameter::WrongOrder

Compilation error due to passing parameters in the wrong order

class X::Phaser::Multiple

Compilation error due to multiple phasers of the same type

class X::Phaser::PrePost

Error due to a false return value of a PRE/POST phaser

class X::Placeholder::Block

Compilation error due to a placeholder in an ineligible block

class X::Placeholder::Mainline

Compilation error due to a placeholder in the mainline

class X::Proc::Async::AlreadyStarted

Error due to calling start on an already started Proc::Async object

class X::Proc::Async::BindOrUse

Error due to trying to bind a handle that is also used

class X::Proc::Async::CharsOrBytes

Error due to tapping the same Proc::Async stream for both text and binary reading

class X::Proc::Async::MustBeStarted

Error due to interacting with a Proc::Async stream before spawning its process

class X::Proc::Async::OpenForWriting

Error due to writing to a read-only Proc::Async object

class X::Proc::Async::TapBeforeSpawn

Error due to tapping a Proc::Async stream after spawning its process

class X::Proc::Unsuccessful

Exception thrown if a Proc object is sunk after the process it ran exited unsuccessfully

class X::Promise::CauseOnlyValidOnBroken

Error due to asking why an unbroken promise has been broken.

class X::Promise::Vowed

Error due to directly trying to keep/break a vowed promise.

class X::Redeclaration

Compilation error due to declaring an already declared symbol

class X::Role::Initialization

Error due to passing an initialization value to an ineligible role

class X::Scheduler::CueInNaNSeconds

Error caused by passing NaN to Scheduler.cue as :at, :in, or :every

class X::Seq::Consumed

Error due to trying to reuse a consumed sequence

class X::Sequence::Deduction

Error due to constructing a sequence from ineligible input

class X::Signature::NameClash

Compilation error due to two named parameters with the same name

class X::Signature::Placeholder

Compilation error due to placeholders in a block with a signature

class X::Str::Match::x

Invalid argument type for :x argument to Str matching methods

class X::Str::Numeric

Error while trying to coerce a string to a number

class X::StubCode

Runtime error due to execution of stub code

class X::Syntax::Augment::WithoutMonkeyTyping

Compilation error due to augmenting a type without the MONKEY-TYPING pragma

class X::Syntax::Comment::Embedded

Compilation error due to a malformed inline comment

class X::Syntax::Confused

Compilation error due to unrecognized syntax

class X::Syntax::InfixInTermPosition

Compilation error due to an infix in term position

class X::Syntax::Malformed

Compilation error due to a malformed construct (usually a declarator)

class X::Syntax::Missing

Compilation error due to a missing piece of syntax

class X::Syntax::NegatedPair

Compilation error due to passing an argument to a negated colonpair

class X::Syntax::NoSelf

Compilation error due to implicitly using a self that is not there

class X::Syntax::Number::RadixOutOfRange

Compilation error due to an unallowed radix in a number literal

class X::Syntax::P5

Compilation error due to use of Perl-only syntax

class X::Syntax::Perl5Var

Compilation error due to use of Perl-only default variables

class X::Syntax::Regex::Adverb

Compilation error due to an unrecognized regex adverb

class X::Syntax::Regex::SolitaryQuantifier

Compilation error due to a regex quantifier without preceding atom

class X::Syntax::Reserved

Compilation error due to use of syntax reserved for future use

class X::Syntax::Self::WithoutObject

Compilation error due to invoking self in an ineligible scope

class X::Syntax::Signature::InvocantMarker

Compilation error due to a misplaced invocant marker in a signature

class X::Syntax::Term::MissingInitializer

Compilation error due to declaring a term without initialization

class X::Syntax::UnlessElse

Compilation error due to an unless clause followed by else

class X::Syntax::Variable::Match

Compilation error due to declaring a match variable

class X::Syntax::Variable::Numeric

Compilation error due to declaring a numeric symbol

class X::Syntax::Variable::Twigil

Compilation error due to an unallowed twigil in a declaration

class X::Temporal::InvalidFormat

Error due to using an invalid format when creating a DateTime or Date

class X::TypeCheck

Error due to a failed type check

class X::TypeCheck::Assignment

Error due to a failed type check during assignment

class X::TypeCheck::Binding

Error due to a failed type check during binding

class X::TypeCheck::Return

Error due to a failed typecheck during return

class X::TypeCheck::Splice

Compilation error due to a macro trying to splice a non-AST value

class X::Undeclared

Compilation error due to an undeclared symbol

The Camelia image is copyright 2009 by Larry Wall. "Raku" is trademark of the Yet Another Society. All rights reserved.