view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

    call, except for package, file, and line, will replace the values of the next
    frame to be kept in the trace. If `$COUNT` is large than 1, the shift will
    hide frames between the shifted frame and the new frame. If `$COUNT` is larger
    than the remaining stack, the lowest unhidden/unshifted stack frame will be the
    recipient of the shift operation, even if the shift frame itself is the lowest.

    This has the same effect on a stack trace as `goto &sub`.

## MASK RESOLUTION

Multiple masks in the `%Trace::Mask::MASKS` structure may apply to any given
stack frame, a compliant tracer will account for all of them. A simple hash
merge is sufficient so long as they are merged in the correct order. Here is an
example:

    my $masks_ref = \%Trace::Mask::MASKS;

    my @all = grep { defined $_ } (
        $masks_ref->{$file}->{'*'}->{'*'},
        $masks_ref->{$file}->{$line}->{'*'},
        $masks_ref->{'*'}->{'*'}->{$name},
        $masks_ref->{$file}->{'*'}->{$name},
        $masks_ref->{$file}->{$line}->{$name},
    );

    my %final = map { %{$_} } @all;

The most specific path should win out (override others). Rightmost path
component is considered the most important. More wildcards means less specific.
Paths may never have wildcards for all 3 components.

## $ENV{'NO\_TRACE\_MASK'}

If this environment variable is set to true then all masking rules should be
ignored, tracers should produce full and complete stack traces.

## TRACES STARTING AT $LEVEL

If a tracing tool starts at the call to the tool (such as `Carp::confess()`)
then it should account for all the masks starting with the call to confess
itself going all the way until the bottom of the stack, or until a mask with
'stop' is found. If a tracing tool allows you to start tracing from a specific
level, the tracer should still account for the masks of the frames at the top
of the stack on which it is not reporting.

## MASK NUMERIC KEYS

Numeric keys in a mask represent items in the list returned from `caller()`.
If you provide numeric keys their values will replace the corresponding value
in the caller list before it is used in the trace. You can use this to replace
the package, file, etc. This will work for any VALID index into the list. This
cannot be used to extend the list. Numeric keys outside the bounds of the list
are simply ignored, this is for compatability as different perl versions may
have a different size list.

## SPECIAL/MAGIC subs

Traces must NEVER hide or alter the following special/magic subs:

- BEGIN
- UNITCHECK
- CHECK
- INIT
- END
- DESTROY
- import
- unimport

These subs are all special in one way or another, hiding them would be hiding
critical information.

# CLASS METHODS

The `masks()` method is defined in [Trace::Mask](https://metacpan.org/pod/Trace::Mask), it returns a reference to
the `%Trace::Mask::MASKS` hash for easy access. It is fine to cache this
reference, but not the data it contains.

# REFERENCE

[Trace::Mask::Reference](https://metacpan.org/pod/Trace::Mask::Reference) is included in this distribution. The Reference
module contains example tracers, and example tools that benefit from masking
stack traces. The examples in this module should NOT be used in production
code.

# UTILS

[Trace::Mask::Util](https://metacpan.org/pod/Trace::Mask::Util) is included in this distribution. The util module provides
utilities for adding stack trace masking behavior. The utilities provided by
this module are considered usable in production code.

# TEST

[Trace::Mask::Test](https://metacpan.org/pod/Trace::Mask::Test) is included in this distribution. This module provides
test cases and tools useful for verifying your tracing tools are compliant with
the spec.

# PLUGINS

## Carp

[Trace::Mask::Carp](https://metacpan.org/pod/Trace::Mask::Carp) is included in this distribution. This module can make
[Carp](https://metacpan.org/pod/Carp) compliant with [Trace::Mask](https://metacpan.org/pod/Trace::Mask).

## Try::Tiny

[Trace::Mask::TryTiny](https://metacpan.org/pod/Trace::Mask::TryTiny) is included in this ditribution. Simply loading theis
module will cause [Try::Tiny](https://metacpan.org/pod/Try::Tiny) framework to be hidden in compliant stack
traces.

# SEE ALSO

[Sub::Uplevel](https://metacpan.org/pod/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