Document a bit more of Proc::Aync, related exceptions

lib/Type/Proc/Async.pod

@@ -29,16 +29,28 @@ This produces the following output:
     Output: foo bar
     Done.
 
+An example that opens an external program for writing:
+
+    use v6;
+    my $prog = Proc::Async.new(:w, 'hexdump', '-C');
+    my $promise = $prog.start;
+    $prog.write(Buf.new(12, 42));
+    $prog.close-stdin;
+    await $promise;
 
 =head1 Methods
 
 =head2 method new
 
-    method new(:$path, *@args) returns Proc::Async:D
+    method new(:$path, *@args, :$w) returns Proc::Async:D
 
 Creates a new C<Proc::Async> object with externa program name or path C<$path>
 and the command line arguments C<@args>.
 
+If C<:w> is passed to C<new>, then a pipe to the external program's standard
+input stream (stdin) is opened, to which you can write with C<write> and
+C<say>.
+
 =head2 method stdout
 
     method stdout(Proc::Async:D:, :$bin) returns Supply:D
@@ -99,9 +111,30 @@ thrown.
 Returns the name and/or path of the external program that was passed to the
 C<new> method as first argument.
 
+=head2 method args
+
+    method args(Proc::Async:D:) returns Positional:D
+
+Returns the command line arguments for the external programs, as passed to the
+C<new> method.
+
+=head2 method write
+
+    method write(Proc::Async:D: Blob:D $b, :$scheduler = $*SCHEDULER)
+
+Write the binary data in C<$b> to the standard input stream of the external
+program.
+
+The C<Proc::Async> object must be created for writing (with
+C<Proc::Async.new(:w, $path, @args)>). Otherwise an
+L<X::Proc::Async::OpenForWriting> exception will the thrown.
+
+C<start> must have been called before calling method write, otherwise an
+L<X::Proc::Async::MustBeStarted> exception is thrown.
+
 =begin comment
 
-TODO: various exceptions, @.args, print, say, write, close-stdin, kill
+TODO: various exceptions, print, say, close-stdin, kill
 
 =end comment
 

lib/Type/X/Proc/Async/MustBeStarted.pod

@@ -0,0 +1,26 @@
+=begin pod
+
+=TITLE class X::Proc::Async::MustBeStarted
+
+=SUBTITLE Exception class for L<Proc::Async> methods that must be called after the program has been spawned
+
+    class X::Proc::Async::MustBeStarted is Exception { ... }
+
+Several methods from L<Proc::Async> excpect that the external program has been
+spawned (by calling C<.start> on it), including C<say>, C<write>, C<print> and
+C<close-stdin>. If one of those methods is called before C<.start> was called,
+they throw an exception of type C<X::Proc::Async::MustBeStarted>.
+
+    Proc::Async.new('echo', :w).say(42);
+    # dies with    Process must be started first before calling 'say'
+
+=head1 Methods
+
+=head2 method method
+
+    method method(X::Proc::Async::MustBeStarted:D) returns Str:D
+
+Returns the name of the method that was illegally called before starting the
+external program.
+
+=end pod

lib/Type/X/Proc/Async/OpenForWriting.pod

@@ -0,0 +1,26 @@
+=begin pod
+
+=TITLE class X::Proc::Async::OpenForWriting
+
+=SUBTITLE Exception class for write operations on a L<Proc::Async> object opened for reading
+
+    class X::Proc::Async::OpenForWriting is Exception { ... }
+
+When a L<Proc::Async> object is opened only for reading from the external
+program (no C<:w> passed to open), and a write operation such as C<write>,
+C<print> and C<say> is performed, an exception of type
+X<X::Proc::Async::OpenForWriting> is thrown:
+
+    my $proc = Proc::Async.new("echo");
+    $proc.start;
+    $proc.say(42)   # Process must be opened for writing with :w to call 'say'
+
+=head1 Methods
+
+=head2 method method
+
+    method method(X::Proc::Async::OpenForWriting:D:)
+
+Returns the method name that was called and which caused the exception.
+
+=end pod