Debian Codegraph @

lib/Rinci/FAQ.pod

raw
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