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>.
SEE ALSO
IPC::System::Simple also provides wrapper for "system()" and
"readpipe()" with some additional behavior, although its scope is not as
extensive as IPC::System::Options.
Proc::Govern similarly provide a run+options function, with a different
set of options, including system load watching, logging output to file,
disabling and screensaver or power management.
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 software is copyright (c) 2023, 2021, 2020, 2019, 2017, 2016, 2015
by perlancar <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.
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.