SYNOPSIS

     use IPC::System::Options qw(system readpipe run);
    
     # use exactly like system()
     system(...);
    
     # use exactly like readpipe() (a.k.a. qx a.k.a. `` a.k.a. the backtick operator)
     my $res = readpipe(...);
     $res = `...`;
    
     # but these functions accept an optional hash first argument to specify options
     system({...}, ...);
     readpipe({...}, ...);
    
     # run without shell, even though there is only one argument
     system({shell=>0}, "ls");
     system({shell=>0}, "ls -lR"); # will fail, as there is no 'ls -lR' binary
    
     # force shell, even though there are multiple arguments (arguments will be
     # quoted for you, including proper quoting on Win32)
     system({shell=>1}, "ls", "-lR");
    
     # set LC_ALL/LANGUAGE/LANG environment variable
     $res = readpipe({lang=>"de_DE.UTF-8"}, "df");
    
     # log using Log::Any, die on failure
     system({log=>1, die=>1}, "blah", ...);

    Set default options for all calls (prefix each option with dash):

     use IPC::System::Options 'system', 'readpipe', -log=>1, -die=>1;

    run() is like system() but uses IPC::Run's run() instead of system():

     run('ls');
    
     # also accepts an optional hash first argument. some additional options that
     # run() accepts: stdin.
     run({capture_stdout => \$stdout, capture_stderr => \$stderr}, 'ls', '-l');

DESCRIPTION

FUNCTIONS

 system([ \%opts ], @args)

    Just like perl's system() except that it accepts an optional hash first
    argument to specify options. Currently known options:

      * shell => bool

      Can be set to 0 to always avoid invoking the shell. The default is to
      use the shell under certain conditions, like perl's system(). But
      unlike perl's system(), you can force shell usage even though you
      pass multiple arguments (in which case, the arguments will be quoted
      for you, including proper quoting on Win32).

      * lang => str

      Temporarily set locale-related environment variables: LC_ALL (this is
      the highest precedence, even higher than the other LC_* variables
      including LC_MESSAGES), LANGUAGE (this is used in Linux, with
      precedence higher than LANG but lower than LC_*), and LANG.

      Of course you can set the environment variables manually (or use the
      env option), this option is just for convenience.

      * env => hashref

      Temporarily set environment variables.

      * log => bool

      If set to true, then will log invocation as well as return/result
      value. Will log using Log::Any at the trace level.

      * die => bool

      If set to true, will die on failure.

      * capture_stdout => scalarref

      Capture stdout using Capture::Tiny.

      * capture_stderr => scalarref

      Capture stderr using Capture::Tiny.

 readpipe([ \%opts ], @args)

    Just like perl's readpipe() (a.k.a. qx() a.k.a. `` a.k.a. the backtick
    operator) except that it accepts an optional hash first argument to
    specify options. And it can accept multiple arguments (in which case,
    the arguments will be quoted for you, including proper quoting on
    Win32).

    Known options:

      * lang => str

      See option documentation in system().

      * env => hash

      See option documentation in system().

      * log => bool

      See option documentation in system().

      * die => bool

      See option documentation in system().

      * capture_stdout => scalarref

      See option documentation in system().

      * capture_stderr => scalarref

      See option documentation in system().

      * max_log_output => int

      If set, will limit result length being logged. It's a good idea to
      set this (e.g. to 1024) if you expect some command to return large
      output.

 run([ \%opts ], @args)

    Like system(), but uses IPC::Run's run(). Known options:

      * lang => str

      See option documentation in system().

      * env => hash

      See option documentation in system().

      * log => bool

      See option documentation in system().

      * die => bool

      See option documentation in system().

      * capture_stdout => scalarref

      See option documentation in system().

      * capture_stderr => scalarref

      See option documentation in system().

      * stdin => scalar

      Supply standard input.