NAME
    IPC::System::Options - Perl's system() and readpipe/qx replacement, with
    options

VERSION
    This document describes version 0.331 of IPC::System::Options (from Perl
    distribution IPC-System-Options), released on 2019-01-07.

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", "-laR");

     # note that to prevent the quoting mechanism from quoting some special
     # characters (like ">") you can use scalar references, e.g.:
     system({shell=>1}, "ls", "-laR", \">", "/root/ls-laR");

     # 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", ...);

     # chdir first before running program (and chdir back afterwards)
     system({chdir => "/tmp", die => 1}, "some-program");

    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.

        Cannot be used together with "tee_*" or "capture_merged".

    *   capture_stderr => scalarref

        Capture stderr using Capture::Tiny.

        Cannot be used together with "tee_*" or "capture_merged".

    *   capture_merged => scalarref

        Capture stdout and stderr in a single variable using Capture::Tiny's
        "capture_merged".

        Cannot be used together with "tee_*", "capture_stdout", or
        "capture_stderr".

    *   tee_stdout => scalarref

        Tee stdout using Capture::Tiny.

        Cannot be used together with "capture_*" or "tee_merged".

    *   tee_stderr => scalarref

        Capture stderr using Capture::Tiny.

        Cannot be used together with "capture_*" or "tee_merged".

    *   tee_merged => scalarref

        Capture stdout and stderr in a single variable using Capture::Tiny's
        "capture_merged".

        Cannot be used together with "capture_*", "tee_stdout", or
        "tee_stderr".

    *   chdir => str

        Attempt to change to specified directory first and change back to
        the original directory after the command has been run. This is a
        convenient option so you can do this kind of task in a single call:

         {
             my $cwd = getcwd();
             chdir $dir or die;
             system(...);
             chdir $cwd or die;
         }

        If the attempt to chdir before command execution fails, will die if
        "die" option is set to true. Otherwise, $! (OS error) will be set to
        the "chdir()" error and to minimize surprise $? (child exit code)
        will also be set to non-zero value (-1) even though at this point no
        child process has been run.

        If the attempt to chdir back (after command execution) fails, will
        die if "die" option is set to true. Otherwise, $! will be set to the
        "chdir()" error and $? will be set to -1 only if $? is zero. So if
        the command fails, $? will contain the exit code of the command.

    *   dry_run => bool

        If set to true, then will only display what would be executed to
        STDERR (or log at "warn" level, if "log" option is true) instead of
        actually executing the command.

        Will set $? (child exit code) to 0.

        An example of how this option can be used:

         system({ dry_run => $ENV{DRY_RUN} }, ...);

        This will allow you to run script in dry-run mode by setting
        environment variable.

  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()".

    *   capture_merged => scalarref

        See option documentation in "system()".

    *   tee_stdout => scalarref

        See option documentation in "system()".

    *   tee_stderr => scalarref

        See option documentation in "system()".

    *   tee_merged => 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.

    *   chdir => str

        See option documentation in "system()".

    *   dry_run => bool

        See option documentation in "system()".

  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()".

    *   capture_merged => scalarref

        See option documentation in "system()".

    *   tee_stdout => scalarref

        See option documentation in "system()".

    *   tee_stderr => scalarref

        See option documentation in "system()".

    *   tee_merged => scalarref

        See option documentation in "system()".

    *   stdin => scalar

        Supply standard input.

    *   chdir => str

        See option documentation in "system()".

    *   dry_run => bool

        See option documentation in "system()".

HOMEPAGE
    Please visit the project's homepage at
    <https://metacpan.org/release/IPC-System-Options>.

SOURCE
    Source repository is at
    <https://github.com/perlancar/perl-IPC-System-Options>.

BUGS
    Please report any bugs or feature requests on the bugtracker website
    <https://rt.cpan.org/Public/Dist/Display.html?Name=IPC-System-Options>

    When submitting a bug or request, please include a test-file or a patch
    to an existing test-file that illustrates the bug or desired feature.

AUTHOR
    perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2019, 2017, 2016, 2015 by
    perlancar@cpan.org.

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

