Rinci

 view release on metacpan or  search on metacpan

Changes  view on Meta::CPAN

	  requiring {only one,all} members of a group of args must be specified
	  (and possibly others in the future). UPDATE: Now replaced with
	  'args_rels'.

	- Specify argument specification property 'deps', to allow an argument
	  to depend on others.


1.1.71  2015-01-17  Released-By: PERLANCAR

	- Specify that streaming input and output now uses coderef instead of
	  filehandle/etc. This is simpler and has the side-effects of easier to
	  do wrapping for (see Perinci::Sub::Wrapper) where one can just wrap
	  the coderef to do per-record validation of streaming input/output.


1.1.70  2014-11-19  Released-By: PERLANCAR

	- Add 'links' property to arg spec.


1.1.69  2014-10-30  Released-By: PERLANCAR

	- No spec changes.

lib/Rinci/FAQ.pod  view on Meta::CPAN

For handling binary data when writing Perl-based command-line applications, see
L<Perinci::CmdLine::Manual::Examples>.

=item * How to accept partial data?

First, set an argument property C<partial> to true to signify that this argument
accept partial value. You can then call with special arguments C<-arg_len>,
C<-arg_part_start>, C<-arg_part_len>. See L<Rinci::function> for more details.
L<Riap::HTTP> can also do this via HTTP Content-Range.

=item * How to accept streaming input?

Many program environments (like in Unix) have the concept of standard input.
Rinci provides a thin abstraction over this. You can set the argument property
C<stream> to true. This way, in most implementation like in Perl, your function
will receive the argument value as filehandle which it can then read from. See
C<partial> property in C<args> function metadata property in L<Rinci::function>
for an example.

Your function can also read from standard input directly, but this means you
cannot use conveniences like the C<cmdline_src>, where the command-line
framework can supply an argument value for you from various sources including
standard input and/or files.

=item * How to produce streaming output?

Many program environments (like in Unix) have the concept of standard output. To
produce output stream, you can set result metadata property C<stream> to true.
And then in the result you can put a filehandle or an object that responds to
getline/getitem methods.

=item * What is the difference between accepting partial data and streaming input?

If a function accepts partial data, to send a large data without taking up too
much memory, a caller needs to break the data into several parts and call the
function several times, each with a different part.

If a function accepts a stream input, to send a large data a caller can send a
filehandle/iterator object from which the function can read the data
iteratively.

Stream input is easier and simpler for the function writer to write. A caller
also only needs to call the function once instead of multiple times. However,
there is no resume capability.

On the other hand, partial input data is easier to implement with Riap::HTTP, as
it maps rather closely to HTTP Content-Range.

If you are uploading a large data over a network to a function, partial input
data is preferred because of its ease to work with HTTP and its resume ability.

However, if input is really a stream (i.e. unknown/infinite length), then
streaming input is the option to use.

=item * What is the difference between returning partial result and streaming output?

If a function can return partial result, to retrieve a large result from a
function a caller can calls several times and each time request to retrieve
parts of result.

If a function returns output stream, a caller can then retrieve data from the
stream iteratively.

Output stream is easier to handle by the caller. The caller also only needs to
call once instead of multiple times. However, there is no resume capability.

lib/Rinci/function.pod  view on Meta::CPAN

             -arg_part_len   => 10_000_000);
 # send the last 4.5 MiB
 upload_file(name=>"myvideo.mp4", data=>substr($data, 20_000_000),
             -arg_len        => 24_500_000,
             -arg_part_start => 20_000_000,
             -arg_part_len   =>  4_500_000);

=head3 stream (argument property)

Bool. By setting this property to true, function can specify that it accepts
streaming data for this argument. It is useful when argument value is large or
of undetermined/infinite length. To send value as a stream, caller must send a
subroutine reference (callback) instead which the function will call repeatedly
until it gets undef to signify exhaustion of data.

=head3 cmdline_aliases

Hash. Specify aliases for use in command-line options (or other possibly
suitable situation where arguments are parsed from command-line-like options).
Keys are alias names, values are itself hashes (alias specification). Valid
alias specification keys: C<summary> (a string, optional), C<schema> (optional,

lib/Rinci/function.pod  view on Meta::CPAN

In some cases, this is not convenient. When supplying larger amount of data, a
complex structures, or a stream, we might want to use other sources. The
C<cmdline_src> property can be set to one of the following value for this
purpose:

=over

=item * file

Command-line option/argument value will be treated as filename and function
argument will be set to content of the file (or in the case of streaming
argument, to a callback which can be used to get the file's content).

=item * stdin

This means that program should get function argument from the whole standard
input until EOF.

Note that only one argument can have its source set to C<stdin> or
C<stdin_or_file> or C<stdin_or_files> or C<stdin_or_args>.

lib/Rinci/function.pod  view on Meta::CPAN

example:

 statuses => {
     206 => {
         schema => 'str*',
     },
 }

=item * stream (result property)

Bool. Specify that function returns streaming output. Note that function can
also signify streaming output by setting result metadata property C<stream> to
true.

Function must then return a subroutine reference (callback) as its actual result
which the caller can call repeatedly until it gets undef to signify exhaustion.

=item * partial (result property)

Bool. If set to true, specify that it is possible to request partial result. An
example is in a function that reads contents from (potentially large) files: