NAME

IPC::System::Options - Perl's system(), readpipe()/qx, IPC::Run's run(), start() (with more options)

VERSION

This document describes version 0.341 of IPC::System::Options (from Perl distribution IPC-System-Options), released on 2023-05-24.

SYNOPSIS

use IPC::System::Options qw(system readpipe run start);

# use exactly like system()
system(...);

# use exactly like readpipe() (a.k.a. qx a.k.a. `` a.k.a. the backtick
# operator). if you import readpipe, you'll override the backtick operator with
# this module's version (along with your chosen settings).
my $res = readpipe(...);
$res = `...`;

# but these functions accept an optional hash first argument to specify options
system({...}, ...);
$res = 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
$res = readpipe({shell=>0}, "ls -lR"); # ditto

# force shell, even though there are multiple arguments (arguments will be
# quoted and joined together for you, including proper quoting on Win32).
system({shell=>1}, "perl", "-e", "print 123"); # will print 123
$res = readpipe({shell=>1}, "perl", "-e", "print 123");

# 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"); # fails, because the arguments are quoted so the command becomes: ls '-laR' '>' '/root/ls-laR'
system({shell=>1}, "ls", "-laR", \">", "/root/ls-laR"); # works

# set LC_ALL/LANGUAGE/LANG environment variable
$res = readpipe({lang=>"de_DE.UTF-8"}, "df");

# log using Log::ger, 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');

start() is like run() but uses IPC::Run's start() instead of run() to run program in the background. The result is a handle (see IPC::Run for more details) which you can then call finish(), etc on.

my $h = start('ls', '-l');
...
$h->finish;

DESCRIPTION

This module provides replacement (wrapper) for Perl's system(), readpipe() (qx//, a.k.a. the backtick operator), as well as IPC::Run's start() and run(). The wrappers give you options like forcing/avoiding use of shell (like what IPC::System::Simple offers you), logging the arguments and/or output (using Log::ger), temporarily setting environment variables, temporarily setting working directory, dying on non-zero exit code, capturing (or tee-ing) output (stdout/stderr) (using Capture::Tiny), and a few others. They are meant as a convenience so you can just call system() (or the other wrapper target) instead of doing some additional setup and cleanup yourself.

FUNCTIONS

system

Usage:

system([ \%opts ], @args) => $child_error ($?)

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::ger at the trace level.
fail_log_level => str

When a command fail (and logging is enabled), log the failure message at this level. The default is error which is a sensible default but sometimes you want to log the failure at different 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.
exit_code_success_criteria => int|array[int]|Regexp|code

Specify which command exit codes are to be marked as success. For example, exit code 1 for the diff command does not signify an error; it just means that the two input files are different. So in this case you can either specify one of:
```
exit_code_success_criteria => [0,1]
exit_code_success_criteria => qr/\A(0|1)\z/
exit_code_success_criteria => sub { $_[0] == 0 || $_[0] == 1 }
```
By default, if this option is not specified, non-zero exit codes count as failure.

Currently this only affects logging: when exit code is considered non-success, a warning log is produced and readpipe() does not log the result.

readpipe

Usage:

readpipe([ \%opts ], @args) => $output

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().
exit_code_success_criteria => int|array[int]|Regexp|code

See option documentation in system().

run

Usage:

run([ \%opts ], @args) => $is_success

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|coderef

See option documentation in system().
capture_stderr => scalarref|coderef

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().
exit_code_success_criteria => int|array[int]|Regexp|code

See option documentation in system().

start

Usage:

start([ \%opts ], @args) => $harness

Like run(), but uses IPC::Run's start(). For known options, see run().

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.

AUTHOR

perlancar <perlancar@cpan.org>

CONTRIBUTING

To contribute, you can send patches by email/via RT, or send pull requests on GitHub.

Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via:

% prove -l

If you want to build the distribution (e.g. to try to install it locally on your system), you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond that are considered a bug and can be reported to me.

COPYRIGHT AND LICENSE

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

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.

To install IPC::System::Options, copy and paste the appropriate command in to your terminal.

cpanm

cpanm IPC::System::Options

CPAN shell

perl -MCPAN -e shell
install IPC::System::Options

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

FUNCTIONS

system

readpipe

run

start

HOMEPAGE

SOURCE

SEE ALSO

AUTHOR

CONTRIBUTING

COPYRIGHT AND LICENSE

BUGS

Module Install Instructions