Document X::Proc::Async::CharsOrBytes

lib/Type/Proc/Async.pod

@@ -58,7 +58,7 @@ C<say>.
 
 =head2 method stdout
 
-    method stdout(Proc::Async:D:, :$bin) returns Supply:D
+    method stdout(Proc::Async:D: :$bin) returns Supply:D
 
 Returns the L<Supply|/type/Supply> for the external program's standard output
 stream. If C<:bin> is passed, the standard output is passed along in  binary as
@@ -76,9 +76,13 @@ thrown.
 If C<stdout> is not called, the external program's standard output is not
 captured at all.
 
+Note that you cannot call C<stdout> both with and without C<:bin> on the same
+object; it will throw an exception of type L<X::Proc::Async::CharsOrBytes> if
+you try.
+
 =head2 method stderr
 
-    method stderr(Proc::Async:D:, :$bin) returns Supply:D
+    method stderr(Proc::Async:D: :$bin) returns Supply:D
 
 Returns the L<Supply|/type/Supply> for the external program's standard error
 stream. If C<:bin> is passed, the standard error is passed along in  binary as
@@ -96,6 +100,10 @@ thrown.
 If C<stderr> is not called, the external program's standard error stream is not
 captured at all.
 
+Note that you cannot call C<stderr> both with and without C<:bin> on the same
+object; it will throw an exception of type L<X::Proc::Async::CharsOrBytes> if
+you try.
+
 =head2 method start
 
     method start(Proc::Async:D:, :$scheduler = $*SCHEDULER) returns Promise:D

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

@@ -0,0 +1,28 @@
+=begin pod
+
+=TITLE class X::Proc::Async::CharsOrBytes
+
+=SUBTITLE Exception class for L<Proc::Async>, thrown when an output stream is tapped for both text and binary data.
+
+    class X::Proc::Async::CharsOrBytes is Exception { ... }
+
+A L<Proc::Async> object allows subscription to the output or error stream
+either for bytes (L<Blob|/type/Blob>) or for text data (L<Str|/type/Str>), but
+not for both. If you do try both, it throws an exception of type
+C<X::Proc::Async::CharsOrBytes>.
+
+    my $proc = Proc::Async.new('echo');
+    $proc.stdout.tap(&print);
+    $proc.stdout(:bin).tap(&print); # dies with
+                                    # Can only tap one of chars or bytes supply for stdout
+
+=head1 Methods
+
+=head2 method handle
+
+    method handle(X::Proc::Async::CharsOrBytes:D:) returns Str:D
+
+Returns the name of the handle that was accessed both for text and for binary
+data, C<stdout> or C<stderr>.
+
+=end pod