NAME

Trap - Trap \$*OUT and/or \$*ERR output

SYNOPSIS

use Trap;

my $out;
my $err;
{   # separate capturing
    $out = Trap(my $*OUT);
    $err = Trap(my $*ERR);
    say "Hello world!";
    note "Goodbye!"
}
print "STDOUT: $out.text()";  # SDDOUT: Hello world!␤
print "STDERR: $err.text()";  # STDERR: Goodbye!␤

my $merged;
{   # merged capturing
    $merged = Trap(my $*OUT, my $*ERR);
    say "Hello world!";
    note "Goodbye!"
}
print $merged.text;  # Hello world!␤Goodbye!␤

my $new;
{   # creating the object manually
    $new = my $*OUT = Trap.new;
    say "Hello world!";
}
print "with object: $new.text()";  # with object: Hello world!␤

{   # ignoring any output
    Trap(my $*OUT, my $*ERR);
    say "shall never be seen";
}

my $trap;
{
    $trap = Trap(my $*OUT);
    note "not on STDOUT";
}
say $trap.silent;  # True

my $visual;
{
    # show output as well as trapping
    $visual = Trap(my $*OUT, :tee<OUT>)
    say "Quality first";  # also shown
}
print $visual.text;  # Quality First␤

DESCRIPTION

Trap exports a class Trap that can be called to capture standard output and/or standard error, typically for a lexical scope.

The class can be called with either one or two arguments, each of which should be a writeable local dynamic variable $*OUT or $*ERR. Or one can create the Trap object manually. Or one can use Trap to just trap the standard output and/or standard error (see SYNOPSIS for examples).

Note that if you're only interested in surpressing output from warnings, you should use the quietly statement prefix.

METHODS

text

Returns the combined text that was captured.

silent

Returns True if no output was captured at all (not even empty strings), False otherwise.

TEEING OUTPUT

my $trap = Trap(my $*OUT, :tee<OUT>)
say "foo";        # foo␤    on STDOUT
note $trap.text;  # foo␤    on STDERR

The named argument :tee can be specified to output captured output as it is being captured on either the original STDOUT or STDERR output handle (by specifying the string "OUT" or "ERR".

my $trap = Trap(my $*OUT, :tee("teed.output".IO))
say "foo";        # foo␤    on STDOUT
note $trap.text;  # foo␤    on STDERR

One can also specify any IO::Path orIO::Handle object to have the output trapped to.

The name of this named argument is inspired by the Unix tee command.

AUTHOR

Elizabeth Mattijsen <[email protected]>

Source can be located at: https://github.com/lizmat/Trap . 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

Copyright 2022, 2024, 2025 Elizabeth Mattijsen

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

# vim: expandtab shiftwidth=4