NAME

Sys::Command::Process - objects that represent a command process

VERSION

0.04 Development release.

SYNOPSIS

use Sys::Command::Process;

# start a system process and return an object
my $proc = Sys::Command::Process->new(
    cmd => \@cmd,
    env => { SOME => 'VALUE' },
    dir => 'here',
);

# Interact with the command via its STDIN, STDERR etc.
if ($proc->pid) {
    while (my $line = $proc->stdout) {
        $proc->stdin->print("next input");
    }
}
my @errors = $proc->stderr->getlines;

# done!
$proc->close();

# exit information
$proc->exit();      # exit status
$proc->signal();    # signal
$proc->core();      # core dumped? (boolean)

DESCRIPTION

Sys::Command::Process lets you run a system command and interact with it through its STDIN, STDOUT, and STDERR file handles.

This module is intended to be invoked through Sys::Command.

CONSTRUCTOR

new(%args) => Sys::Command::Process

Spawns a process based on %args. %args must contain at least a 'cmd' value, and optionally 'encoding', 'env', 'dir' and 'input' values as defined as attributes below.

ATTRIBUTES

cmd

An array ref containing the command and its arguments.

encoding

An string value identifying the encoding of the input/output file-handles. Defaults to 'utf8'.

env

A hashref containing the run-time environment key/values.

dir

The working directory the command will be run in.

input

A string which is fed to the command via its standard input, which is then closed. This is a shortcut for printing to, and closing the commands stdin file-handle. An empty string will close the command's standard input without writing to it. On some systems, some commands may close standard input on startup, which will cause a SIGPIPE when trying to write to it. This will raise an exception.

pid

The command's process ID.

stdin

The command's STDIN file handle, based on IO::Handle so you can call getline(), print() etc on it.

stdout

The command's STDOUT file handle, based on IO::Handle so you can call getline(), print() etc on it.

stderr

The command's STDERR file handle, based on IO::Handle so you can call getline(), print() etc on it.

exit

The command's exit value, shifted by 8 (see "perldoc -f system"). Set only after the close() method has been called.

signal

The signal (if any) that terminated the command, bitwise-added with 127 (see "perldoc -f system"). Set only after the close() method has been called.

signal

The signal number (if any) that terminated the command, bitwise-added with 127 (see "perldoc -f system"). Set only after the close() method has been called.

core

A boolean indicating the process core was dumped. Set only after the close() method has been called.

METHODS

cmd_line => @list

Returns a list of the command and its arguments.

cmdline => $str

Returns a string of the command and its arguments separated by spaces.

close()

Close all pipes to the child process, and collects exit status, etc. and defines a number of attributes (see above).

Note that close() is automatically called when the Sys::Command::Process object is destroyed. Annoyingly, this means that in the following example $fh will be closed when you tried to use it:

my $fh = Sys::Command::Process->new( %args )->stdout;

So you have to keep track of the Sys::Command::Process object manually.

AUTHOR

Mark Lawrence <nomad@null.net>, based heavily on Git::Repository::Command by Philippe Bruhat (BooK), <book at cpan.org>

COPYRIGHT

Copyright 2011 Mark Lawrence

LICENSE

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