ActiveState::Run - Collection of small utility functions


NAME

ActiveState::Run - Collection of small utility functions


SYNOPSIS

 use ActiveState::Run qw(run);
 run("ls -l");


DESCRIPTION

This module provides a collection of small utility functions for running external programs.

The following functions are provided:

decode_status( )
decode_status( $rc )

Will decode the given return code (defaults to $?) and return the exit value, the signal it was killed with, and if it dumped core.

In scalar context, it will return a string explaining what happened, or an empty string if no error occured.

  my $foo = `ls`;
  my $err = decode_status;
  die "ls failed: $err" if $err;

In array context, it will return a list of key/value pairs containing:

WIFEXITED

True when the status code indicates normal termination.

WEXITSTATUS

If WIFEXITED, this will contain the low-order 8 bits of the status value the child passed to exit or returned from main.

WIFSIGNALED

Non-zero if process was terminated by a signal.

WTERMSIG

If WIFSIGNALED, the terminating signal.

WIFSTOPPED

Non-zero if the process was stopped.

WSTOPSIG

If WIFSTOPPED, the signal that stopped the process.

WCOREDUMP

Nonzero if the process dumped core.

Example:

  my $foo = `ls`;
  my %err = decode_status;
  die "ls dumped core" if $err{WCOREDUMP};
run( $cmd, @args )

Works like the builtin system() but will by default print commands to stdout before it execute them and raise an exception (die) if the command fails (returns non-zero status). Like for the command specifications for make(1), you can prefix the command with "@" to suppress the echo and with "-" to suppress the status check.

The environment variables AS_RUN_SILENT and AS_RUN_PREFIX influence printing as well, see ENVIRONMENT.

shell_quote( @args )

Will quote the arguments provided so that they can be passed to the command shell without interpretation by the shell. This is useful with run() when you can't provide separate @args, e.g.:

   run(shell_quote("rm", "-f", @files) . " >dev/null");

In list context it returns the same number of values as arguments passed in. Only those arg values that need quoting will be quoted.

In scalar context it will return a single string with all the quoted @args separated by space.

In void context it will attempt inline modification of the @args passed.


ENVIRONMENT

If the AS_RUN_SILENT environment variable is TRUE, then printing of the command about to run for run() is suppressed.

If the AS_RUN_PREFIX environment variable is set, then the printed command is prefixed with the given string. If AS_RUN_SILENT is TRUE, then this value is ignored.


BUGS

none.