summaryrefslogtreecommitdiffabout
authorSergey Poznyakoff <gray@gnu.org.ua>2017-07-24 10:41:28 (GMT)
committer Sergey Poznyakoff <gray@gnu.org.ua>2017-07-24 10:41:28 (GMT)
commit73365dbc9cda550963df506ea739cbcd73817106 (patch) (side-by-side diff)
tree50c0ba403bcf4fcdd6aa3e142c04142ce734d009
parent1718b7e87b3ce2d588f2412ac41bea6e7048709f (diff)
downloadposixruncapture-73365dbc9cda550963df506ea739cbcd73817106.tar.gz
posixruncapture-73365dbc9cda550963df506ea739cbcd73817106.tar.bz2
Update docs
Diffstat (more/less context) (ignore whitespace changes)
-rw-r--r--Capture.xs23
-rw-r--r--lib/POSIX/Run/Capture.pm206
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()) {
+ if (WIFEXITED($obj->status)) {
+ print "program "
+ . $obj->program
+ . " terminated with code "
+ . WEXITSTATUS($obj->status);
+ } elsif (WIFSIGNALED($self->status)) {
+ print "program "
+ . $obj->program
+ . " terminated on signal "
+ . WTERMSIG($obj->status);
+ } else {
+ print "program "
+ . $obj->program
+ . " terminated with unrecogized code "
+ . $obj->status;
+ }
+ }
+
+=head3 $obj->nlines($chan)
+
+Returns number of lines saved in output channel B<$chan> (1 for stdout or 2
+for stderr). You can also use symbolic constants B<RUNCAP_STDOUT> and
+B<RUNCAP_STDERR>, if you require the module as
+
+ use POSIX::Run::Capture qw(:std);
+
+=head3 $obj->length($chan)
+
+Returns total length in bytes of data captured in output channel B<$chan>.
+
+=head3 $obj->next_line($chan)
+
+Returns next line from the captured channel B<$chan>.
+
+=head3 $obj->get_lines($chan)
+
+Returns a reference to an array of lines captured from channel B<$chan>.
+
+=head3 $obj->rewind($chan)
-Mention other useful documentation such as the documentation of
-related modules or operating system documentation (such as man pages
-in UNIX), or any relevant external documentation such as RFCs or
-standards.
+Rewinds the captured channel B<$chan> to its beginning.
-If you have a mailing list set up for your module, mention it here.
+=head1 EXPORT
-If you have a web site set up for your module, mention it here.
+None by default. Use B<:std> or B<:all> to export the constants
+B<RUNCAP_STDIN>, B<RUNCAP_STDOUT> and B<RUNCAP_STDERR>, which correspond to
+numbers of standard input, output and error channels.
=head1 AUTHOR

Return to:

Send suggestions and report system problems to the System administrator.