.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "Term::Filter 3pm" .TH Term::Filter 3pm "2017-01-02" "perl v5.24.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Term::Filter \- Run an interactive terminal session, filtering the input and output .SH "VERSION" .IX Header "VERSION" version 0.03 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& package My::Term::Filter; \& use Moose; \& with \*(AqTerm::Filter\*(Aq; \& \& sub munge_input { \& my $self = shift; \& my ($got) = @_; \& $got =~ s/\ece/E\- Elbereth\en/g; \& $got; \& } \& \& sub munge_output { \& my $self = shift; \& my ($got) = @_; \& $got =~ s/(Elbereth)/\ee[35m$1\ee[m/g; \& $got; \& } \& \& My::Term::Filter\->new\->run(\*(Aqnethack\*(Aq); .Ve .SH "DESCRIPTION" .IX Header "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 \*(L"\s-1SYNOPSIS\*(R"\s0), or to intercept the data going in or out to record it or rebroadcast it (App::Ttyrec or App::Termcast, for instance). .PP This role is intended to be consumed by a class which implements its callbacks as methods; for a simpler callback-based \s-1API,\s0 you may want to use Term::Filter::Callback instead. .SH "ATTRIBUTES" .IX Header "ATTRIBUTES" .SS "input" .IX Subsection "input" The input filehandle to attach to the pty's input. Defaults to \s-1STDIN.\s0 .SS "output" .IX Subsection "output" The output filehandle to attach the pty's output to. Defaults to \s-1STDOUT.\s0 .SS "pty" .IX Subsection "pty" The IO::Pty::Easy object that the subprocess will be run under. Defaults to a newly created instance. .SH "METHODS" .IX Header "METHODS" .SS "input_handles" .IX Subsection "input_handles" Returns the filehandles which will be monitored for reading. This list defaults to \f(CW\*(C`input\*(C'\fR and \f(CW\*(C`pty\*(C'\fR. .SS "add_input_handle($fh)" .IX Subsection "add_input_handle($fh)" Add an input handle to monitor for reading. After calling this method, the \&\f(CW\*(C`read\*(C'\fR callback will be called with \f(CW$fh\fR as an argument whenever data is available to be read from \f(CW$fh\fR. .SS "remove_input_handle($fh)" .IX Subsection "remove_input_handle($fh)" Remove \f(CW$fh\fR from the list of input handles being watched for reading. .SS "run(@cmd)" .IX Subsection "run(@cmd)" Run the command specified by \f(CW@cmd\fR, as though via \f(CW\*(C`system\*(C'\fR. The callbacks that have been defined will be called at the appropriate times, to allow for manipulating the data that is sent or received. .SH "CALLBACKS" .IX Header "CALLBACKS" The following methods may be defined to interact with the subprocess: .IP "setup" 4 .IX Item "setup" Called when the process has just been started. The parameters to \f(CW\*(C`run\*(C'\fR are passed to this callback. .IP "cleanup" 4 .IX Item "cleanup" Called when the process terminates. Will not be called if \f(CW\*(C`setup\*(C'\fR is never run (for instance, if the process fails to start). .IP "munge_input" 4 .IX Item "munge_input" Called whenever there is new data coming from the \f(CW\*(C`input\*(C'\fR 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. .IP "munge_output" 4 .IX Item "munge_output" Called whenever the process running on the pty has produced new data, before it is passed to the \f(CW\*(C`output\*(C'\fR handle. Must return the data to send to the \&\f(CW\*(C`output\*(C'\fR handle (and the default implementation does this), but can do other things with the data as well. .IP "read" 4 .IX Item "read" Called when a filehandle other than \f(CW\*(C`input\*(C'\fR or \f(CW\*(C`pty\*(C'\fR has data available (so will never be called unless you call \f(CW\*(C`add_input_handle\*(C'\fR to register your handle with the event loop). Receives the handle with data available as its only argument. .IP "read_error" 4 .IX Item "read_error" Called when an exception state is detected in any handle in \f(CW\*(C`input_handles\*(C'\fR (including the default ones). Receives the handle with the exception state as its only argument. .IP "winch" 4 .IX Item "winch" Called whenever the parent process receives a \f(CW\*(C`SIGWINCH\*(C'\fR signal, after it propagates that signal to the subprocess. \f(CW\*(C`SIGWINCH\*(C'\fR 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. .SH "BUGS" .IX Header "BUGS" No known bugs. .PP Please report any bugs through \s-1RT:\s0 email \&\f(CW\*(C`bug\-term\-filter at rt.cpan.org\*(C'\fR, or browse to . .SH "SEE ALSO" .IX Header "SEE ALSO" IO::Pty::Easy .PP App::Termcast .PP App::Ttyrec .SH "SUPPORT" .IX Header "SUPPORT" You can find this documentation for this module with the perldoc command. .PP .Vb 1 \& perldoc Term::Filter .Ve .PP You can also look for information at: .IP "\(bu" 4 AnnoCPAN: Annotated \s-1CPAN\s0 documentation .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Ratings .Sp .IP "\(bu" 4 \&\s-1RT: CPAN\s0's request tracker .Sp .IP "\(bu" 4 Search \s-1CPAN\s0 .Sp .SH "AUTHOR" .IX Header "AUTHOR" Jesse Luehrs .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2012 by Jesse Luehrs. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.