From 73365dbc9cda550963df506ea739cbcd73817106 Mon Sep 17 00:00:00 2001 From: Sergey Poznyakoff Date: Mon, 24 Jul 2017 13:41:28 +0300 Subject: Update docs --- Capture.xs | 23 +++--- lib/POSIX/Run/Capture.pm | 206 ++++++++++++++++++++++++++++++++++++++++++++--- 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 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 + +Defines the command (B) and its arguments. In the absense of +B argument, B<$argv[0]> will be run. + +=item B + +Sets the pathname of binary file to run. + +=item B or B + +Supplies standard input for the command. The argument can be a string or +a file handle. + +=item B + +Sets the I 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 + +Sets the I function for standard error stream. See the +description above. + +=item B + +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 +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 and B 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, B, B, +and B. + +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 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 returned false, this method returns the +value of the system error number (the C B variable). + +Upon successful return from B<$obj-Erun>, the following accessors can +be used: + +=head3 $obj->status + +Returns the termination status of the program. Use the macros from +B 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 and +B, 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, B and B, which correspond to +numbers of standard input, output and error channels. =head1 AUTHOR -- cgit v1.2.1