NAME

IPC::Open3::Simple - A simple alternative to IPC::Open3

VERSION

$Id: Simple.pm,v 1.7 2006/07/20 13:30:02 erwan Exp $

SYNOPSIS

To run 'ls' in a few directories and put the returned lines in a list:

    my @files;
    my $ipc = IPC::Open3::Simple->new(out => sub { push @files, $_[0]; })
    $ipc->run('ls /etc/');
    $ipc->run('ls /home/erwan/');

To run a 'cvs up' and do different stuff with what cvs writes to stdout and stderr:

    IPC::Open3::Simple->new(out => \&parse_cvs_stdout, err => \&parse_cvs_stderr)->run('cvs up');

DESCRIPTION

IPC::Open3::Simple aims at making it very easy to start a shell command, eventually feed its stdin with some data, then retrieve its stdout and stderr separately.

When you want to run a shell command and parse its stdout/stderr or feed its stdin, you often end up using IPC::Run, IPC::Cmd or IPC::Open3 with your own parsing code, and end up writing more code than you intended. IPC::Open3::Simple is about removing this overhead and making IPC::Open3 easier to use.

IPC::Open3::Simple calls IPC::Open3 and redirects stdin, stdout and stderr to some function references passed in argument to the constructor. It does a select on the input/output filehandles returned by IPC::Open3 and dispatches their content to and from those functions.

INTERFACE

my $runner = IPC::Open3::Simple->new(in => \&sub_in, out => \&sub_out, err => \&sub_err)

Return an object that run commands. Takes no arguments or a hash containing one or more of the keys 'in', 'out' and 'err'. The values of those keys are function references (see method run for details).

$runner->run(@cmds)

Execute the shell commands @cmds. @cmds follows the same syntax as the command arguments of open3 from IPC::Open3.

run creates a process that executes thoses commands, and connects the process's stdin, stdout and stderr to the functions passed in the constructor:

If out was defined in new, every line coming from the process's stdout is passed as first argument to the function reference sub_out. The line is chomped.

If err was defined, the same applies, with lines from the process's stderr being passed to sub_err.

If in was defined, sub_in is called with a filehandle as first argument. Everything written to this filehandle will be sent forward to the process's stdin. sub_in is responsible for calling close() on the filehandle.

run returns only when the command has finished to run.

DIAGNOSTICS

"IPC::Open3::Simple::new expects coderefs"

You called new with 'in', 'err' or 'out' arguments that are not function references.

"ERROR: failed to execute command..."

Open3 failed to run the command passed in @cmds to run.

BUGS AND LIMITATIONS

No bugs so far.

Limitation: IPC::Open3::Simple is not designed for interactive interprocess communication. Do not use it to steer the process opened by open3 via stdin/stdout/stderr, use fork and pipes or some appropriate IPC module for that. IPC::Open3::Simple's scope is to easily run a command, eventually with some stdin input, and get its stdout and stderr along the way, not to interactively communicate with the command.

SEE ALSO

See IPC::Open3, IPC::Run, IPC::Cmd.

COPYRIGHT AND LICENSE

Copyright (C) by Erwan Lemonnier <erwan@cpan.org>

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.