NAME

Backtrace::Files - turn backtrace into list of files / lines

SYNOPSIS

use Backtrace::Files;

.say for backtrace-files($backtrace, :context(2));

say normalize-backtrace-filename("SETTING::src/core.c/Cool.rakumod");

.say for add-source-lines(@backtrace);

DESCRIPTION

Backtrace::Files attempts to provide an abstract interface to backtraces and the files and line numbers in those backtraces, with the backtrace-files subroutine. Backtraces can be given as a string, or as an Exception object.

It also provides two helper subroutines: one for normalizing filenames to a local system installation (with references to the Rakudo core, and references to installed modules) called normalize-backtrace-filename.

And another called add-source-lines that will fetch the source lines of a given list of filename / line-numbers pairs, with potential context lines added.

SELECTIVE IMPORTING

use Backtrace::Files <backtrace-files>;  # only export sub backtrace-files

By default all subroutines are exported. But you can limit this to the functions you actually need by specifying the names in the use statement.

To prevent name collisions and/or import any subroutine with a more memorable name, one can use the "original-name:known-as" syntax. A semi-colon in a specified string indicates the name by which the subroutine is known in this distribution, followed by the name with which it will be known in the lexical context in which the use command is executed.

# export "backtrace-files" as "btf"
use Backtrace::Files <backtrace-files:btf>;

.say for btf($backtrace, :context(2));

EXPORTED SUBROUTINES

backtrace-files

# show file / linenrs of given backtrace
for backtrace-files($backtrace) -> (:key($file), :value(@lines)) {
    say "$file: @lines.join(',')";
}

# show file / linenrs / actual lines of given backtrace
for backtrace-files($backtrace, :source) -> (:key($file), :value(@lines)) {
    say "$file:";
    for @lines -> (:key($linenr), :value($line)) {
        say "$linenr: $line";
    }
    say "";
}

The backtrace-files subroutine accepts a single positional argument, the source of the backtrace information. This can either be an Exception, a IO::Handle object, an IO::Path object, or a string.

By default, the backtrace-files subroutine produces a list of Pairs of which the key is the absolute filename, and the value is a list of line numbers of consecutive frames within the same file. Please note that the same filename can occur more than once, if not all calls to code in a file where consecutive in the backtrace.

The following optional named arguments can be specified to include the actual source of the lines as well:

:source

Indicates whether the actual source of the lines referred to in the backtrace, should be included as well. If specified with a true value, then each line number will be converted into a Pair with the line number as the key, and the actual line as the value (or an empty string if the line could not be obtained for whatever reason).

:context(N)

Indicates whether extra source lines should be added before and after the actual line number of the backtrace. Only makes sense if :source has been specified with a true value. If specified, indicates the number of lines that should be added before and after, as additional Pairs in the array keyed to the filename. Defaults to no lines being added.

:before-context(N)

Indicates whether extra source lines should be added before the actual line number of the backtrace. Only makes sense if :source has been specified with a true value. If specified, indicates the number of lines that should be added before, as additional Pairs in the array keyed to the filename. Defaults to whatever was (implicitely) specified with :context.

:after-context(N)

Indicates whether extra source lines should be added after the actual line number of the backtrace. Only makes sense if :source has been specified with a true value. If specified, indicates the number of lines that should be added after, as additional Pairs in the array keyed to the filename. Defaults to whatever was (implicitely) specified with :context.

:in-backtrace(Type)

Indicates the actual type that should be used to create Pairs of line number and actual source for lines that actually occurred in the backtrace. Only makes sense if :source has been specified with a true value. Defaults to Pair.

:added-context(Type)

normalize-backtrace-filename

say normalize-backtrace-filename("SETTING::src/core.c/Cool.rakumod");

The normalize-backtrace-filename subroutine is a utility subroutine that accepts a string consisting of a filename from a backtrace, and converts this to an actual filename if the file mentioned was a conceptual filename or a filename known to have missing information.

It is intended for situations where e.g. a CATCH block would look at the backtrace to produce a list of actual filenames.

add-source-lines

for add-source-lines($file, (10, 20)) -> (:key($file), :value(@pairs)) {
    say $file;
    for @pairs -> (:key($linenr), :value($source)) {
        say "$linenr:$source"
    }
}

The add-source-lines subroutine is a utility subroutine that will fetch the source lines indicated by pair(s) of filename and line number lists. It either accepts a filename and a list of line numbers, or a Pair consisting of a filename as key and a list of line numbers as value, or it accepts a list of Pairs with filename a list of line numbers.

It also accepts the :context, :before-context, :after-context, :in-backtrace and :added-context named arguments, with the same defaults as documented with the backtrace-files subroutine.

AUTHOR

Elizabeth Mattijsen liz@raku.rocks

Source can be located at: https://github.com/lizmat/Backtrace-Files . Comments and Pull Requests are welcome.

If you like this module, or what I’m doing more generally, committing to a small sponsorship would mean a great deal to me!

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.