view release on metacpan or  search on metacpan

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

categorize arguments. Not unlike the C<tags> property.

=head3 pos

Non-negative integer. Argument position when specified in an ordered fashion,
e.g. in an array. Starts from zero.

=head3 slurpy

Bool. Only relevant if B<pos> is specified, specify whether argument should
gobble up all remaining values in an ordered argument list into an array.

Old alias: L</greedy>

=head3 greedy

Old alias for L</slurpy>. Will be removed in Rinci 1.2.

=head3 partial (argument property)

Bool. Whether or not argument value can be sent partially. Only argument types
that have a length notion can be set as partial (e.g. C<str> where the unit is
character, C<buf> where the unit is byte, and C<array> where the unit is
element).

There should at most be one argument with this property set to true.

To send partial argument, you can use the special arguments C<-arg_len> (total
argument length), C<-arg_part_start> (start position of the part that is being
sent), C<-arg_part_len> (length of part that is being sent). Example (in Perl):

 # function metadata
 {
     v => 1.1,
     summary => "Upload a file",
     args => {
         name => {schema=>"str*", req=>1},
         data => {schema=>"buf*", req=>1, partial=>1},
     },
 }

 # function usage example: send the first 10MiB of data
 upload_file(name=>"myvideo.mp4", data=>substr($data, 0, 10_000_000),
             -arg_len        => 24_500_000,
             -arg_part_start =>          0,
             -arg_part_len   => 10_000_000);
 # send the next 10MiB
 upload_file(name=>"myvideo.mp4", data=>substr($data, 10_000_000, 10_000_000),
             -arg_len        => 24_500_000,
             -arg_part_start => 10_000_000,
             -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,
defaults to argument's schema), C<is_flag> (bool, optional, if set to 1 then it
is a shortcut for specifying C<schema> to C<< ["bool", {"is":1}] >>), C<code> (a
code to set argument value, optional, will be given C<< (\%args, $val) >>); if
not set, the default behavior is simply to set the argument value).

=head3 cmdline_on_getopt

Code. A hook that will be called when argument is specified as a command-line
option. In Perl, hook will be called with a hash argument containing this key:
C<arg> (str, argument name), C<value> (str, option value), C<args> (hash, the
argument hash defined so far).

This can be useful if you want to process a command-line option directly on a
per-option basis instead of getting the final resulting argument value. For
example (in Perl):

 args => {
     library => {
         schema            => ['array*' => of => 'str*'],
         cmdline_aliases   => { I => {} },
         cmdline_on_getopt => sub {
             my %args = @_;
             require lib;
             lib->import($args{value});
         },
     },
     module => {
         schema            => ['array*' => of => 'str*'],
         cmdline_aliases   => { M => {} },
         cmdline_on_getopt => sub {
             my %args = @_;
             require Module::Load;
             Module::Load::load($args{value});
         },
     },
 }

With command-line argument like this:

 -I dir1 -M mod1 -I dir2 -M mod2

Without any C<cmdline_on_getopt> hooks, the function will receive this argument
hash:

 { library => ['dir1', 'dir2'], module => ['mod1', 'mod2'] }

but there is no way to know the order of options being specified in the
command-line. With the hooks, the function can load modules correctly (e.g.
loading C<mod1> won't search in C<dir2> as that directory has not been added by
-I).

=head3 completion (argument property)

Code. A code to supply argument value completion. Will be explained in the
examples.

=head3 index_completion

Code. A code to supply argument element index completion. Applicable to the
following argument types:

B<hash>: for completing hash pair keys. (See also C<element_completion> for
completing hash pair values).

See examples for how to use this property.

=head3 element_completion

Code. A code to supply argument element value completion. Applicable to the
following argument types:

B<array>: for completing array element values.

B<hash>: for completing hash pair values. (See also C<index_completion> for
completing hash keys).

See examples for how to use this property.

=head3 is_password

Experimental. Bool. Describe that argument holds password. Programs can react to
this in several ways, for example they can turn off echoing to terminal when
asking value from standard input. Or they can redact values to C<****> when
logging.

=head3 cmdline_src

Str. Normally in a command-line program, command-line options and arguments will
map to function arguments, e.g. C<--arg 2> will set the C<foo> argument to C<2>
and positional arguments (argument which specifies the C<pos> property and
optionally also a C<slurpy> property with true value) will get or slurp
command-line arguments.

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>.

=item * stdin_or_file

This means that program should get argument value from content of file (the name
of which is given from the first remaining command-line argument after all other
arguments/options have been processed), or, if none is provided, from standard
input.

=item * stdin_or_files

This means that program should get argument value from content of files (the
names of which are taken from the remaining command-line arguments after all
other arguments/options have been processed), or, or if no command-line argument
remains, from standard input. This behavior is similar to the C<< <> >> (diamond
operator) in Perl.

=item * stdin_or_args

This means that program should get argument value from remaining command-line
argument(s), or if no command-line argument remains, from standard input.

=item * stdin_line

This means that program should get argument value from a line of standard input;
newline ending will be removed from the argument value.

Arguments with C<cmdline_src> of C<stdin_line> will be processed before
C<stdin>/C<stdin_or_file>/C<stdin_or_files>/C<stdin_or_args>.

=back

Other sources might be defined in the future.

TODO: Define C<web_src> property?

TODO: A way to define record separator?

=head3 cmdline_prompt

Str. String to display when asking for argument value from stdin (if
C<cmdline_src> property value is C<stdin_line>.

TODO: cmdline_prompt_template?

=head3 meta

Experimental. Hash. This allows specifying argument submetadata, used e.g. when
dealing with forms (a form field/widget can be a subform). Value is Rinci
function metadata.

=head3 element_meta

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

The above example says that only one of C<delete>, C<add>, C<edit> can be
specified. And if any of C<red>, C<green>, C<blue> is specified then all must be
specified. In CLI context this translates to:

 % prog --delete item
 % prog --delete --add item ; # error, both --delete and --add specified

 % prog --red 255 --green 255 --blue 0
 % prog --red 255 --blue 0 ; # error, --green is missing

Another example:

 XXX

=head2 args_as

Str. Specify in what form the function expects the arguments. The value is
actually implementation-specific since it describes the function implementation.
For example in L<Perinci> for Perl, these values are recognized: C<array>,
C<hash>, C<arrayref>, C<hashref>. This property is useful for wrapper to be able
to convert one form to another.

The default value is also left to the implementation.

For interimplementation communication (e.g. via L<Riap::HTTP> or L<Riap::TCP>),
named arguments are always used so this property is irrelevant.

=head2 result

DefHash. Specify function return value. It is a defhash containing keys:

=over 4

=item * summary (result property)

From DefHash. Like the C<summary> property in variable metadata.

=item * description (result property)

From DefHash. Like the C<description> property. Suggested to be formatted to 78
columns.

=item * schema (result property)

A Sah schema to validate the result (the third element in the envelope result).
This schema should only be tested if status is 200. See also: C<statuses>.

=item * statuses

Hash. Can be used to specify different result schema for different statuses. For
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:

 # function metadata
 {
     v => 1.1,
     summary => 'Read file contents',
     args => {
         name => {
             summary => 'File name',
             schema  => 'str*',
             req     => 1,
         },
     },
     result => {schema=>'buf*', partial=>1},
 }

 # example function usage: request to read first 10MiB of file content,
 # -result_part_start defaults to 0.
 my $res = read_file(name=>'myvideo.mp4', -res_part_len=>10000000);
 # => [206, "Partial content", "data...", {len=>24500000, part_start=>0, part_len=>10000000}]

 # request the next 10MiB
 my $res = read_file(name=>'myvideo.mp4', -res_part_start=>10000000, -res_part_len=>10000000);
 # => [206, "Partial content", "data...", {len=>24500000, part_start=>10000000, part_len=>10000000}]

 # request the next 10MiB, since this actual file size is only 24500000,
 # function should return 416 status
 my $res = read_file(name=>'myvideo.mp4', -res_part_start=>20000000, -res_part_len=>10000000);
 # => [416, "Request range not satisfiable, file size is only 24500000"]

 # request the next 4.5MiB, this time succeeds
 my $res = read_file(name=>'myvideo.mp4', -res_part_start=>20000000, -res_part_len=>4500000);
 # => [206, "Partial content", "data...", {len=>24500000, part_start=>20000000, part_len=>4500000}]

Partial result request to a function which does not support partial result might
have the effect of the whole content being returned (status 200) or status 416.

=back

Note that since functions normally return enveloped result, instead of
returning:

 RESULT

your functions normally have to return an enveloped result:

 [STATUS, MESSAGE, RESULT, METADATA]

Examples:

 # result is an integer
 result => {schema => 'int*'}