.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "Rinci::FAQ 3pm" .TH Rinci::FAQ 3pm "2016-12-28" "perl v5.24.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Rinci::FAQ \- Metadata for your functions/methods .SH "VERSION" .IX Header "VERSION" This document describes version 1.1.84 of Rinci::FAQ (from Perl distribution Rinci), released on 2016\-12\-28. .SH "FAQ" .IX Header "FAQ" .SS "Rinci::function" .IX Subsection "Rinci::function" .IP "\(bu" 4 Why do you make enveloped result an arary instead of hash? .Sp For example, a hash-based enveloped result can be something like: .Sp .Vb 1 \& {status=>200, message=>"OK", result=>42, meta1=>..., meta2=>...} .Ve .Sp This has the benefit of a single container, but I picked array because of the brevity for simple cases (which are the majority), e.g.: .Sp .Vb 2 \& [200] # versus {status=>200} \& [200, "OK"] # versus {status=>200, message=>"OK"} .Ve .Sp When handling enveloped result, the array version is also shorter: .Sp .Vb 2 \& if ($res\->[0] == 200) { ... } \& # versus: if ($res\->{status} == 200) { ... } \& \& print "Error $res\->[0] \- $res\->[1]"; \& # versus: print "Error $res\->{status} \- $res\->{message}"; .Ve .Sp The hash version is more obvious for first-time reader, but after just some amount of time, \f(CW\*(C`$res\->[0]\*(C'\fR, \f(CW\*(C`$res\->[1]\*(C'\fR will become obvious if you use it consistently. .Sp As a bonus, arrays are faster and more space-efficient than hashes. .IP "\(bu" 4 How do you indicate transient/temporary vs permanent errors? .Sp Some protocols, like \s-1SMTP\s0 or \s-1POP,\s0 defines 4xx codes as temporary errors and 5xx as permanent ones. This gives clue to clients whether to retry or not. \s-1HTTP,\s0 which Rinci is modelled after, does not provide such distinction to its status codes. However, Rinci defines a \f(CW\*(C`perm_err\*(C'\fR result metadata that can be used for such purpose, e.g.: .Sp .Vb 2 \& [500, "Can\*(Aqt submit mail, we are being blocked by RBL", undef, \& {perm_err=>0}] \& \& [500, "Can\*(Aqt submit mail, destination address does not exist", undef, \& {perm_err=>1}] .Ve .IP "\(bu" 4 How to handle binary data? .Sp To accept binary data, you can set one or more arguments as having the schema type \f(CW\*(C`buf\*(C'\fR (instead of \f(CW\*(C`str\*(C'\fR): .Sp .Vb 3 \& args => { \& data => { schema => \*(Aqbuf*\*(Aq, req=>1 }, \& } .Ve .Sp To return binary data, you can set result's schema type to \f(CW\*(C`buf\*(C'\fR, e.g.: .Sp .Vb 1 \& result => { schema => \*(Aqbuf*\*(Aq } .Ve .Sp For handling binary data when writing Perl-based command-line applications, see Perinci::CmdLine::Manual::Examples. .IP "\(bu" 4 How to accept partial data? .Sp First, set an argument property \f(CW\*(C`partial\*(C'\fR to true to signify that this argument accept partial value. You can then call with special arguments \f(CW\*(C`\-arg_len\*(C'\fR, \&\f(CW\*(C`\-arg_part_start\*(C'\fR, \f(CW\*(C`\-arg_part_len\*(C'\fR. See Rinci::function for more details. Riap::HTTP can also do this via \s-1HTTP\s0 Content-Range. .IP "\(bu" 4 How to accept streaming input? .Sp 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 \&\f(CW\*(C`stream\*(C'\fR 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 \&\f(CW\*(C`partial\*(C'\fR property in \f(CW\*(C`args\*(C'\fR function metadata property in Rinci::function for an example. .Sp Your function can also read from standard input directly, but this means you cannot use conveniences like the \f(CW\*(C`cmdline_src\*(C'\fR, where the command-line framework can supply an argument value for you from various sources including standard input and/or files. .IP "\(bu" 4 How to produce streaming output? .Sp Many program environments (like in Unix) have the concept of standard output. To produce output stream, you can set result metadata property \f(CW\*(C`stream\*(C'\fR to true. And then in the result you can put a filehandle or an object that responds to getline/getitem methods. .IP "\(bu" 4 What is the difference between accepting partial data and streaming input? .Sp 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. .Sp 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. .Sp 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. .Sp On the other hand, partial input data is easier to implement with Riap::HTTP, as it maps rather closely to \s-1HTTP\s0 Content-Range. .Sp 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 \s-1HTTP\s0 and its resume ability. .Sp However, if input is really a stream (i.e. unknown/infinite length), then streaming input is the option to use. .IP "\(bu" 4 What is the difference between returning partial result and streaming output? .Sp 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. .Sp If a function returns output stream, a caller can then retrieve data from the stream iteratively. .Sp 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. .Sp On the other hand, partial result is easier to implement with Riap::HTTP, as it maps rather closely to \s-1HTTP\s0 Content-Range. .Sp If you are retrieving a large data over a network from a function, partial result is preferred because of its ease to work with \s-1HTTP\s0 .SH "HOMEPAGE" .IX Header "HOMEPAGE" Please visit the project's homepage at . .SH "SOURCE" .IX Header "SOURCE" Source repository is at . .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests on the bugtracker website .PP When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature. .SH "AUTHOR" .IX Header "AUTHOR" perlancar .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2016 by perlancar@cpan.org. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.