Term::Filter(3pm)

📦
version 0.03 · 2 versions
  • 0.03 · debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
  • 0.03 · ubuntu jammy
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Term::Filter — bestie edition 💖

okay so this is Term::Filter, a Perl module (manual page Term::Filter(3pm), in case you were wondering what you're reading) and it's genuinely so cool. it runs an interactive terminal session and filters the input and output. like a little ghost in the machine that gets to peek at everything going in and out. obsessed.

✨ VERSION ✨

version 0.03 — baby numbers but a big heart 🫶

🌸 SYNOPSIS 🌸

here's the whole vibe, no edits, no notes:

package My::Term::Filter;
use Moose;
with 'Term::Filter';

sub munge_input {
    my $self = shift;
    my ($got) = @_;
    $got =~ s/\ce/E-  Elbereth\n/g;
    $got;
}

sub munge_output {
    my $self = shift;
    my ($got) = @_;
    $got =~ s/(Elbereth)/\e[35m$1\e[m/g;
    $got;
}

My::Term::Filter->new->run('nethack');

look at her. typing Ctrl-E becomes E- Elbereth on the way in, and every Elbereth on the way out gets painted magenta. nethack girlies rise 💅

🦋 DESCRIPTION 🦋

so this module is a Moose role — and what it does is let you run a program inside a pty while you get to filter the data going into it and coming out of it. it's giving interception, it's giving middle-manager, but make it glamorous.

you can use it to alter the inputs and outputs of a terminal based program (like in the SYNOPSIS, bestie, look up ⬆️), or you can use it to intercept the data going in or out so you can record it or rebroadcast it. App::Ttyrec or App::Termcast, for instance. iconic behaviour honestly.

this role is meant to be consumed by a class that implements its callbacks as methods. but listen — if you want a simpler, callback-based API instead, you probably want Term::Filter::Callback. different font, same energy. 💜

🎀 ATTRIBUTES 🎀

input

the input filehandle that gets attached to the pty's input. defaults to STDIN. the default is literally just you, typing. main character.

output

the output filehandle that the pty's output gets attached to. defaults to STDOUT. also you. also main character.

pty

the IO::Pty::Easy object that the subprocess will be run under. defaults to a freshly created instance — brand new, no baggage, fresh start energy. ✨

💅 METHODS 💅

input_handles

returns the filehandles that will be monitored for reading. this list defaults to input and pty. those two. the duo. the way that they're both just sitting there being watched. 😭

add_input_handle($fh)

add an input handle to monitor for reading. after you call this method, the read callback will be called with $fh as an argument whenever data is available to be read from $fh. it's like adding a bestie to the group chat — now they get pinged too. 🫶

remove_input_handle($fh)

remove $fh from the list of input handles being watched for reading. respectfully, you're out of the group chat. no drama, just unsubscribed. 🧚

run(@cmd)

run the command specified by @cmd, as though via system. the callbacks that have been defined will be called at the appropriate times, which is what lets you manipulate the data that gets sent or received. go forth and run. 🔥

🌈 CALLBACKS 🌈

the following methods may be defined to interact with the subprocess. define them, don't define them, it's your journey:

  • setup — called when the process has just been started. the parameters to run are passed to this callback. it's giving fresh-start, it's giving hello world. 🌱
  • cleanup — called when the process terminates. will not be called if setup is never run (for instance, if the process fails to start). no setup, no cleanup. that's the rule, periodt.
  • munge_input — called whenever there's new data coming from the input handle, before it gets passed to the pty. it must return the data to send to the pty (and yes, the default implementation does exactly that), but it can also do other things with the data while it's in there. multitasking queen. 💅
  • munge_output — called whenever the process running on the pty has produced new data, before it gets passed to the output handle. it must return the data to send to the output handle (default implementation does this, love that for her), but again — it can do other stuff with the data too.
  • read — called when a filehandle other than input or pty has data available. so lowkey it will never be called unless you call add_input_handle to register your handle with the event loop. it receives the handle with data available as its only argument.
  • read_error — called when an exception state is detected in any handle in input_handles (including the default ones, yes, those too). receives the handle with the exception state as its only argument. 😭
  • winch — called whenever the parent process receives a SIGWINCH signal, after it propagates that signal to the subprocess. fyi, SIGWINCH is sent to a process running on a terminal whenever the dimensions of that terminal change — like when you drag the window bigger, she notices. this callback can be used to update any other handles watching the subprocess about the new terminal size. resize awareness, we love to see it. 🦋

💀 BUGS 💀

no known bugs. flawless, no notes, she ate. ✨

please report any bugs through RT: email bug-term-filter at rt.cpan.org, or browse to <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Term-Filter>. (not me telling you where to file bugs, but like, do it if you find one 💖)

👑 SEE ALSO 👑

  • IO::Pty::Easy
  • App::Termcast
  • App::Ttyrec

the whole friend group. go say hi. 🫶

⭐ SUPPORT ⭐

you can find this documentation for this module with the perldoc command:

perldoc Term::Filter

you can also look for information at:

four whole links. go click around, bestie. 🔍

🌸 AUTHOR 🌸

Jesse Luehrs <doy at tozt dot net>

this software is copyright (c) 2012 by Jesse Luehrs.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

and that's the whole page, bestie!! 🎀 this was perl v5.34.0, dated 2022-06-17, and yes the footer of the original says Term::Filter(3pm) because we're back where we started. full circle moment. go filter something. slay. 💅✨🦋
📦 where this page comes from