Help language development. Donate to The Perl Foundation

IO::MiddleMan zef:raku-community-modules last updated on 2022-03-13

NAME

IO::MiddleMan - hijack, capture, or mute writes to an IO::Handle

TABLE OF CONTENTS

• NAME
• SYNOPSIS
• DESCRIPTION
• ACCESSORS
  • .data
  • .handle
  • .mode
• METHODS
  • .capture
  • .hijack
  • .mute
  • .normal
  • .Str
• CAVEATS
• REPOSITORY
• BUGS
• AUTHOR
• LICENSE

SYNOPSIS

my $mm = IO::MiddleMan.hijack: $*OUT;
say "Can't see this yet!";
$mm.mode = 'normal';
say "Want to see what I said?";
say "Well, fine. I said $mm";

my $fh = 'some-file'.IO.open: :w;
my $mm = IO::MiddleMan.capture: $fh;
$fh.say: 'test', 42;
say "We wrote $mm into some-file";

IO::MiddleMan.mute: $*ERR;
note "you'll never see this!";

DESCRIPTION

This module allows you to inject yourself in the middle between an IO::Handle and things writing into it. You can completely hijack the data, merely capture it, or discard it entirely.

ACCESSORS

.data

say Currently captured things are " $mm.data.join: '';

$mm.data = () unless $mm.data.grep: {/secrets/};
say "Haven't seen any secrets yet. Restarted the capture";

An array that contains data captured by .hijack and .capture methods. Each operation on the filehandle add one element to .data; those operations are calls to .print, .print-nl, .say, and .put methods on the original filehandle. Note that .data added with .say/.put will have \n added to it already.

.handle

my $mm = IO::MiddleMan.mute: $*OUT;
say "This is muted";
$mm.handle.say: "But this still works!";

The original IO::Handle. You can still successfully call data methods on it, and no captures will be done, regardless of what the IO::MiddleMan .mode is.

.mode

my $mm = IO::MiddleMan.hijack: $*OUT;
say "I'm hijacked!";
$mm.mode = 'normal';
say "Now things are back to normal";

Sets operational mode for the IO::MiddleMan. Valid modes are capture, hijack, mute, and normal. See methods of the corresponding name for the description of the behavior these modes enable.

METHODS

.capture

my $mm = IO::MiddleMan.capture: $*OUT;
say "I'm watching you";

Creates and returns a new IO::MiddleMan object set to capture all the data sent to the IO::Handle given as the positional argument. Any writes to the original IO::Handle will proceed as normal, while also being stored in .data accessor.

.hijack

my $mm = IO::MiddleMan.hijack: $*OUT;
say "Can't see this yet!";

Creates and returns a new IO::MiddleMan object set to hijack all the data sent to the IO::Handle given as the positional argument. Any writes to the original IO::Handle will NOT reach it and instead will be stored in .data accessor.

.mute

my $mm = IO::MiddleMan.mute: $*OUT;
say "You'll never see this!";

Creates and returns a new IO::MiddleMan object set to ignore all the data sent to the IO::Handle given as the positional argument.

.normal

my $mm = IO::MiddleMan.normal: $*OUT;
say "Things look perfectly normal";

Creates and returns a new IO::MiddleMan object set to send all the data sent to the IO::Handle given as the positional argument as it normally would and no capturing of it is to be done.

.Str

say "Captured $mm";

This module overrides the .Str method to return all the captured data as a string.

CAVEATS

The module currently only operates on non-binary data (i.e. write method is still native to IO::Handle). Patches are welcome.

The given filehandle must be a writable container and its contents will be changed to the IO::MiddleMan object, thus possibly complicating some operations.

REPOSITORY

Fork this module on GitHub: https://github.com/raku-community-modules/IO-MiddleMan

BUGS

To report bugs or request features, please use https://github.com/raku-community-modules/IO-MiddleMan/issues

AUTHOR

Zoffix Znet (http://zoffix.com/)

LICENSE

You can use and distribute this module under the terms of the The Artistic License 2.0. See the LICENSE file included in this distribution for complete details.