Update docs

2 files changed, 205 insertions, 24 deletions

diff --git a/Capture.xs b/Capture.xs
index 067180c..19da27b 100644
--- a/Capture.xs
+++ b/Capture.xs
@@ -3,18 +3,6 @@
 MODULE = POSIX::Run::Capture            PACKAGE = POSIX::Run::Capture PREFIX = capture_
 PROTOTYPES: ENABLE
 
-=head2 new POSIX::Run::Capture
-
-   new POSIX::Run::Capture([ $command, @args ]);
-
-   new POSIX::Run::Capture(argv => [ $command, @args ],
-                           stdout => sub { ... },
-                           stderr => sub { ... },
-                           timeout => N)
-                           
-
-=cut
-        
 POSIX::Run::Capture
 capture_new(package, ...)
         char *package;
@@ -66,7 +54,8 @@ capture_new(package, ...)
                                         croak("program argument is not a scalar");
                                 else 
                                         prog = val;
-                        } else if (strcmp(kw, "input") == 0) {
+                        } else if (strcmp(kw, "input") == 0
+                                   || strcmp(kw, "stdin") == 0) {
                                 input = val;
                         } else
                                 croak("unknown keyword argument %s", kw);
@@ -80,6 +69,14 @@ void
 capture_DESTROY(cp)
         POSIX::Run::Capture cp;
 
+=head2 $obj->set_argv_ref($aref)
+
+Sets command argument vector. The B<$aref> parameter is an array reference.
+
+This is an auxiliary method. Use B<set_argv> instead.
+
+=cut
+        
 void
 capture_set_argv_ref(cp, argv)
         POSIX::Run::Capture cp;
diff --git a/lib/POSIX/Run/Capture.pm b/lib/POSIX/Run/Capture.pm
index dacdcfd..5dedad0 100644
--- a/lib/POSIX/Run/Capture.pm
+++ b/lib/POSIX/Run/Capture.pm
@@ -64,27 +64,211 @@ POSIX::Run::Capture - run command and capture its output
 =head1 SYNOPSIS
 
   use POSIX::Run::Capture;
-  
 
+  $obj = new POSIX::Run::Capture(argv => [ $command, @args ],
+                                 program => $prog,
+                                 stdin => $fh_or_string,
+                                 stdout => sub { ... },
+                                 stderr => sub { ... },
+                                 timeout => $n);
+  $obj->run;
+
+  $num = $obj->errno;
+  $num = $obj->status;
+  $num = $obj->length($chan);
+  $num = $obj->nlines($chan);
+
+  $str = $obj->next_line($chan);
+  $aref = $obj->get_lines($chan);
+  $obj->rewind($chan)
+
+  $obj->set_program($prog);
+  $obj->set_timeout($n);
+  $obj->set_input($fh_or_string);
+
+  $aref = head3 $obj->argv;
+  $str = =head3 $obj->program
+  $num = $obj->timeout;
+    
 =head1 DESCRIPTION
 
-The API is in development.
+This module prefers performance and effectiveness over portability. As its
+name suggests, it can be used only on POSIX systems.    
+    
+=head2 new POSIX::Run::Capture
+
+Creates a new capture object. There are three possible invocation modes.
+
+  new POSIX::Run::Capture(argv => [ $command, @args ],
+                          program => $prog,
+                          stdin => $fh_or_string,
+                          stdout => sub { ... },
+                          stderr => sub { ... },
+                          timeout => $n)
+
+When named arguments are used, the following keywords are allowed:
+
+=over 4
+
+=item B<argv>
+
+Defines the command (B<C argv[0]>) and its arguments. In the absense of
+B<program> argument, B<$argv[0]> will be run.
+
+=item B<program>
+
+Sets the pathname of binary file to run.        
+
+=item B<stdin> or B<input>
+
+Supplies standard input for the command. The argument can be a string or
+a file handle.
+
+=item B<stdout>
+
+Sets the I<line monitor> function for standard output. Line monitor is
+invoked each time a complete line is read, or the EOF is hit on the standard
+output. The acquired line is passed to the monitor as its argument. The
+following example monitor function prints its argument to STDOUT:
+
+    sub stdout_monitor {
+        my $line = shift;
+        print $line;
+    }
+
+Notice that the last line read can lack the teminating newline character.
+
+=item B<stderr>
+
+Sets the I<line monitor> function for standard error stream. See the
+description above.
+
+=item B<timeout>
+
+Sets execution timeout, in seconds. If the program takes longer than B<$n>
+seconds to terminate, it will be forcibly terminated (by sending the B<SIGKILL>
+signal).
+
+=back
     
-=head2 EXPORT
+=head3 new POSIX::Run::Capture([ $command, @args ]);
+
+A simplified way of creating the object, equivalent to
 
-None by default.  Use B<:std> to export the B<STDOUT> and B<STDERR> constants.
+   new POSIX::Run::Capture(argv => [ $command, @args ]);
+
+=head3 new POSIX::Run::Capture;
+
+Crates an empty capture object.
+
+Whatever constructor is used, the necessary parameters can be set
+or changed later, using B<set_argv>, B<set_program>, B<set_input>,
+and B<set_timeout>.
+
+Monitors can be defined only when creating the object.
+
+=head2 Modifying the object.
+
+The following methods modify the object:    
     
+=head3 $obj->set_program($prog)
+
+Sets the pathname of the command to run.
 
-=head1 SEE ALSO
+=head3 $obj->set_timeout($n)
+
+Sets runtime timeout, in seconds.
+
+=head3 $obj->set_input($fh_or_string)
+
+Sets standard input for the program. Argument must be either a filehandle
+open for reading or a string. The filehandle will be repositioned to its
+beginning prior to use.
+
+=head2 Accessors
+
+The following accessors return parameters associated with the object:    
+    
+=head3 $obj->argv
+
+Returns a reference to the B<argv> array associated with the object.
+
+=head3 $obj->program
+
+Returns the pathname of the executable program.
+
+=head3 $obj->timeout
+
+Returns the runtime timeout or B<0> if no timeout is set.
+
+=head2 Running the command
+    
+=head3 $obj->run
+
+Runs the program. Returns B<1> on successful termination, B<0> otherwise.
+
+=head3 $obj->errno
+
+If the last call to B<run> returned false, this method returns the
+value of the system error number (the C B<errno> variable).
+
+Upon successful return from B<$obj-E<gt>run>, the following accessors can
+be used:    
+    
+=head3 $obj->status
+
+Returns the termination status of the program. Use the macros from
+B<POSIX :sys_wait_h> to analyze it. E.g.:
+
+    use POSIX qw(:sys_wait_h);
+    if ($obj->run()) {