=begin pod

=TITLE class Proc

=SUBTITLE Running process (filehandle-based interface)

    class Proc { ... }

C<Proc> is a representation of an invocation of an external
process. It provides access to the input, output and error stream as well as
the exit code. It is typically created through the C<run> subroutine:

    my $proc = run 'echo', 'Hallo world', :out;
    my $captured-output = $proc.out.slurp-rest;
    say "Output was $captured-output.perl()";       # Output was "Hallo world\n"

Piping several commands is easy too. To achieve the equivalent of the pipe
C<echo "Hello, world" | cat -n> in Perl 6, and capture the output from the
second command, you can do

    my $p1 = run 'echo', 'Hello, world', :out;
    my $p2 = run 'cat', '-n', :in($p1.out), :out;
    say $p2.out.get;


=head1 Methods

=head2 method new

    method new(Proc:U:
            :$in = '-',
            :$out = '-',
            :$err = '-',
            Bool :$bin = False,
            Bool :$chomp = True,
            Bool :$merge = False,
            Str:D :$enc = 'UTF-8',
            Str:D $nl = "\n",
        ) returns Proc:D
    sub run(
            :$in = '-',
            :$out = '-',
            :$err = '-',
            Bool :$bin = False,
            Bool :$chomp = True,
            Bool :$merge = False,
            Str:D :$enc = 'UTF-8',
            Str:D $nl = "\n",
            :$cwd = $*CWD,
            Hash() :$env = %*ENV,
            *@args
    )  returns Proc:D

C<new> creates a new C<Proc> object, whereas C<run> creates one, and spawns it
with the command and arguments provided in C<@args>.

C<$in>, C<$out> and C<$err> are the three
standard streams of the to-be-launched program, and default to C<"-">, which
means they inherit the stream from the parent process. Setting one (or more)
of them to C<True> makes the stream available as an L<IO::Pipe> object of the
same name, so for example C<$proc.out>. Or you can pass an existing
L<IO::Handle> object (for example IO::Pipe) in, in which case this handle is
used for the stream.

C<$bin> controls whether the streams are handled as binary (i.e.
L<Blob|/type/Blob> object) or text (i.e. L<Str|/type/Str> objects). If C<$bin>
is False, C<$enc> holds the character encoding to encode strings sent to the
input stream and decode binary data from the output and error streams.

With C<$chomp> set to C<True>, newlines are stripped from the output and err
streams when reading with C<lines> or C<get>. C<$nl> controls what your idea
of a newline is.

If C<$merge> is set to True, the standard output and error stream end up
merged in C<$proc.out>.

=head2 method spawn

    method spawn(Proc:D *@args ($, *@), :$cwd = $*CWD, Hash() :$env = %*ENV) returns Bool:D

Runs the C<Proc> objects with the given command, argument list, working directory and environment.

=head2 method exitcode

    method exitcode(Proc:D) returns Int:D

Returns the exit code of the external process, or -1 if it has not exited yet.

=head2 method signal

    method signal(Proc:D)

Returns the signal number with which the external process was killed, or 0 or
an undefined value otherwise.

=head2 method pid

    method pid(Proc:D)

Returns the Process Identifier (pid) of the external process, if available.

=end pod
