txt: ## dist_github-ppentchev-Shell-Capture.md
  # NAME
  
  Shell::Capture - capture a command's output and exit code
  
  # SYNOPSIS
  
  ```
      use Shell::Capture;
  
      my Shell::Capture $c .= capture('id', '-u', '-n');
      if $c.exitcode != 0 {
          die "Could not execute id -u -n\n";
      } elsif $c.lines.elems != 1 {
          die "id -u -n returned something unexpected:\n" ~ $c.lines.join("\n") ~ "\n";
      }
      say "Got my username: " ~ $c.lines[0];
  
      sub fail($r, @cmd) {
          die "fail with exit code $r.exitcode() and $r.lines().elems() " ~
              "line(s) of output and cmd " ~ @cmd;
      }
  
      $c .= capture-check(:accept(0, 3), 'sh', '-c', 'date');
      say "The current date is $c.lines()[0]" if $c.exitcode == 0;
  
      $c .= capture-check(:accept(0, 3), 'sh', '-c', 'date; exit 3');
      say "The current date is $c.lines()[0]" if $c.exitcode == 3;
  
      $c .= capture-check(:accept(0, 3), :&fail, 'sh', '-c', 'date; exit 1');
      say 'not reached, fail() dies';
  
      $c .= capture-check('git', 'ls-files', '-z', :nl("\0"));
      say 'Got some unquoted filenames from Git:';
      $c.lines>>.say;
  
      $c .= capture-check('env', 'LANG=fr_FR.ISO-8859-1', 'date', :enc('ISO-8859-1'));
  
  ```
  
  # DESCRIPTION
  
  This class provides two methods to execute an external command, capture its output and exit code, and, in `capture-check()`, raise an error on unexpected exit code values.
  
  # FIELDS
  
  * exitcode
  
    ```
    Int:D $.exitcode
  
    ```
  
    The exit code of the executed external command.
  * lines
  
    ```
    Str:D @.lines
  
    ```
  
    The output of the external command split into lines with the newline terminator removed.
  
  # METHODS
  
  * method capture()
  
    ```
    method capture(*@cmd, Str :$enc, Str :$nl)
  
    ```
  
    Execute the specified command in the same way as `run()` would, then create a new `Shell::Capture` object with its `exitcode` and `lines` members set respectively to the exit code of the command and its output split into lines, as described above.
  
    The `$enc` and `$nl` parameters, if supplied, are passed directly to `run()`, allowing the caller to specify the encoding of the data output by the external program and the character (or string) used to delimit lines in the output. See the `Proc.new()` documentation for more information.
  * method capture-check()
  
    ```
    method capture-check(:$accept, :$fail, Str :$enc, Str :$nl, *@cmd)
  
    ```
  
    Execute the specified command and create a `Shell::Capture` object in the same way as `capture()`, then check the exit code against the `$accept` list (default: only 0). If the exit code is on the list, return the `Shell::Capture` object to the caller.
  
    If the exit code is not on the list and there is no `$fail` handler specified, output an error message to the standard error stream and terminate the program. If a fail handler is specified, invoke it with two arguments: the `Shell::Capture` object for further examination and the command executed; if the fail handler returns, `capture-check()` will return the `Shell::Capture` object to its caller (useful for writing tests).
  
    The `$enc` and `$nl` parameters, if specified, are passed directly to `run()` just as in `capture()`.
  
  # AUTHOR
  
  Peter Pentchev <[roam@ringlet.net](mailto:roam@ringlet.net)>
  
  # COPYRIGHT
  
  Copyright (C) 2016, 2017 Peter Pentchev
  
  # LICENSE
  
  The Shell::Capture module is distributed under the terms of the Artistic License 2.0. For more details, see the full text of the license in the file LICENSE in the source distribution.
  