README

NAME
    Sys::Cmd - run a system command or spawn a system processes

VERSION
    0.99.1_1 (yyyy-mm-dd)

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

        # Get command output, raise exception on failure:
        $output = run(@cmd);

        # Feed command some input, get output as lines,
        # raise exception on failure:
        @output = run( @cmd, { input => 'feedme' } );

        # Spawn and interact with a process somewhere else:
        $proc = spawn(
            @cmd,
            {
                dir      => '/',
                encoding => 'encoding(iso-8859-3)'
            },
        );

        while ( my $line = $proc->stdout->getline ) {
            $proc->stdin->print("thanks\n");
        }

        my @errors = $proc->stderr->getlines;

        $proc->close();         # Finished talking to file handles
        $proc->wait_child();    # Cleanup

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

DESCRIPTION
    Sys::Cmd lets you run system commands and capture their output, or
    spawn and interact with a system process through its "STDIN",
    "STDOUT", and "STDERR" file handles. The following functions are
    exported on demand by this module:

    run( @cmd, [\%opt] ) => $output | @output
        Execute @cmd and return what the command sent to its "STDOUT",
        raising an exception in the event of error. In array context
        returns a list instead of a plain string.

        The first element of @cmd determines what/how things are run:

        *   If it is a relative file name it is executed directly using
            Proc::Spawn.

        *   If it is a CODE reference (subroutine) Sys::Cmd forks before
            running it in the child process. This is not supported on
            Win32.

        *   Everything else is looked up using File::Which and then
            executed with Proc::Spawn.

        The command input and environment can be modified with an
        optional hashref containing the following key/values:

        dir The working directory the command will be run in.

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

        env A hashref containing key/values to be added to the current
            environment at run-time. If a key has an undefined value
            then the key is removed from the environment altogether.

        input
            A string which is fed to the command via its standard input,
            which is then closed.

    runx( @cmd, [\%opt] ) => $outerrput | @outerrput
        The same as the "run" function but with the command's "STDERR"
        output appended to the "STDOUT" output.

    spawn( @cmd, [\%opt] ) => Sys::Cmd
        Return a Sys::Cmd object (documented below) representing the
        process running @cmd, with attributes set according to the
        optional \%opt hashref. The first element of @cmd determines the
        execution method just like the "run()" function.

    Sys::Cmd objects can of course be created using the standard "new"
    constructor if you prefer that to the "spawn" function:

        $proc = Sys::Cmd->new(
            cmd => \@cmd,
            dir => '/',
            env => { SOME => 'VALUE' },
            enc => 'iso-8859-3',
            input => 'feedme',
            on_exit => sub {
                my $proc = shift;
                print $proc->pid .' exited with '. $proc->exit;
            },
        );

    Note that Sys::Cmd objects created this way will not lookup the
    command using File::Which the way the "run", "runx" and "spawn"
    functions do. CODE references in $cmd[0] are however still
    recognized and forked off.

    Sys::Cmd uses Log::Any "debug" calls for logging purposes. An easy
    way to see the output is to add "use Log::Any::Adapter 'Stdout'" in
    your program.

CONSTRUCTOR
    new(%args) => Sys::Cmd
        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.

        If an "on_exit" subref argument is provided it will be called by
        the "wait_child" method, which can either be called manually or
        will be automatically called when the object is destroyed.

ATTRIBUTES
    All attributes are read-only.

    cmd An array ref containing the command or CODE reference (UNIX
        only) and its arguments.

    dir The working directory the command will be run in.

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

    env A hashref containing key/values to be added to the current
        environment at run-time. If a key has an undefined value then
        the key is removed from the environment altogether.

    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 command's *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 for which
        Sys::Cmd will warn.

    pid The command's process ID.

    stdin
        The command's *STDIN* file handle, based on IO::Handle so you
        can call print() etc methods on it. Autoflush is automatically
        enabled on this handle.

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

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

    exit
        The command's exit value, shifted by 8 (see "perldoc -f
        system"). Set by "wait_child()".

    signal
        The signal number (if any) that terminated the command,
        bitwise-added with 127 (see "perldoc -f system"). Set by
        "wait_child()".

    core
        A boolean indicating the process core was dumped. Set by
        "wait_child()".

METHODS
    cmdline => @list | $str
        In array context returns a list of the command and its
        arguments. In scalar context returns a string of the command and
        its arguments joined together by spaces.

    close()
        Close all filehandles to the child process. Note that file
        handles will automaticaly be closed when the Sys::Cmd object is
        destroyed. Annoyingly, this means that in the following example
        $fh will be closed when you tried to use it:

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

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

    wait_child() -> $exit_value
        Wait for the child to exit using waitpid
        <http://perldoc.perl.org/functions/waitpid.html>, collect the
        exit status and return it. This method sets the *exit*, *signal*
        and *core* attributes and will also be called automatically when
        the Sys::Cmd object is destroyed.

SEE ALSO
    Sys::Cmd::Template

ALTERNATIVES
    AnyEvent::Run, AnyEvent::Util, Argv, Capture::Tiny, Child,
    Forks::Super, IO::Pipe, IPC::Capture, IPC::Cmd,
    IPC::Command::Multiplex, IPC::Exe, IPC::Open3, IPC::Open3::Simple,
    IPC::Run, IPC::Run3, IPC::RunSession::Simple, IPC::ShellCmd,
    IPC::System::Simple, POE::Pipe::TwoWay, Proc::Background,
    Proc::Fork, Proc::Spawn, Spawn::Safe, System::Command

SUPPORT
    This distribution is managed via github:

        https://github.com/mlawren/sys-cmd/tree/devel

    This distribution follows the semantic versioning model:

        http://semver.org/

    Code is tidied up on Git commit using githook-perltidy:

        http://github.com/mlawren/githook-perltidy

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

COPYRIGHT AND LICENSE
    Copyright 2011-2021 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.