NAME

       Term::Filter - Run an interactive terminal session, filtering the input and output

VERSION

       version 0.03

SYNOPSIS

         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');

DESCRIPTION

       This module is a Moose role which implements running a program in a pty while being able to filter the
       data that goes into and out of it. This can be used to alter the inputs and outputs of a terminal based
       program (as in the "SYNOPSIS"), or to intercept the data going in or out to record it or rebroadcast it
       (App::Ttyrec or App::Termcast, for instance).

       This role is intended to be consumed by a class which implements its callbacks as methods; for a simpler
       callback-based API, you may want to use Term::Filter::Callback instead.

ATTRIBUTES

   input
       The input filehandle to attach to the pty's input. Defaults to STDIN.

   output
       The output filehandle to attach the pty's output to. Defaults to STDOUT.

   pty
       The IO::Pty::Easy object that the subprocess will be run under. Defaults to a newly created instance.

METHODS

   input_handles
       Returns the filehandles which will be monitored for reading. This list defaults to "input" and "pty".

   add_input_handle($fh)
       Add an input handle to monitor for reading. After calling this method, the "read" callback will be called
       with $fh as an argument whenever data is available to be read from $fh.

   remove_input_handle($fh)
       Remove $fh from the list of input handles being watched for reading.

   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, to allow for manipulating the data that is sent or received.

CALLBACKS

       The following methods may be defined to interact with the subprocess:

       setup
           Called when the process has just been started. The parameters to "run" are passed to this callback.

       cleanup
           Called  when the process terminates. Will not be called if "setup" is never run (for instance, if the
           process fails to start).

       munge_input
           Called whenever there is new data coming from the "input" handle, before it is  passed  to  the  pty.
           Must  return the data to send to the pty (and the default implementation does this), but can do other
           things with the data as well.

       munge_output
           Called whenever the process running on the pty has produced new data, before  it  is  passed  to  the
           "output"  handle. Must return the data to send to the "output" handle (and the default implementation
           does this), but can do other things with the data as well.

       read
           Called when a filehandle other than "input" or "pty" has data available  (so  will  never  be  called
           unless  you call "add_input_handle" to register your handle with the event loop). 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). 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. "SIGWINCH" is sent to a process running on a terminal whenever the dimensions of that
           terminal change. This callback can be used to update any other handles watching the subprocess  about
           the new terminal size.

BUGS

       No known bugs.

       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>.

SEE ALSO

       IO::Pty::Easy

       App::Termcast

       App::Ttyrec

SUPPORT

       You can find this documentation for this module with the perldoc command.

           perldoc Term::Filter

       You can also look for information at:

       •   AnnoCPAN: Annotated CPAN documentation

           <http://annocpan.org/dist/Term-Filter>

       •   CPAN Ratings

           <http://cpanratings.perl.org/d/Term-Filter>

       •   RT: CPAN's request tracker

           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Term-Filter>

       •   Search CPAN

           <http://search.cpan.org/dist/Term-Filter>

AUTHOR

       Jesse Luehrs <doy at tozt dot net>

COPYRIGHT AND LICENSE

       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.

perl v5.34.0                                       2022-06-17                                  Term::Filter(3pm)