NAME

Trace::Mask::Reference - Reference implemtnations of tools and tracers

DESCRIPTION

This module provides a reference implementation of an Stack::Mask compliant stack tracer. It also provides reference examples of tools that benefit from masking stack traces. These tools should NOT be used in production code, but may be useful in unit tests that verify compliance.

SYNOPSIS

    use Trace::Mask::Reference qw/try_example trace_string/;

    sub foo {
        print trace_string;
    }

    sub bar {
        my $error = try_example { foo() };
        ...
    }

    sub baz {
        bar();
    }

    baz();

This produces the following stack trace:

    main::foo() called at test.pl line 8
    main::bar() called at test.pl line 13
    main::baz() called at test.pl line 16

Notice that the call to try, the eval it uses inside, and the call to the anonymous codeblock are all hidden. This effectively removes noise from the stack trace. It makes 'try' look just like an 'if' or 'while' block. There is a downside however if anything inside the try implementation itself is broken.

EXPORTS

Note: All exports are optional, you must request them if you want them.

$frames_ref = trace()

This produces an array reference containing stack frames of a trace. Each frame is an arrayref that matches the return from caller(), with the additon that the last index contains the arguments used in the call. Never rely on the index number of the arguments, always pop them off if you need them, different versions of perl may have a different number of values in a stack frame.

Index 0 of the $frames_ref will be the topmost call of the trace, the rest will be in descending order.

See trace_string() for a tool to provide a carp-like stack trace.

$level may be specified to start the stack at a deeper level.

$trace = trace_string()

$trace = trace_string($level)

This provides a stack trace string similar to longmess() from Carp. Though it does not indent the trace, and it does not take the form of an error report.

$level may be specified to start the stack at a deeper level.

($pkg, $file, $line) = trace_mask_caller()

($pkg, $file, $line, $name, ...) = trace_mask_caller($level)

This is a caller() emulator that honors the stack tracing specifications. Please do not override caller() with this. This implementation take a FULL stack trace on each call, and returns just the desired frame from that trace.

$error = try_example { ... }

A reference implementation of try { ... } that demonstrates the trace masking behavior. Please do not use this in production code, it is a very dumb, and not-very-useful implementation of try that serves as a demo.

SEE ALSO

Sub::Uplevel - Tool for hiding stack frames from all callers, not just stack traces.

SOURCE

The source code repository for Trace-Mask can be found at http://github.com/exodist/Trace-Mask.

MAINTAINERS

Chad Granum <exodist@cpan.org>

AUTHORS

Chad Granum <exodist@cpan.org>

COPYRIGHT

Copyright 2015 Chad Granum <exodist7@gmail.com>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html