javonet-ruby-sdk 2.4.10 → 2.4.11

data/lib/javonet-ruby-sdk/Binaries/Perl/MacOs/X64/deps/lib/perl5/IPC/System/Simple.pm

@@ -1,1115 +0,0 @@
-package IPC::System::Simple;
-
-# ABSTRACT: Run commands simply, with detailed diagnostics
-
-use 5.006;
-use strict;
-use warnings;
-use re 'taint';
-use Carp;
-use List::Util qw(first);
-use Scalar::Util qw(tainted);
-use Config;
-use constant WINDOWS => ($^O eq 'MSWin32');
-use constant VMS     => ($^O eq 'VMS');
-
-BEGIN {
-
-    # It would be lovely to use the 'if' module here, but it didn't
-    # enter core until 5.6.2, and we want to keep 5.6.0 compatibility.
-
-
-    if (WINDOWS) {
-
-        ## no critic (ProhibitStringyEval)
-
-        eval q{
-            use Win32::Process qw(INFINITE NORMAL_PRIORITY_CLASS);
-            use File::Spec;
-            use Win32;
-            use Win32::ShellQuote;
-
-            # This uses the same rules as the core win32.c/get_shell() call.
-            use constant WINDOWS_SHELL => eval { Win32::IsWinNT() }
-                ? [ File::Spec->catfile(Win32::GetFolderPath(Win32::CSIDL_SYSTEM), 'cmd.exe'), '/x/d/c' ]
-                : [ File::Spec->catfile(Win32::GetFolderPath(Win32::CSIDL_SYSTEM), 'command.com'), '/c' ];
-
-            # These are used when invoking _win32_capture
-            use constant NO_SHELL  => 0;
-            use constant USE_SHELL => 1;
-
-        };
-
-        ## use critic
-
-        # Die nosily if any of the above broke.
-        die $@ if $@;
-    }
-}
-
-# Note that we don't use WIFSTOPPED because perl never uses
-# the WUNTRACED flag, and hence will never return early from
-# system() if the child processes is suspended with a SIGSTOP.
-
-use POSIX qw(WIFEXITED WEXITSTATUS WIFSIGNALED WTERMSIG);
-
-use constant FAIL_START     => q{"%s" failed to start: "%s"};
-use constant FAIL_PLUMBING  => q{Error in IPC::System::Simple plumbing: "%s" - "%s"};
-use constant FAIL_CMD_BLANK => q{Entirely blank command passed: "%s"};
-use constant FAIL_INTERNAL  => q{Internal error in IPC::System::Simple: "%s"};
-use constant FAIL_TAINT     => q{%s called with tainted argument "%s"};
-use constant FAIL_TAINT_ENV => q{%s called with tainted environment $ENV{%s}};
-use constant FAIL_SIGNAL    => q{"%s" died to signal "%s" (%d)%s};
-use constant FAIL_BADEXIT   => q{"%s" unexpectedly returned exit value %d};
-
-use constant FAIL_UNDEF     => q{%s called with undefined command};
-
-
-use constant FAIL_POSIX     => q{IPC::System::Simple does not understand the POSIX error '%s'.  Please check https://metacpan.org/pod/IPC::System::Simple to see if there is an updated version.  If not please report this as a bug to https://github.com/pjf/ipc-system-simple/issues};
-
-# On Perl's older than 5.8.x we can't assume that there'll be a
-# $^{TAINT} for us to check, so we assume that our args may always
-# be tainted.
-use constant ASSUME_TAINTED => ($] < 5.008);
-
-use constant EXIT_ANY_CONST => -1;			# Used internally
-use constant EXIT_ANY       => [ EXIT_ANY_CONST ];	# Exported
-
-use constant UNDEFINED_POSIX_RE => qr{not (?:defined|a valid) POSIX macro|not implemented on this architecture};
-
-require Exporter;
-our @ISA = qw(Exporter);
-
-our @EXPORT_OK = qw( 
-    capture  capturex
-    run      runx
-    system   systemx
-    $EXITVAL EXIT_ANY
-);
-
-our $VERSION = '1.30';
-$VERSION =~ tr/_//d;
-
-our $EXITVAL = -1;
-
-my @Signal_from_number = split(' ', $Config{sig_name});
-
-# Environment variables we don't want to see tainted.
-my @Check_tainted_env = qw(PATH IFS CDPATH ENV BASH_ENV);
-if (WINDOWS) {
-	push(@Check_tainted_env, 'PERL5SHELL');
-}
-if (VMS) {
-	push(@Check_tainted_env, 'DCL$PATH');
-}
-
-# Not all systems implement the WIFEXITED calls, but POSIX
-# will always export them (even if they're just stubs that
-# die with an error).  Test for the presence of a working
-# WIFEXITED and friends, or define our own.
-
-eval { WIFEXITED(0); };
-
-if ($@ =~ UNDEFINED_POSIX_RE) {
-        no warnings 'redefine';  ## no critic
-	*WIFEXITED   = sub { not $_[0] & 0xff };
-	*WEXITSTATUS = sub { $_[0] >> 8  };
-	*WIFSIGNALED = sub { $_[0] & 127 };
-	*WTERMSIG    = sub { $_[0] & 127 };
-} elsif ($@) {
-	croak sprintf FAIL_POSIX, $@;
-}
-
-# None of the POSIX modules I've found define WCOREDUMP, although
-# many systems define it.  Check the POSIX module in the hope that
-# it may actually be there.
-
-
-# TODO: Ideally, $NATIVE_WCOREDUMP should be a constant.
-
-my $NATIVE_WCOREDUMP;
-
-eval { POSIX::WCOREDUMP(1); };
-
-if ($@ =~ UNDEFINED_POSIX_RE) {
-	*WCOREDUMP = sub { $_[0] & 128 };
-        $NATIVE_WCOREDUMP = 0;
-} elsif ($@) {
-	croak sprintf FAIL_POSIX, $@;
-} else {
-	# POSIX actually has it defined!  Huzzah!
-	*WCOREDUMP = \&POSIX::WCOREDUMP;
-        $NATIVE_WCOREDUMP = 1;
-}
-
-sub _native_wcoredump {
-    return $NATIVE_WCOREDUMP;
-}
-
-# system simply calls run
-
-no warnings 'once'; ## no critic
-*system  = \&run;
-*systemx = \&runx;
-use warnings;
-
-# run is our way of running a process with system() semantics
-
-sub run {
-
-	_check_taint(@_);
-
-	my ($valid_returns, $command, @args) = _process_args(@_);
-
-        # If we have arguments, we really want to call systemx,
-        # so we do so.
-
-	if (@args) {
-                return systemx($valid_returns, $command, @args);
-	}
-
-    if (WINDOWS) {
-        my $pid = _spawn_or_die(&WINDOWS_SHELL->[0], join ' ', @{&WINDOWS_SHELL}, $command);
-        $pid->Wait(INFINITE);	# Wait for process exit.
-        $pid->GetExitCode($EXITVAL);
-        return _check_exit($command,$EXITVAL,$valid_returns);
-    }
-
-    # Without arguments, we're calling system, and checking
-        # the results.
-
-	# We're throwing our own exception on command not found, so
-	# we don't need a warning from Perl.
-
-        {
-            # silence 'Statement unlikely to be reached' warning
-            no warnings 'exec';             ## no critic
-            CORE::system($command,@args);
-        }
-
-	return _process_child_error($?,$command,$valid_returns);
-}
-
-# runx is just like system/run, but *never* invokes the shell.
-
-sub runx {
-    _check_taint(@_);
-
-    my ($valid_returns, $command, @args) = _process_args(@_);
-
-    if (WINDOWS) {
-        our $EXITVAL = -1;
-
-        my $pid = _spawn_or_die($command, Win32::ShellQuote::quote_native($command, @args));
-
-        $pid->Wait(INFINITE);	# Wait for process exit.
-        $pid->GetExitCode($EXITVAL);
-        return _check_exit($command,$EXITVAL,$valid_returns);
-    }
-
-    # If system() fails, we throw our own exception.  We don't
-    # need to have perl complain about it too.
-
-    no warnings; ## no critic
-
-    CORE::system { $command } $command, @args;
-
-    return _process_child_error($?, $command, $valid_returns);
-}
-
-# capture is our way of running a process with backticks/qx semantics
-
-sub capture {
-	_check_taint(@_);
-
-	my ($valid_returns, $command, @args) = _process_args(@_);
-
-        if (@args) {
-            return capturex($valid_returns, $command, @args);
-        }
-
-        if (WINDOWS) {
-            # USE_SHELL really means "You may use the shell if you need it."
-            return _win32_capture(USE_SHELL, $valid_returns, $command);
-        }
-
-	our $EXITVAL = -1;
-
-	my $wantarray = wantarray();
-
-	# We'll produce our own warnings on failure to execute.
-	no warnings 'exec';	## no critic
-
-        if ($wantarray) {
-                my @results = qx($command);
-                _process_child_error($?,$command,$valid_returns);
-                return @results;
-        } 
-
-        my $results = qx($command);
-        _process_child_error($?,$command,$valid_returns);
-        return $results;
-}
-
-# _win32_capture implements the capture and capurex commands on Win32.
-# We need to wrap the whole internals of this sub into
-# an if (WINDOWS) block to avoid it being compiled on non-Win32 systems.
-
-sub _win32_capture {
-    if (not WINDOWS) {
-        croak sprintf(FAIL_INTERNAL, "_win32_capture called when not under Win32");
-    } else {
-
-        my ($use_shell, $valid_returns, $command, @args) = @_;
-
-        my $wantarray = wantarray();
-
-        # Perl doesn't support multi-arg open under
-        # Windows.  Perl also doesn't provide very good
-        # feedback when normal backtails fail, either;
-        # it returns exit status from the shell
-        # (which is indistinguishable from the command
-        # running and producing the same exit status).
-
-        # As such, we essentially have to write our own
-        # backticks.
-
-        # We start by dup'ing STDOUT.
-
-        open(my $saved_stdout, '>&', \*STDOUT)  ## no critic
-                or croak sprintf(FAIL_PLUMBING, "Can't dup STDOUT", $!);
-
-        # We now open up a pipe that will allow us to	
-        # communicate with the new process.
-
-        pipe(my ($read_fh, $write_fh))
-                or croak sprintf(FAIL_PLUMBING, "Can't create pipe", $!);
-
-        # Allow CRLF sequences to become "\n", since
-        # this is what Perl backticks do.
-
-        binmode($read_fh, ':crlf');
-
-        # Now we re-open our STDOUT to $write_fh...
-
-        open(STDOUT, '>&', $write_fh)  ## no critic
-                or croak sprintf(FAIL_PLUMBING, "Can't redirect STDOUT", $!);
-
-        # If we have args, or we're told not to use the shell, then
-        # we treat $command as our shell.  Otherwise we grub around
-        # in our command to look for a command to run.
-        #
-        # Note that we don't actually *use* the shell (although in
-        # a future version we might).  Being told not to use the shell
-        # (capturex) means we treat our command as really being a command,
-        # and not a command line.
-
-        my $exe =   @args                      ? $command :
-                    (! $use_shell)             ? $command :
-                    $command =~ m{^"([^"]+)"}x ? $1       :
-                    $command =~ m{(\S+)     }x ? $1       :
-                    croak sprintf(FAIL_CMD_BLANK, $command);
-
-        # And now we spawn our new process with inherited
-        # filehandles.
-
-        my $err;
-        my $pid = eval { 
-                _spawn_or_die($exe, @args ? Win32::ShellQuote::quote_native($command, @args) : $command);
-        }
-        or do {
-                $err = $@;
-        };
-
-        # Regardless of whether our command ran, we must restore STDOUT.
-        # RT #48319
-        open(STDOUT, '>&', $saved_stdout)  ## no critic
-                or croak sprintf(FAIL_PLUMBING,"Can't restore STDOUT", $!);
-
-        # And now, if there was an actual error , propagate it.
-        die $err if defined $err;   # If there's an error from _spawn_or_die
-
-        # Clean-up the filehandles we no longer need...
-
-        close($write_fh)
-                or croak sprintf(FAIL_PLUMBING,q{Can't close write end of pipe}, $!);
-        close($saved_stdout)
-                or croak sprintf(FAIL_PLUMBING,q{Can't close saved STDOUT}, $!);
-
-        # Read the data from our child...
-
-        my (@results, $result);
-
-        if ($wantarray) {
-                @results = <$read_fh>;
-        } else {
-                $result = join("",<$read_fh>);
-        }
-
-        # Tidy up our windows process and we're done!
-
-        $pid->Wait(INFINITE);	# Wait for process exit.
-        $pid->GetExitCode($EXITVAL);
-
-        _check_exit($command,$EXITVAL,$valid_returns);
-
-        return $wantarray ? @results : $result;
-
-    }
-}
-
-# capturex() is just like backticks/qx, but never invokes the shell.
-
-sub capturex {
-	_check_taint(@_);
-
-	my ($valid_returns, $command, @args) = _process_args(@_);
-
-	our $EXITVAL = -1;
-
-	my $wantarray = wantarray();
-
-	if (WINDOWS) {
-            return _win32_capture(NO_SHELL, $valid_returns, $command, @args);
-        }
-
-	# We can't use a multi-arg piped open here, since 5.6.x
-	# doesn't like them.  Instead we emulate what 5.8.x does,
-	# which is to create a pipe(), set the close-on-exec flag
-	# on the child, and the fork/exec.  If the exec fails, the
-	# child writes to the pipe.  If the exec succeeds, then
-	# the pipe closes without data.
-
-	pipe(my ($read_fh, $write_fh))
-		or croak sprintf(FAIL_PLUMBING, "Can't create pipe", $!);
-
-	# This next line also does an implicit fork.
-	my $pid = open(my $pipe, '-|');	 ## no critic
-
-	if (not defined $pid) {
-		croak sprintf(FAIL_START, $command, $!);
-	} elsif (not $pid) {
-		# Child process, execs command.
-
-		close($read_fh);
-
-		# TODO: 'no warnings exec' doesn't get rid
-		# of the 'unlikely to be reached' warnings.
-		# This is a bug in perl / perldiag / perllexwarn / warnings.
-
-		no warnings;   ## no critic
-
-		CORE::exec { $command } $command, @args;
-
-		# Oh no, exec fails!  Send the reason why to
-		# the parent.
-
-		print {$write_fh} int($!);
-		exit(-1);
-	}
-
-	{
-		# In parent process.
-
-		close($write_fh);
-
-		# Parent process, check for child error.
-		my $error = <$read_fh>;
-
-		# Tidy up our pipes.
-		close($read_fh);
-
-		# Check for error.
-		if ($error) {
-			# Setting $! to our child error number gives
-			# us nice looking strings when printed.
-			local $! = $error;
-			croak sprintf(FAIL_START, $command, $!);
-		}
-	}
-
-	# Parent process, we don't care about our pid, but we
-	# do go and read our pipe.
-
-	if ($wantarray) {
-		my @results = <$pipe>;
-		close($pipe);
-		_process_child_error($?,$command,$valid_returns);
-		return @results;
-	}
-
-	# NB: We don't check the return status on close(), since
-	# on failure it sets $?, which we then inspect for more
-	# useful information.
-
-	my $results = join("",<$pipe>);
-	close($pipe);
-	_process_child_error($?,$command,$valid_returns);
-	
-	return $results;
-
-}
-
-# Tries really hard to spawn a process under Windows.  Returns
-# the pid on success, or undef on error.
-
-sub _spawn_or_die {
-
-	# We need to wrap practically the entire sub in an
-	# if block to ensure it doesn't get compiled under non-Win32
-	# systems.  Compiling on these systems would not only be a
-	# waste of time, but also results in complaints about
-	# the NORMAL_PRIORITY_CLASS constant.
-
-	if (not WINDOWS) {
-		croak sprintf(FAIL_INTERNAL, "_spawn_or_die called when not under Win32");
-	} else {
-		my ($orig_exe, $cmdline) = @_;
-		my $pid;
-
-		my $exe = $orig_exe;
-
-		# If our command doesn't have an extension, add one.
-		$exe .= $Config{_exe} if ($exe !~ m{\.});
-
-		Win32::Process::Create(
-			$pid, $exe, $cmdline, 1, NORMAL_PRIORITY_CLASS, "."
-		) and return $pid;
-
-		my @path = split(/;/,$ENV{PATH});
-
-		foreach my $dir (@path) {
-			my $fullpath = File::Spec->catfile($dir,$exe);
-
-			# We're using -x here on the assumption that stat()
-			# is faster than spawn, so trying to spawn a process
-			# for each path element will be unacceptably
-			# inefficient.
-
-			if (-x $fullpath) {
-				Win32::Process::Create(
-					$pid, $fullpath, $cmdline, 1,
-					NORMAL_PRIORITY_CLASS, "."
-				) and return $pid;
-			}
-		}
-
-		croak sprintf(FAIL_START, $orig_exe, $^E);
-	}
-}
-
-# Complain on tainted arguments or environment.
-# ASSUME_TAINTED is true for 5.6.x, since it's missing ${^TAINT}
-
-sub _check_taint {
-	return if not (ASSUME_TAINTED or ${^TAINT});
-	my $caller = (caller(1))[3];
-	foreach my $var (@_) {
-		if (tainted $var) {
-			croak sprintf(FAIL_TAINT, $caller, $var);
-		}
-	}
-	foreach my $var (@Check_tainted_env) {
-		if (tainted $ENV{$var} ) {
-			croak sprintf(FAIL_TAINT_ENV, $caller, $var);
-		}
-	}
-
-	return;
-
-}
-
-# This subroutine performs the difficult task of interpreting
-# $?.  It's not intended to be called directly, as it will
-# croak on errors, and its implementation and interface may
-# change in the future.
-
-sub _process_child_error {
-	my ($child_error, $command, $valid_returns) = @_;
-	
-	$EXITVAL = -1;
-
-	my $coredump = WCOREDUMP($child_error);
-
-        # There's a bug in perl 5.8.9 and 5.10.0 where if the system
-        # does not provide a native WCOREDUMP, then $? will
-        # never contain coredump information.  This code
-        # checks to see if we have the bug, and works around
-        # it if needed.
-
-        if ($] >= 5.008009 and not $NATIVE_WCOREDUMP) {
-            $coredump ||= WCOREDUMP( ${^CHILD_ERROR_NATIVE} );
-        }
-
-	if ($child_error == -1) {
-		croak sprintf(FAIL_START, $command, $!);
-
-	} elsif ( WIFEXITED( $child_error ) ) {
-		$EXITVAL = WEXITSTATUS( $child_error );
-
-		return _check_exit($command,$EXITVAL,$valid_returns);
-
-	} elsif ( WIFSIGNALED( $child_error ) ) {
-		my $signal_no   = WTERMSIG( $child_error );
-		my $signal_name = $Signal_from_number[$signal_no] || "UNKNOWN";
-
-		croak sprintf FAIL_SIGNAL, $command, $signal_name, $signal_no, ($coredump ? " and dumped core" : "");
-
-
-	} 
-
-	croak sprintf(FAIL_INTERNAL, qq{'$command' ran without exit value or signal});
-
-}
-
-# A simple subroutine for checking exit values.  Results in better
-# assurance of consistent error messages, and better forward support
-# for new features in I::S::S.
-
-sub _check_exit {
-	my ($command, $exitval, $valid_returns) = @_;
-
-	# If we have a single-value list consisting of the EXIT_ANY
-	# value, then we're happy with whatever exit value we're given.
-	if (@$valid_returns == 1 and $valid_returns->[0] == EXIT_ANY_CONST) {
-		return $exitval;
-	}
-
-	if (not defined first { $_ == $exitval } @$valid_returns) {
-		croak sprintf FAIL_BADEXIT, $command, $exitval;
-	}	
-	return $exitval;
-}
-
-
-# This subroutine simply determines a list of valid returns, the command
-# name, and any arguments that we need to pass to it.
-
-sub _process_args {
-	my $valid_returns = [ 0 ];
-	my $caller = (caller(1))[3];
-
-	if (not @_) {
-		croak "$caller called with no arguments";
-	}
-
-	if (ref $_[0] eq "ARRAY") {
-		$valid_returns = shift(@_);
-	}
-
-	if (not @_) {
-		croak "$caller called with no command";
-	}
-
-	my $command = shift(@_);
-
-        if (not defined $command) {
-                croak sprintf( FAIL_UNDEF, $caller );
-        }
-
-	return ($valid_returns,$command,@_);
-
-}
-
-1;
-
-__END__
-
-=head1 NAME
-
-IPC::System::Simple - Run commands simply, with detailed diagnostics
-
-=head1 SYNOPSIS
-
-  use IPC::System::Simple qw(system systemx capture capturex);
-
-  system("some_command");        # Command succeeds or dies!
-
-  system("some_command",@args);  # Succeeds or dies, avoids shell if @args
-
-  systemx("some_command",@args); # Succeeds or dies, NEVER uses the shell
-
-
-  # Capture the output of a command (just like backticks). Dies on error.
-  my $output = capture("some_command");
-
-  # Just like backticks in list context.  Dies on error.
-  my @output = capture("some_command");
-
-  # As above, but avoids the shell if @args is non-empty
-  my $output = capture("some_command", @args);
-
-  # As above, but NEVER invokes the shell.
-  my $output = capturex("some_command", @args);
-  my @output = capturex("some_command", @args);
-
-=head1 DESCRIPTION
-
-Calling Perl's in-built C<system()> function is easy, 
-determining if it was successful is I<hard>.  Let's face it,
-C<$?> isn't the nicest variable in the world to play with, and
-even if you I<do> check it, producing a well-formatted error
-string takes a lot of work.
-
-C<IPC::System::Simple> takes the hard work out of calling 
-external commands.  In fact, if you want to be really lazy,
-you can just write:
-
-    use IPC::System::Simple qw(system);
-
-and all of your C<system> commands will either succeed (run to
-completion and return a zero exit value), or die with rich diagnostic
-messages.
-
-The C<IPC::System::Simple> module also provides a simple replacement
-to Perl's backticks operator.  Simply write:
-
-    use IPC::System::Simple qw(capture);
-
-and then use the L</capture()> command just like you'd use backticks.
-If there's an error, it will die with a detailed description of what
-went wrong.  Better still, you can even use C<capturex()> to run the
-equivalent of backticks, but without the shell:
-
-    use IPC::System::Simple qw(capturex);
-
-    my $result = capturex($command, @args);
-
-If you want more power than the basic interface, including the
-ability to specify which exit values are acceptable, trap errors,
-or process diagnostics, then read on!
-
-=head1 ADVANCED SYNOPSIS
-
-  use IPC::System::Simple qw(
-    capture capturex system systemx run runx $EXITVAL EXIT_ANY
-  );
-
-  # Run a command, throwing exception on failure
-
-  run("some_command");
-
-  runx("some_command",@args);  # Run a command, avoiding the shell
-
-  # Do the same thing, but with the drop-in system replacement.
-
-  system("some_command");
-
-  systemx("some_command", @args);
-
-  # Run a command which must return 0..5, avoid the shell, and get the
-  # exit value (we could also look at $EXITVAL)
-
-  my $exit_value = runx([0..5], "some_command", @args);
-
-  # The same, but any exit value will do.
-
-  my $exit_value = runx(EXIT_ANY, "some_command", @args);
-
-  # Capture output into $result and throw exception on failure
-
-  my $result = capture("some_command");	
-
-  # Check exit value from captured command
-
-  print "some_command exited with status $EXITVAL\n";
-
-  # Captures into @lines, splitting on $/
-  my @lines = capture("some_command"); 
-
-  # Run a command which must return 0..5, capture the output into
-  # @lines, and avoid the shell.
-
-  my @lines  = capturex([0..5], "some_command", @args);
-
-=head1 ADVANCED USAGE
-
-=head2 run() and system()
-
-C<IPC::System::Simple> provides a subroutine called
-C<run>, that executes a command using the same semantics as
-Perl's built-in C<system>:
-
-    use IPC::System::Simple qw(run);
-
-    run("cat *.txt");           # Execute command via the shell
-    run("cat","/etc/motd");     # Execute command without shell
-
-The primary difference between Perl's in-built system and
-the C<run> command is that C<run> will throw an exception on
-failure, and allows a list of acceptable exit values to be set.
-See L</Exit values> for further information.
-
-In fact, you can even have C<IPC::System::Simple> replace the
-default C<system> function for your package so it has the
-same behaviour:
-
-    use IPC::System::Simple qw(system);
-
-    system("cat *.txt");  # system now succeeds or dies!
-
-C<system> and C<run> are aliases to each other.
-
-See also L</runx(), systemx() and capturex()> for variants of
-C<system()> and C<run()> that never invoke the shell, even with
-a single argument.
-
-=head2 capture()
-
-A second subroutine, named C<capture> executes a command with
-the same semantics as Perl's built-in backticks (and C<qx()>):
-
-    use IPC::System::Simple qw(capture);
-
-    # Capture text while invoking the shell.
-    my $file  = capture("cat /etc/motd");
-    my @lines = capture("cat /etc/passwd");
-
-However unlike regular backticks, which always use the shell, C<capture>
-will bypass the shell when called with multiple arguments:
-
-    # Capture text while avoiding the shell.
-    my $file  = capture("cat", "/etc/motd");
-    my @lines = capture("cat", "/etc/passwd");
-
-See also L</runx(), systemx() and capturex()> for a variant of
-C<capture()> that never invokes the shell, even with a single
-argument.
-
-=head2 runx(), systemx() and capturex()
-
-The C<runx()>, C<systemx()> and C<capturex()> commands are identical
-to the multi-argument forms of C<run()>, C<system()> and C<capture()>
-respectively, but I<never> invoke the shell, even when called with a
-single argument.  These forms are particularly useful when a command's
-argument list I<might> be empty, for example:
-
-    systemx($cmd, @args);
-
-The use of C<systemx()> here guarantees that the shell will I<never>
-be invoked, even if C<@args> is empty.
-
-=head2 Exception handling
-
-In the case where the command returns an unexpected status, both C<run> and
-C<capture> will throw an exception, which if not caught will terminate your
-program with an error.
-
-Capturing the exception is easy:
-
-    eval {
-        run("cat *.txt");
-    };
-
-    if ($@) {
-        print "Something went wrong - $@\n";
-    }
-
-See the diagnostics section below for more details.
-
-=head3 Exception cases
-
-C<IPC::System::Simple> considers the following to be unexpected,
-and worthy of exception:
-
-=over 4
-
-=item *
-
-Failing to start entirely (eg, command not found, permission denied).
-
-=item *
-
-Returning an exit value other than zero (but see below).
-
-=item *
-
-Being killed by a signal.
-
-=item *
-
-Being passed tainted data (in taint mode).
-
-=back
-
-=head2 Exit values
-
-Traditionally, system commands return a zero status for success and a
-non-zero status for failure.  C<IPC::System::Simple> will default to throwing
-an exception if a non-zero exit value is returned.
-
-You may specify a range of values which are considered acceptable exit
-values by passing an I<array reference> as the first argument.  The
-special constant C<EXIT_ANY> can be used to allow I<any> exit value
-to be returned.
-
-	use IPC::System::Simple qw(run system capture EXIT_ANY);
-
-	run( [0..5], "cat *.txt");             # Exit values 0-5 are OK
-
-	system( [0..5], "cat *.txt");          # This works the same way
-
-	my @lines = capture( EXIT_ANY, "cat *.txt"); # Any exit is fine.
-
-The C<run> and replacement C<system> subroutines returns the exit
-value of the process:
-
-	my $exit_value = run( [0..5], "cat *.txt");
-
-	# OR:
-
-	my $exit_value = system( [0..5] "cat *.txt");
-
-	print "Program exited with value $exit_value\n";
-
-=head3 $EXITVAL
-
-The exit value of any command executed by C<IPC::System::Simple>
-can always be retrieved from the C<$IPC::System::Simple::EXITVAL>
-variable:
-
-This is particularly useful when inspecting results from C<capture>,
-which returns the captured text from the command.
-
-	use IPC::System::Simple qw(capture $EXITVAL EXIT_ANY);
-
-	my @enemies_defeated = capture(EXIT_ANY, "defeat_evil", "/dev/mordor");
-
-	print "Program exited with value $EXITVAL\n";
-
-C<$EXITVAL> will be set to C<-1> if the command did not exit normally (eg,
-being terminated by a signal) or did not start.  In this situation an
-exception will also be thrown.
-
-=head2 WINDOWS-SPECIFIC NOTES
-
-The C<run> subroutine make available the full 32-bit exit value on
-Win32 systems. This has been true since C<IPC::System::Simple> v0.06
-when called with multiple arguments, and since v1.25 when called with
-a single argument.  This is different from the previous versions of
-C<IPC::System::Simple> and from Perl's in-build C<system()> function,
-which can only handle 8-bit return values.
-
-The C<capture> subroutine always returns the 32-bit exit value under
-Windows.  The C<capture> subroutine also never uses the shell,
-even when passed a single argument.
-
-The C<run> subroutine always uses a shell when passed a single
-argument. On NT systems, it uses C<cmd.exe> in the system root, and on
-non-NT systems it uses C<command.com> in the system root.
-
-As of C<IPC::System::Simple> v1.25, the C<runx> and C<capturex>
-subroutines, as well as multiple-argument calls to the C<run> and
-C<capture> subroutines, have their arguments properly quoted, so that
-arugments with spaces and the like work properly. Unfortunately, this
-breaks any attempt to invoke the shell itself. If you really need to
-execute C<cmd.exe> or C<command.com>, use the single-argument form.
-For single-argument calls to C<run> and C<capture>, the argument must
-be properly shell-quoted in advance of the call.
-
-Versions of C<IPC::System::Simple> before v0.09 would not search
-the C<PATH> environment variable when the multi-argument form of
-C<run()> was called.  Versions from v0.09 onwards correctly search
-the path provided the command is provided including the extension
-(eg, C<notepad.exe> rather than just C<notepad>, or C<gvim.bat> rather
-than just C<gvim>).  If no extension is provided, C<.exe> is
-assumed.
-
-Signals are not supported on Windows systems.  Sending a signal
-to a Windows process will usually cause it to exit with the signal
-number used.
-
-=head1 DIAGNOSTICS
-
-=over 4
-
-=item "%s" failed to start: "%s"
-
-The command specified did not even start.  It may not exist, or
-you may not have permission to use it.  The reason it could not
-start (as determined from C<$!>) will be provided.
-
-=item "%s" unexpectedly returned exit value %d
-
-The command ran successfully, but returned an exit value we did
-not expect.  The value returned is reported.
-
-=item "%s" died to signal "%s" (%d) %s
-
-The command was killed by a signal.  The name of the signal
-will be reported, or C<UNKNOWN> if it cannot be determined.  The
-signal number is always reported.  If we detected that the
-process dumped core, then the string C<and dumped core> is
-appended.
-
-=item IPC::System::Simple::%s called with no arguments
-
-You attempted to call C<run> or C<capture> but did not provide any
-arguments at all.  At the very lease you need to supply a command
-to run.
-
-=item IPC::System::Simple::%s called with no command
-
-You called C<run> or C<capture> with a list of acceptable exit values,
-but no actual command.
-
-=item IPC::System::Simple::%s called with tainted argument "%s"
-
-You called C<run> or C<capture> with tainted (untrusted) arguments, which is
-almost certainly a bad idea.  To untaint your arguments you'll need to pass
-your data through a regular expression and use the resulting match variables.
-See L<perlsec/Laundering and Detecting Tainted Data> for more information.
-
-=item IPC::System::Simple::%s called with tainted environment $ENV{%s}
-
-You called C<run> or C<capture> but part of your environment was tainted
-(untrusted).  You should either delete the named environment
-variable before calling C<run>, or set it to an untainted value
-(usually one set inside your program).  See
-L<perlsec/Cleaning Up Your Path> for more information.
-
-=item Error in IPC::System::Simple plumbing: "%s" - "%s"
-
-Implementing the C<capture> command involves dark and terrible magicks
-involving pipes, and one of them has sprung a leak.  This could be due to a
-lack of file descriptors, although there are other possibilities.
-
-If you are able to reproduce this error, you are encouraged
-to submit a bug report according to the L</Reporting bugs> section below.
-
-=item Internal error in IPC::System::Simple: "%s"
-
-You've found a bug in C<IPC::System::Simple>.  Please check to
-see if an updated version of C<IPC::System::Simple> is available.
-If not, please file a bug report according to the L</Reporting bugs> section
-below.
-
-=item IPC::System::Simple::%s called with undefined command
-
-You've passed the undefined value as a command to be executed.
-While this is a very Zen-like action, it's not supported by
-Perl's current implementation.
-
-=back
-
-=head1 DEPENDENCIES
-
-This module depends upon L<Win32::Process> when used on Win32
-system.  C<Win32::Process> is bundled as a core module in ActivePerl 5.6
-and above.
-
-There are no non-core dependencies on non-Win32 systems.
-
-=head1 COMPARISON TO OTHER APIs
-
-Perl provides a range of in-built functions for handling external
-commands, and CPAN provides even more.  The C<IPC::System::Simple>
-differentiates itself from other options by providing:
-
-=over 4
-
-=item Extremely detailed diagnostics
-
-The diagnostics produced by C<IPC::System::Simple> are designed
-to provide as much information as possible.  Rather than requiring
-the developer to inspect C<$?>, C<IPC::System::Simple> does the
-hard work for you.
-
-If an odd exit status is provided, you're informed of what it is.  If a
-signal kills your process, you are informed of both its name and number.
-If tainted data or environment prevents your command from running, you
-are informed of exactly which data or environmental variable is
-tainted.
-
-=item Exceptions on failure
-
-C<IPC::System::Simple> takes an aggressive approach to error handling.
-Rather than allow commands to fail silently, exceptions are thrown
-when unexpected results are seen.  This allows for easy development
-using a try/catch style, and avoids the possibility of accidentally
-continuing after a failed command.
-
-=item Easy access to exit status
-
-The C<run>, C<system> and C<capture> commands all set C<$EXITVAL>,
-making it easy to determine the exit status of a command.
-Additionally, the C<system> and C<run> interfaces return the exit
-status.
-
-=item Consistent interfaces
-
-When called with multiple arguments, the C<run>, C<system> and
-C<capture> interfaces I<never> invoke the shell.  This differs
-from the in-built Perl C<system> command which may invoke the
-shell under Windows when called with multiple arguments.  It
-differs from the in-built Perl backticks operator which always
-invokes the shell.
-
-=back
-
-=head1 BUGS
-
-When C<system> is exported, the exotic form C<system { $cmd } @args>
-is not supported.  Attemping to use the exotic form is a syntax
-error.  This affects the calling package I<only>.  Use C<CORE::system>
-if you need it, or consider using the L<autodie> module to replace
-C<system> with lexical scope.
-
-Core dumps are only checked for when a process dies due to a
-signal.  It is not believed there are any systems where processes
-can dump core without dying to a signal.
-
-C<WIFSTOPPED> status is not checked, as perl never spawns processes
-with the C<WUNTRACED> option.
-
-Signals are not supported under Win32 systems, since they don't
-work at all like Unix signals.  Win32 signals cause commands to
-exit with a given exit value, which this modules I<does> capture.
-
-=head2 Reporting bugs
-
-Before reporting a bug, please check to ensure you are using the
-most recent version of C<IPC::System::Simple>.  Your problem may
-have already been fixed in a new release.
-
-You can find the C<IPC::System::Simple> bug-tracker at
-L<http://rt.cpan.org/Public/Dist/Display.html?Name=IPC-System-Simple> .
-Please check to see if your bug has already been reported; if
-in doubt, report yours anyway.
-
-Submitting a patch and/or failing test case will greatly expedite
-the fixing of bugs.
-
-=head1 FEEDBACK
-
-If you find this module useful, please consider rating it on the
-CPAN Ratings service at
-L<http://cpanratings.perl.org/rate/?distribution=IPC-System-Simple> .
-
-The module author loves to hear how C<IPC::System::Simple> has made
-your life better (or worse).  Feedback can be sent to
-E<lt>pjf@perltraining.com.auE<gt>.
-
-=head1 SEE ALSO
-
-L<autodie> uses C<IPC::System::Simple> to provide succeed-or-die
-replacements to C<system> (and other built-ins) with lexical scope.
-
-L<POSIX>, L<IPC::Run::Simple>, L<perlipc>, L<perlport>, L<IPC::Run>,
-L<IPC::Run3>, L<Win32::Process>
-
-=head1 AUTHOR
-
-Paul Fenwick E<lt>pjf@cpan.orgE<gt>
-
-=head1 COPYRIGHT AND LICENSE
-
-Copyright (C) 2006-2008 by Paul Fenwick
-
-This library is free software; you can redistribute it and/or modify
-it under the same terms as Perl itself, either Perl version 5.6.0 or,
-at your option, any later version of Perl 5 you may have available.
-
-=for Pod::Coverage WCOREDUMP
-
-=cut