IPC::Run::Simple - Simple system() wrapper
# Run a command and check whether it failed use IPC::Run::Simple; run("echo Hello, O Cruel World") or die "Command failed"; # Describe the failure use IPC::Run::Simple qw($ERR); run("echo Hello, O Cruel World") or die "Command failed: $ERR"; # Use the :all tag instead of explicitly requesting $ERR use IPC::Run::Simple qw(:all); run("echo Hello, O Cruel World") or die "Command failed: $ERR"; # Die with error message if command does not return 0 use IPC::Run::Simple qw(:Fatal); run("echo Hello, O Cruel World"); # Allow other exit values without dying use IPC::Run::Simple qw(:Fatal); run(command => [ "echo", "Hello, O Cruel World!" ], allowed => [ 1, 2, 5 ]);
This module is intended to be a very simple, straightforward wrapper around the system() call to make it behave more like other builtins.
system()
run() will return a true value if the command was executed and return a successful status code, and false otherwise. The reason for the failure will be stored in the $IPC::Run::Simple::ERR variable (which is just $ERR if you import either $ERR or :all). The description of the reason was pulled almost directly from the system() documentation.
run()
$IPC::Run::Simple::ERR
$ERR
:all
Optionally, you can import the :Fatal tag, which will cause run() to die() with an appropriate message if the command fails for any reason.
:Fatal
die()
If you wish to allow nonzero exit values but still want to trap unexpected errors, you may use an expanded call syntax. Call run() with a set of key=>value pairs. The two implemented keys are command (an array reference containing the command to run) and allowed (an array reference of exit values that are allowed without causing run() to return false or throw an exception.)
command
allowed
This module was inspired by a thread on PerlMonks, where pjf asked whether there was a simple system() wrapper: http://www.perlmonks.org/?node_id=557107
In response, I wrote this module.
By default, the run() function is exported into the caller's namespace. $ERR can be optionally exported. The :all tag will export both run() and $ERR.
The :Fatal tag will cause all errors to be fatal.
The $ERR variable is shared by all packages. So if package A calls run("a"), which sets $ERR, and then calls b_func(), which is defined in package B and calls run("b"), then after b_func() returns $ERR will no longer be set to the value resulting from the run("a"); its value will have been overwritten by the call to run("b")..
run("a")
b_func()
run("b")
IPC::Run3 also uses true/false to indicate success or failure, and also implements several other features (it aims to replace system(), backticks, and piped opens, whereas this module is purely a wrapper for system().)
IPC::Run handles everything that this module does, everything that IPC::Run3 does, and will attempt to embed a microcontroller in your kitchen sink if you let it.
IPC::Cmd is similar to (and can use) IPC::Run3, but can also work via IPC::Open3 or builtin code.
All of the above have been tested on Windows, unlike this module.
Steve Fink <sfink@cpan.org>
Ricardo SIGNES pointed out a bug resulting from misuse of a package-scoped $Fatal variable.
$Fatal
Copyright (C) 2006 by Steve Fink
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.5 or, at your option, any later version of Perl 5 you may have available.
To install IPC::Run::Simple, copy and paste the appropriate command in to your terminal.
cpanm
cpanm IPC::Run::Simple
CPAN shell
perl -MCPAN -e shell install IPC::Run::Simple
For more information on module installation, please visit the detailed CPAN module installation guide.