view release on metacpan or  search on metacpan

lib/Riap.pod  view on Meta::CPAN

Below are actions that are available for the C<function> entities. At least
C<call> must be implemented by the server.

=head2 Action: B<call>

Call a function and return its result. Additional request keys include:

=over 4

=item * B<args>

Hash, optional, function arguments, defaults to C<{}>.

In general, do not pass special arguments (arguments prefixed by dash C<->) as
they might be stripped/removed prior to processing. Some special arguments can
be passed through other means (e.g. see C<confirm> and C<dry_run> below).

=item * B<confirm> => BOOL

Optional. If set to true, will pass special argument C<< -confirm => 1 >> to
function. This is used as confirmation when function can return status 331
(requires confirmation). See L<Rinci::function> for more details on status 331.

=item * B<dry_run> => BOOL

Optional. If set to true, will either pass C<< -dry_run => 1 >> to function
supporting dry run, or C<< -tx_action => 'check_state' >> to function supporting
transaction (can more or less be regarded as the dry run equivalent).

=item * B<arg_len> => int

Will be passed to function as special argument C<-arg_len> to send partial
argument value.

=item * B<arg_part_start> => int

Will be passed to function as special argument C<-arg_part_start> to send
partial argument value.

=item * B<art_part_len> => int

Will be passed to function as special argument C<-arg_part_len> to send partial
argument value.

=item * B<res_part_start> => int

Will be passed to function as special argument C<-res_part_start> to request
partial result.

=item * B<res_part_len> => int

Will be passed to function as special argument C<-res_part_len> to request
partial result.

=item * B<stream_arg> => bool

Optional. If set to true, then will provide a filehandle or an iterable object
as argument value for the function, where the function can read data from. And
will also send special argument C<< -arg_stream => 1 >> to function. Note that
the function must have exactly a single argument that has its C<streaming>
property set to true. Otherwise, server MUST send 501 (unimplemented) response.

=back

=head2 Action: B<complete_arg_val>

Complete function argument value, a la Bash tab completion where you have a
semicompleted word and request possible values started by that word. Additional
Riap request keys include:

=over 4

=item * B<arg>

String, required, the name of function argument to complete.

=item * B<word>

String, optional, word that needs to be completed. Defaults to empty string.

=back

The server should return a list of possible completions. Example, when
completing a C<delete_user> function for the argument C<username>, and C<word>
is "st", the server might return:

 [200,"OK",
  ["stella","steven","stuart"],
  {"riap.v":1.2}
 ]

When there is no completion, the server should return an empty list:

 [200,"OK",
  [],
  {"riap.v":1.2}
 ]

=head2 Action: B<complete_arg_elem>

This is just like C<complete_arg_val>, except this tries to complete the value
of an element of an array argument, instead of the value of the argument itself.
This is useful for example when completing this command-line:

 % somecmd --category foo --category <tab>

where C<category> is argument of type array and its element contain some
restricted value. The command-line option C<--category> can be specified
multiple times to set the array elements.

=over 4

=item * B<arg>

String, required, the name of function argument to complete.

=item * B<index>

Integer, required, which element to complete for (starts from 0 for the first
element).