NAME

IO::Filter::External - Filter any IO handle using an external program.

SYNOPSIS

  use IO::Filter::External;

  $io = ...; # any IO handle opened in read mode
  $fio = new IO::Filter::External ($io, "r", "bzip2", "-c");
  # then you can read bzip-compressed bytes from $fio

  $io = ...; # any IO handle opened in write mode
  $fio = new IO::Filter::External ($io, "w", "bzip2", "-cd");
  # write bzip-compressed bytes to $fio

DESCRIPTION

IO::Filter::External is an IO filter (see IO::Filter(3)) which allows you to filter any ordinary Perl IO handle through an arbitrary Unix filter command. (The Unix filter command must be one of those like tr or grep which takes input from STDIN and writes its output to STDOUT).

IO::Filter::External can be used in two modes, read mode or write mode. All IO::Filters are unidirectional, and therefore cannot be used in both read and write mode together.

Here is an example of read mode:

  $io = ...; # any IO handle opened in read mode
  $fio = new IO::Filter::External ($io, "r", "bzip2", "-c");
  # your program reads bzip-compressed bytes from $fio

In read mode, IO::Filter::External behaves conceptually like this:

 your program         external          $io acts as
 reading from  <----- program    <----- the source
 $fio                 (bzip2 -c)        of data

Here is an example of write mode:

  $io = ...; # any IO handle opened in write mode
  $fio = new IO::Filter::External ($io, "w", "bzip2", "-cd");
  # your program writes bzip-compressed bytes to $fio

In write mode, the behaviour is:

 your program         external          $io acts as
 writing to    -----> program    -----> the sink for
 $fio                 (bzip2 -cd)       data

The implementation is somewhat more complex, since it involves forking off two external processes to avoid deadlock. Therefore, you should look at the other classes in the IO::Filter package to see whether a Perl-only optimized implementation exists for the task you are trying to perform. For example, use IO::Filter::uc instead of trying for fork off an external tr program.

METHODS

$fio = new IO::Filter::External ($io, $mode, $cmd [, @args]));
$fio->syswrite ($buffer [, $len [, $offset]]);
$fio->sysread ($buffer [, $len [, $offset]]);
$fio->close;

BUGS

FILES

AUTHORS

Richard Jones (rich@annexia.org)