INSTALLATION
============

To install this module type the following:

    perl Makefile.PL
    make
    make test
    make install


NAME
    Sys::Command - run system commands from Perl

VERSION
    0.01. Development release.

SYNOPSIS
        use Sys::Command qw/run spawn/;

        # Run and give me all the output, raise exception on error:
        my $output = run('git','status');

        # Give me separate lines instead
        my @output = run('git','status');

        # Set working directory, environment, encoding and input
        $output = run(qw/git commit -F -/, {
            input    => 'text',
            env      => { GIT_DIR => '/some/path/.git' },
            dir      => '/some/path/',
            encoding => 'iso-8859-7',
        });

        # Set defaults for a command you call many times:
        my $git = Sys::Command->new(
            cmd => ['git'],
            env   => { GIT_DIR => '/some/path/.git' },
            dir   => '/some/path/',
            encoding => 'iso-8859-7',
        );

        # Exactly same as third run above
        $output = $git->run(qw/commit -f -/, {input => 'text'})

        # Low-level access to the underlying process
        my $process = spawn('other','command');
        $process->input->print("stuff");
        $process->close;
        print "Process exited with value: ". $process->exit;

DESCRIPTION
    Sys::Command allows you to call run external (system) commands from
    Perl. It is intended as a more powerful version of the "system"
    built-in, but at the same time be a simpler version of IPC::Open3,
    IPC::Run and IPC::Cmd.

    Sys::Command uses File::Which internally to discover the location of the
    binary you are trying to run.

  Functional Interface
    Three functions are exported from this module on demand. They all take
    an optional \%opts hashref, which modifies the way the command will be
    run. See the 'encoding', 'env', 'dir', and 'input' attributes of the
    Object interface below for details.

    run($cmd, [@args], [\%opts]) => $output
        run() will simply run the $cmd and @args provided, returning the
        output as a string (in scalar context) or as a list (in
        list-context). It will raise an exception on error. An optional
        \%opts hashref may be given to control how (directory, environment,
        input etc) the command will be called.

    runa($cmd, [@args], [\%opts]) => $out/errput
        runa() is the same as run() except the command's error output is
        appeneded to the normal output.

    spawn($cmd, [@args], [\%opts]) => Sys::Command::Process
        spawn() will run the $cmd and @args with \%opts and return a object
        which can be manipulated to interact with the command. See
        Sys::Command::Process for details.

  Object Interface
    The Object interface is useful if you are calling out to a program like
    Git where you need to manually set the same environment or encoding each
    time. You can instead create a Sys::Command object which holds those
    values as a kind of template. The Sys::Command constructor takes the
    same arguments as Sys::Command::Process with the exception of 'input':

    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.

    An actual process will not be created until you call one of the run(),
    runa() or spawn() _methods_ on your object.

SEE ALSO
    Sys::Command::Process, IPC::Open3, IPC::Run, IPC::Cmd.

SUPPORT
    Bug Reporting
            https://rt.cpan.org/Public/Bug/Report.html?Queue=Sys-Command

    Source Code
            git clone git://github.com/mlawren/sys-command.git

AUTHOR
    Mark Lawrence <nomad@null.net>.

COPYRIGHT AND LICENSE
    Copyright (C) 2011 Mark Lawrence <nomad@null.net>

    This program is free software; you can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by the
    Free Software Foundation; either version 3 of the License, or (at your
    option) any later version.

