NAME

    IPC::ReadpipeX - List form of readpipe/qx/backticks for capturing
    output

SYNOPSIS

      use IPC::ReadpipeX;
    
      my $path = '/file path/with$shell/characters&';
      my @entries = readpipex 'ls', '-l', $path;
      if ($?) {
        my $exit = $? >> 8;
        die "ls '$path' exited with status $exit";
      }
    
      my $hostname = readpipex 'hostname', '-f';
      chomp $hostname;

DESCRIPTION

    The built-in readpipe function, also known as the qx operator or
    backticks (``), runs a command and captures the output (STDOUT).
    However, unlike system and exec, the command will always be parsed by
    the shell, and it does not provide a list form to bypass shell parsing
    when multiple arguments are passed. "readpipex" provides this
    capability in a simple copy-pastable function.

    For other methods of redirecting output, capturing STDERR, and
    interacting with the process, consider the modules listed in "SEE
    ALSO".

FUNCTIONS

    readpipex is exported by default.

 readpipex

      my $output = readpipex $cmd, @args;
      my @output = readpipex $cmd, @args;

    Runs the given command, capturing STDOUT and returning it as a single
    string in scalar context, or an array of lines in list context. If more
    than one argument is passed, the command will be executed directly
    rather than via the shell, as in system and exec. The command and each
    argument will be passed directly to the execvp(3) system call, so the
    program will receive the arguments exactly as passed, without first
    interpreting shell metacharacters.

    Errors forking or running the command will raise an exception, and $!
    will be set to the error code. The exit status of the process is
    otherwise available in $? as normal.

    The code of this function can easily be copy-pasted and is shown below.

      sub readpipex {
        no warnings 'exec';
        open my $stdout, '-|', @_ or die "readpipex '$_[0]' failed: $!";
        my @output = wantarray ? readline($stdout)
          : do { local $/; scalar readline $stdout };
        close $stdout;
        return wantarray ? @output : $output[0];
      }

    The above code snippet may be considered to be licensed under The
    Unlicense <https://choosealicense.com/licenses/unlicense/> for the
    purpose of copying without attribution or warranty.

CAVEATS

      * Behavior when passing no arguments is unspecified.

      * The shell can still be invoked if only one argument is passed.

      * The -| open mode requires Perl 5.8 or newer on a system that
      supports forking, or Perl 5.22 or newer on Windows.

      * Errors while reading or closing the pipe, though exceedingly rare,
      are ignored, as in the core readpipe.

BUGS

    Report any issues on the public bugtracker.

AUTHOR

    Dan Book <dbook@cpan.org>

COPYRIGHT AND LICENSE

    This software is Copyright (c) 2019 by Dan Book.

    This is free software, licensed under:

      The Artistic License 2.0 (GPL Compatible)

SEE ALSO

      * IPC::System::Simple - provides system and capture functions with
      optional exit status checking and variants that always bypass the
      shell

      * IPC::Run3 - run a process and direct STDIN, STDOUT, and STDERR

      * Capture::Tiny - capture STDOUT and STDERR in any wrapped code

      * IO::Async::Process - complete asynchronous control over a process
      and its handles