NAME

Trace::Mask::Util - Utilities for applying stack trace masks.

DESCRIPTION

This package provides utilities to help you apply masks for stack traces. See Trace::Mask for the specification these utilities follow.

EXPORTS

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

update_mask($file, $line, $sub, \%mask)

Update the mask for the specified $file, $line, and $sub. The mask hashref will be merged into any existing mask. You may use the wildcard string '*' for any 2 of the first 3 arguments. $sub may be coderef, or a fully qualified sub name.

@errors = validate_mask(\%mask)

This will check the mask to ensure it is valid. If the mask is valid an empty list is returned. If there are problems with the mask then a list of error strings will be returned.

$hr = get_mask($file, $line, $sub)

Get the combined mask for the specific file, line and sub. This will be a merger of all applicable masks, including wildcards. $sub may be a coderef, or a fully qualified sub name.

mask_call(\%mask, $sub)

mask_call(\%mask, $sub, @args)

This will call $sub with the specified mask and arguments. This will use goto &$sub to run your sun without mask_call() itself showing up in any stack frames. $sub can be a sub reference, or the name of a sub in the calling package.

mask_sub(\%mask, $sub)

mask_sub(\%mask, $sub, $file)

mask_sub(\%mask, $sub, $file, $line)

Apply the mask to the specified sub, which can be a coderef, or the name of a sub in the calling package. $file and $line are optional, '*' will be used if you do not specify.

mask_line(\%mask)

mask_line(\%mask, $delta)

mask_line(\%mask, $delta, @subs)

This will mask calls on the current or current + $delta line of the calling package. Optionally uo can provide a list of subs to mask, '*' is used if none are specified.

This is useful if you wish to apply a mask to multiple calls on a specific line:

sub try(&) {
    my $code = shift;

    # Hides both the eval, and the anon-block call
    BEGIN { mask_line({hide => 1}, 1) }
    my $ok = eval { $code->(); 1 };

    ...
}

It is best to run this in a BEGIN {...} block so that the mask is added at compile time, instead of being re-added every time your code is run.

mask_frame(%mask)

This applies a mask to the currently running stack frame, that is whatever sub you use it in. This applies no matter where/how your sub was called.

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