NAME

IPC::Simple - simple, non-blocking IPC

VERSION

version 0.02

SYNOPSIS

  use IPC::Simple;

  my $ssh = IPC::Simple->new(
    cmd  => 'ssh',
    args => [ $host ],
    eol  => "\n",
  );

  if ($ssh->launch) {
    $ssh->send('ls -lah');          # get directory listing
    $ssh->send('echo');             # signal our loop that the listing is done

    while (my $msg = $ssh->recv) {  # echo's output will be an empty string
      if ($msg->error) {            # I/O error
        croak $msg;
      }
      elsif ($msg->stderr) {        # output to STDERR
        warn $msg;
      }
      elsif ($msg->stdout) {        # output to STDOUT
        say $msg;
      }
    }

    $ssh->send('exit');             # terminate the connection
    $ssh->join;                     # wait for the process to terminate
  }

DESCRIPTION

Provides a simplified interface for managing and kibbitzing with a child process.

METHODS

new

Creates a new IPC::Simple process object. The process is not immediately launched; see "launch".

constructor arguments

cmd

The command to launch in a child process.

args

An array ref of arguments to cmd.

eol

The end-of-line character to print at the end of each call to "send". Defaults to "\n".

pid

Once launched, returns the pid of the child process.

exit_status

Once a child process exits, this is set to the exit status ($?) of the child process.

exit_code

Once a child process has terminated, this is set to the exit code of the child process.

launch

Starts the child process. Returns true on success, croaks on failure to launch the process.

terminate

Sends the child process a `SIGTERM`. Returns immediately. Use "join" to wait for the process to finish.

join

Blocks until the child process has exited.

send

Sends a string of text to the child process. The string will be appended with a single newline.

recv

Waits for and returns the next line of output from the process, which may be from STDOUT, from STDERR, or it could be an error message resulting from an I/O error while communicating with the process (e.g. a SIGPIPE or abnormal termination).

Each message returned by recv is an object overloaded so that it can be treated as a string as well as providing the following methods:

async

Schedules a callback for the next line of input to be received, returning immediately.

  $proc->async(sub{
    my $msg = shift;

    if ($msg->stdout) {
      ...
    }
  });

This is done with "CONDITION-VARIABLES" in AnyEvent, so the same caveats about races and dead locks apply. It is up to the caller to manage their event loop.

stdout

True when the message came from the child process' STDOUT.

stderr

True when the message came from the child process' STDERR.

error

True when the message is a sub-process communication error.

DEBUGGING

IPC::Simple will emit highly verbose messages to STDERR if the environment variable IPC_SIMPLE_DEBUG is set to a true value.

AUTHOR

Jeff Ober <sysread@fastmail.fm>

COPYRIGHT AND LICENSE

This software is copyright (c) 2020 by Jeff Ober.

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

cpanm IPC::Simple

perl -MCPAN -e shell
install IPC::Simple