| 1 |
package Rinci::FAQ; # just to make PodWeaver happy |
| 2 |
|
| 3 |
# AUTHORITY |
| 4 |
# DATE |
| 5 |
our $DIST = 'Rinci'; # DIST |
| 6 |
# VERSION |
| 7 |
|
| 8 |
1; |
| 9 |
# ABSTRACT: FAQ on Rinci |
| 10 |
|
| 11 |
__END__ |
| 12 |
|
| 13 |
=pod |
| 14 |
|
| 15 |
=encoding UTF-8 |
| 16 |
|
| 17 |
=head1 NAME |
| 18 |
|
| 19 |
Rinci::FAQ - FAQ on Rinci |
| 20 |
|
| 21 |
=head1 VERSION |
| 22 |
|
| 23 |
This document describes version 1.1.104 of Rinci::FAQ (from Perl distribution Rinci), released on 2023-09-30. |
| 24 |
|
| 25 |
=head1 FAQ |
| 26 |
|
| 27 |
=head2 Rinci::function |
| 28 |
|
| 29 |
=over |
| 30 |
|
| 31 |
=item * Why do you make enveloped result an array instead of hash? |
| 32 |
|
| 33 |
For example, a hash-based enveloped result can be something like: |
| 34 |
|
| 35 |
{status=>200, message=>"OK", result=>42, meta1=>..., meta2=>...} |
| 36 |
|
| 37 |
This has the benefit of a single container, but I picked array because of the |
| 38 |
brevity for simple cases (which are the majority), e.g.: |
| 39 |
|
| 40 |
[200] # versus {status=>200} |
| 41 |
[200, "OK"] # versus {status=>200, message=>"OK"} |
| 42 |
|
| 43 |
When handling enveloped result, the array version is also shorter: |
| 44 |
|
| 45 |
if ($res->[0] == 200) { ... } |
| 46 |
# versus: if ($res->{status} == 200) { ... } |
| 47 |
|
| 48 |
print "Error $res->[0] - $res->[1]"; |
| 49 |
# versus: print "Error $res->{status} - $res->{message}"; |
| 50 |
|
| 51 |
The hash version is more obvious for first-time reader, but after just some |
| 52 |
amount of time, C<< $res->[0] >>, C<< $res->[1] >> will become obvious if you |
| 53 |
use it consistently. |
| 54 |
|
| 55 |
As a bonus, arrays are faster and more space-efficient than hashes. |
| 56 |
|
| 57 |
=item * How do you indicate transient/temporary vs permanent errors? |
| 58 |
|
| 59 |
Some protocols, like SMTP or POP, defines 4xx codes as temporary errors and 5xx |
| 60 |
as permanent ones. This gives clue to clients whether to retry or not. HTTP, |
| 61 |
which Rinci is modelled after, does not provide such distinction to its status |
| 62 |
codes. However, Rinci defines a C<perm_err> result metadata that can be used for |
| 63 |
such purpose, e.g.: |
| 64 |
|
| 65 |
[500, "Can't submit mail, we are being blocked by RBL", undef, |
| 66 |
{perm_err=>0}] |
| 67 |
|
| 68 |
[500, "Can't submit mail, destination address does not exist", undef, |
| 69 |
{perm_err=>1}] |
| 70 |
|
| 71 |
=item * How to handle binary data? |
| 72 |
|
| 73 |
To accept binary data, you can set one or more arguments as having the schema |
| 74 |
type C<buf> (instead of C<str>): |
| 75 |
|
| 76 |
args => { |
| 77 |
data => { schema => 'buf*', req=>1 }, |
| 78 |
} |
| 79 |
|
| 80 |
To return binary data, you can set result's schema type to C<buf>, e.g.: |
| 81 |
|
| 82 |
result => { schema => 'buf*' } |
| 83 |
|
| 84 |
For handling binary data when writing Perl-based command-line applications, see |
| 85 |
L<Perinci::CmdLine::Manual::Examples>. |
| 86 |
|
| 87 |
=item * How to accept partial data? |
| 88 |
|
| 89 |
First, set an argument property C<partial> to true to signify that this argument |
| 90 |
accept partial value. You can then call with special arguments C<-arg_len>, |
| 91 |
C<-arg_part_start>, C<-arg_part_len>. See L<Rinci::function> for more details. |
| 92 |
L<Riap::HTTP> can also do this via HTTP Content-Range. |
| 93 |
|
| 94 |
=item * How to accept streaming input? |
| 95 |
|
| 96 |
Many program environments (like in Unix) have the concept of standard input. |
| 97 |
Rinci provides a thin abstraction over this. You can set the argument property |
| 98 |
C<stream> to true. This way, in most implementation like in Perl, your function |
| 99 |
will receive the argument value as filehandle which it can then read from. See |
| 100 |
C<partial> property in C<args> function metadata property in L<Rinci::function> |
| 101 |
for an example. |
| 102 |
|
| 103 |
Your function can also read from standard input directly, but this means you |
| 104 |
cannot use conveniences like the C<cmdline_src>, where the command-line |
| 105 |
framework can supply an argument value for you from various sources including |
| 106 |
standard input and/or files. |
| 107 |
|
| 108 |
=item * How to produce streaming output? |
| 109 |
|
| 110 |
Many program environments (like in Unix) have the concept of standard output. To |
| 111 |
produce output stream, you can set result metadata property C<stream> to true. |
| 112 |
And then in the result you can put a filehandle or an object that responds to |
| 113 |
getline/getitem methods. |
| 114 |
|
| 115 |
=item * What is the difference between accepting partial data and streaming input? |
| 116 |
|
| 117 |
If a function accepts partial data, to send a large data without taking up too |
| 118 |
much memory, a caller needs to break the data into several parts and call the |
| 119 |
function several times, each with a different part. |
| 120 |
|
| 121 |
If a function accepts a stream input, to send a large data a caller can send a |
| 122 |
filehandle/iterator object from which the function can read the data |
| 123 |
iteratively. |
| 124 |
|
| 125 |
Stream input is easier and simpler for the function writer to write. A caller |
| 126 |
also only needs to call the function once instead of multiple times. However, |
| 127 |
there is no resume capability. |
| 128 |
|
| 129 |
On the other hand, partial input data is easier to implement with Riap::HTTP, as |
| 130 |
it maps rather closely to HTTP Content-Range. |
| 131 |
|
| 132 |
If you are uploading a large data over a network to a function, partial input |
| 133 |
data is preferred because of its ease to work with HTTP and its resume ability. |
| 134 |
|
| 135 |
However, if input is really a stream (i.e. unknown/infinite length), then |
| 136 |
streaming input is the option to use. |
| 137 |
|
| 138 |
=item * What is the difference between returning partial result and streaming output? |
| 139 |
|
| 140 |
If a function can return partial result, to retrieve a large result from a |
| 141 |
function a caller can calls several times and each time request to retrieve |
| 142 |
parts of result. |
| 143 |
|
| 144 |
If a function returns output stream, a caller can then retrieve data from the |
| 145 |
stream iteratively. |
| 146 |
|
| 147 |
Output stream is easier to handle by the caller. The caller also only needs to |
| 148 |
call once instead of multiple times. However, there is no resume capability. |
| 149 |
|
| 150 |
On the other hand, partial result is easier to implement with Riap::HTTP, as it |
| 151 |
maps rather closely to HTTP Content-Range. |
| 152 |
|
| 153 |
If you are retrieving a large data over a network from a function, partial |
| 154 |
result is preferred because of its ease to work with HTTP |
| 155 |
|
| 156 |
=back |
| 157 |
|
| 158 |
=head1 HOMEPAGE |
| 159 |
|
| 160 |
Please visit the project's homepage at L<https://metacpan.org/release/Rinci>. |
| 161 |
|
| 162 |
=head1 SOURCE |
| 163 |
|
| 164 |
Source repository is at L<https://github.com/perlancar/perl-Rinci>. |
| 165 |
|
| 166 |
=head1 AUTHOR |
| 167 |
|
| 168 |
perlancar <[email protected]> |
| 169 |
|
| 170 |
=head1 CONTRIBUTING |
| 171 |
|
| 172 |
|
| 173 |
To contribute, you can send patches by email/via RT, or send pull requests on |
| 174 |
GitHub. |
| 175 |
|
| 176 |
Most of the time, you don't need to build the distribution yourself. You can |
| 177 |
simply modify the code, then test via: |
| 178 |
|
| 179 |
% prove -l |
| 180 |
|
| 181 |
If you want to build the distribution (e.g. to try to install it locally on your |
| 182 |
system), you can install L<Dist::Zilla>, |
| 183 |
L<Dist::Zilla::PluginBundle::Author::PERLANCAR>, |
| 184 |
L<Pod::Weaver::PluginBundle::Author::PERLANCAR>, and sometimes one or two other |
| 185 |
Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond |
| 186 |
that are considered a bug and can be reported to me. |
| 187 |
|
| 188 |
=head1 COPYRIGHT AND LICENSE |
| 189 |
|
| 190 |
This software is copyright (c) 2023, 2022, 2021, 2020, 2019, 2018, 2017, 2016, 2015, 2014, 2013, 2012 by perlancar <[email protected]>. |
| 191 |
|
| 192 |
This is free software; you can redistribute it and/or modify it under |
| 193 |
the same terms as the Perl 5 programming language system itself. |
| 194 |
|
| 195 |
=head1 BUGS |
| 196 |
|
| 197 |
Please report any bugs or feature requests on the bugtracker website L<https://rt.cpan.org/Public/Dist/Display.html?Name=Rinci> |
| 198 |
|
| 199 |
When submitting a bug or request, please include a test-file or a |
| 200 |
patch to an existing test-file that illustrates the bug or desired |
| 201 |
feature. |
| 202 |
|
| 203 |
=cut |