NAME

IPC::Run::Simple - Simple system() wrapper

SYNOPSIS

  # 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 ]);

DESCRIPTION

This module is intended to be a very simple, straightforward wrapper around the system() call to make it behave more like other builtins.

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.

Optionally, you can import the :Fatal tag, which will cause run() to die() with an appropriate message if the command fails for any reason.

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

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.

EXPORT

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.

BUGS AND LIMITATIONS

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

SEE ALSO

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.

AUTHOR

Steve Fink <sfink@cpan.org>

Ricardo SIGNES pointed out a bug resulting from misuse of a package-scoped $Fatal variable.

COPYRIGHT AND LICENSE

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.