.\" 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::resmeta 3pm" .TH Rinci::resmeta 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::resmeta \- Function/method result metadata .SH "VERSION" .IX Header "VERSION" This document describes version 1.1.84 of Rinci::resmeta (from Perl distribution Rinci), released on 2016\-12\-28. .SH "SPECIFICATION VERSION" .IX Header "SPECIFICATION VERSION" .Vb 1 \& 1.1 .Ve .SH "INTRODUCTION" .IX Header "INTRODUCTION" This document describes metadata for function/method result. This specification is part of Rinci. Please do a read up on it first, if you have not already done so. .SH "SPECIFICATION" .IX Header "SPECIFICATION" There are currently several properties being used: .SS "Property: undo_data => \s-1ANY\s0" .IX Subsection "Property: undo_data => ANY" (\s-1DEPRECATED\s0) Explained in \f(CW\*(C`undo\*(C'\fR feature section in Rinci::function. .SS "Property: perm_err => bool" .IX Subsection "Property: perm_err => bool" Indicate that error is permanent (instead of temporary/transient). This is to provide a feature like that found in \s-1SMTP/POP\s0 protocol, where 4xx codes indicate transient errors and 5xx permanent ones. .SS "Properties: func.* => \s-1ANY\s0" .IX Subsection "Properties: func.* => ANY" These properties allow function to return extra stuffs. Usually done to avoid breaking format of existing result (to maintain \s-1API\s0 compatibility). The attributes after \f(CW\*(C`func.\*(C'\fR is up to the respective function. An example is the \&\f(CW\*(C`get_args_from_argv()\*(C'\fR function in the Perinci::Sub::GetArgs::Argv Perl module. The function returns \f(CW$args\fR but from v0.26 it also wants to give hints about whether or not there are missing arguments. It can do this via \&\f(CW\*(C`func.missing_arg\*(C'\fR result metadata. .SS "Properties: cmdline.*" .IX Subsection "Properties: cmdline.*" Interpreted by Perinci::CmdLine. See its documentation for more detail. .SS "Property: logs => \s-1ARRAY OF HASH\s0" .IX Subsection "Property: logs => ARRAY OF HASH" Store log of events happening to this result, stored chronologically (older first). Each log should be a hash which should have at least the following keys: \&\f(CW\*(C`time\*(C'\fR (Unix timestamp), \f(CW\*(C`type\*(C'\fR (string). .PP Normally, the first element of the log will contain information about who produced the result and where/when. It has the \f(CW\*(C`type\*(C'\fR key with the value of \&\f(CW\*(C`create\*(C'\fR. It should be a hash with the following keys: .IP "\(bu" 4 package => \s-1STR\s0 .Sp Package (namespace) where this result is produced. .IP "\(bu" 4 file => \s-1STR\s0 .Sp File name where the result is created. Might be a relative or absolute path. .IP "\(bu" 4 line => \s-1INT\s0 .Sp Line number where the result is created. .IP "\(bu" 4 func => \s-1STR\s0 .Sp Function name where this result is produced. .IP "\(bu" 4 stack_trace => \s-1ARRAY\s0 .Sp Optional, a stack trace. In Perl this can be produced by using << [\fIcaller\fR\|(1), \&\fIcaller\fR\|(2), ...] >>. .SS "Property: prev => \s-1ARRAY\s0" .IX Subsection "Property: prev => ARRAY" Store \*(L"previous result\*(R". Result \s-1MUST\s0 be enveloped. Usually useful when tracing errors, especially in conjunction with \f(CW\*(C`logs\*(C'\fR: when reporting error that results from a call to another function, the original result can be set here, to preserve information. See Perinci::Sub::Util's \f(CW\*(C`err()\*(C'\fR for a convenience function for this, and Perinci::CmdLine's way of displaying it. .PP Example: .PP .Vb 5 \& sub f1 { \& ... \& if (error) { return [500, "Can\*(Aqt f1: blah"] } \& ... \& } \& \& sub f2 { \& ... \& my $res = f1(...); \& if ($res is error) { return [500, "Can\*(Aqt f2", undef, {prev=>$res}] } \& ... \& } \& \& sub f3 { \& ... \& my $res = f1(...); \& if ($res is error) { return [500, "Can\*(Aqt f3", undef, {prev=>$res}] } \& } .Ve .SS "Property: results => array" .IX Subsection "Property: results => array" When a function returns an error response (in particular status 207, but other statuses can also use this), it can put detailed errors here. For example, a function which processed 5 items wanted to report that 2 items were successfully processed but the rest 3 failed: .PP .Vb 9 \& [207, "Multistatus", undef, { \& results => [ \& {status=>200, message=>"OK", item_id=>1}, \& {status=>403, message=>"Forbidden", item_id=>2}, \& {status=>404, message=>"Not found", item_id=>3}, \& {status=>500, message=>"Failed", item_id=>4}, \& {status=>200, message=>"OK", item_id=>5}, \& ], \& }] .Ve .PP Each result is a hash to be able to store \f(CW\*(C`status\*(C'\fR, \f(CW\*(C`message\*(C'\fR, as well as additional data like \f(CW\*(C`item_id\*(C'\fR or whatever the function wants. .PP Another example, a function wants to give information on what arguments fail validation: .PP .Vb 9 \& [400, "Some arguments fail validation", undef, { \& results => [ \& {status=>400, arg=>"name", message=>"Missing"}, \& {status=>400, arg=>"location/street", message=>"Missing"}, \& {status=>400, arg=>"age", message=>"Must be numbers only"}, \& {status=>400, arg=>"password", is_warning=>1, \& message=>"Should be longer than 4 characters"}, # warning only \& ], \& }] .Ve .SH "Property: part_start => int" .IX Header "Property: part_start => int" .SH "Property: len => int" .IX Header "Property: len => int" .SH "Property: part_len => int" .IX Header "Property: part_len => int" The \f(CW\*(C`len\*(C'\fR, \f(CW\*(C`part_start\*(C'\fR and \f(CW\*(C`part_len\*(C'\fR properties specifies the range of data when function sends partial result. Suppose your function is returning a partial content of a large file where total file size is 24500000 bytes and the returned content is from bytes 10000000 to 15000000, then \f(CW\*(C`len\*(C'\fR is 24500000, \f(CW\*(C`part_len\*(C'\fR is 5000000, and \f(CW\*(C`part_start\*(C'\fR is 10000000. When returning partial content, status will be 206. .SH "Property: stream => bool" .IX Header "Property: stream => bool" If set to true, signify that result is an output stream. Usually in implementations the result will be a filehandle or an object with \f(CW\*(C`getline\*(C'\fR or \&\f(CW\*(C`getitem\*(C'\fR methods, where caller can then fetch data from it. .SH "FAQ" .IX Header "FAQ" .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 "SEE ALSO" .IX Header "SEE ALSO" Rinci .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.