IPC::System::Options - Perl's system() and readpipe/qx replacement, with options
This document describes version 0.333 of IPC::System::Options (from Perl distribution IPC-System-Options), released on 2019-11-23.
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) 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::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()
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.
start()
finish()
my $h = start('ls', '-l'); ... $h->finish;
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.
LC_ALL
LC_*
LC_MESSAGES
LANGUAGE
LANG
Of course you can set the environment variables manually (or use the env option), this option is just for convenience.
env
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.
trace
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.
tee_*
capture_merged
capture_stderr => scalarref
Capture stderr using Capture::Tiny.
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.
capture_stdout
capture_stderr
tee_stdout => scalarref
Tee stdout using Capture::Tiny.
Cannot be used together with capture_* or tee_merged.
capture_*
tee_merged
tee_stderr => scalarref
tee_merged => scalarref
Cannot be used together with capture_*, tee_stdout, or tee_stderr.
tee_stdout
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.
die
$!
chdir()
$?
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.
warn
log
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.
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).
readpipe()
qx()
``
Known options:
See option documentation in system().
env => hash
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.
Like system(), but uses IPC::Run's run(). Known options:
stdin => scalar
Supply standard input.
Like run(), but uses IPC::Run's start(). For known options, see run().
Please visit the project's homepage at https://metacpan.org/release/IPC-System-Options.
Source repository is at https://github.com/perlancar/perl-IPC-System-Options.
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.
perlancar <perlancar@cpan.org>
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.
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.