Trace::Mask::Reference(3pm)

1Trace::Mask::Reference(U3s)er Contributed Perl DocumentatTiroance::Mask::Reference(3)
2
3
4

NAME

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

DESCRIPTION

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

SYNOPSIS

16           use Trace::Mask::Reference qw/try_example trace_string/;
17
18           sub foo {
19               print trace_string;
20           }
21
22           sub bar {
23               my $error = try_example { foo() };
24               ...
25           }
26
27           sub baz {
28               bar();
29           }
30
31           baz();
32
33       This produces the following stack trace:
34
35           main::foo() called at test.pl line 8
36           main::bar() called at test.pl line 13
37           main::baz() called at test.pl line 16
38
39       Notice that the call to try, the eval it uses inside, and the call to
40       the anonymous codeblock are all hidden. This effectively removes noise
41       from the stack trace. It makes 'try' look just like an 'if' or 'while'
42       block. There is a downside however if anything inside the "try"
43       implementation itself is broken.
44
45   EXPORTS
46       Note: All exports are optional, you must request them if you want them.
47
48       $frames_ref = trace()
49           This produces an array reference containing stack frames of a
50           trace. Each frame is an arrayref that matches the return from
51           "caller()", with the additon that the last index contains the
52           arguments used in the call. Never rely on the index number of the
53           arguments, always pop them off if you need them, different versions
54           of perl may have a different number of values in a stack frame.
55
56           Index 0 of the $frames_ref will be the topmost call of the trace,
57           the rest will be in descending order.
58
59           See "trace_string()" for a tool to provide a carp-like stack trace.
60
61           $level may be specified to start the stack at a deeper level.
62
63       $trace = trace_string()
64       $trace = trace_string($level)
65           This provides a stack trace string similar to "longmess()" from
66           Carp.  Though it does not indent the trace, and it does not take
67           the form of an error report.
68
69           $level may be specified to start the stack at a deeper level.
70
71       ($pkg, $file, $line) = trace_mask_caller()
72       ($pkg, $file, $line, $name, ...) = trace_mask_caller($level)
73           This is a "caller()" emulator that honors the stack tracing
74           specifications.  Please do not override "caller()" with this. This
75           implementation take a FULL stack trace on each call, and returns
76           just the desired frame from that trace.
77
78       $error = try_example { ... }
79           A reference implementation of "try { ... }" that demonstrates the
80           trace masking behavior. Please do not use this in production code,
81           it is a very dumb, and not-very-useful implementation of "try" that
82           serves as a demo.
83

SOURCE

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

MAINTAINERS

93       Chad Granum <exodist@cpan.org>
94

AUTHORS

96       Chad Granum <exodist@cpan.org>
97

COPYRIGHT

99       Copyright 2015 Chad Granum <exodist7@gmail.com>.
100
101       This program is free software; you can redistribute it and/or modify it
102       under the same terms as Perl itself.
103
104       See http://www.perl.com/perl/misc/Artistic.html
105
106
107
108perl v5.36.0                      2022-07-22         Trace::Mask::Reference(3)