NAME
Rinci::resmeta - Function/method result metadata
VERSION
This document describes version 1.1.60 of Rinci::resmeta (from Perl distribution Rinci), released on 2014-10-22.
SPECIFICATION VERSION
1.1
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.
SPECIFICATION
There are currently several properties being used:
Property: undo_data => ANY
(DEPRECATED) Explained in undo
feature section in Rinci::function.
Property: perm_err => bool
Indicate that error is permanent (instead of temporary/transient). This is to provide a feature like that found in SMTP/POP protocol, where 4xx codes indicate transient errors and 5xx permanent ones.
Properties: func.* => ANY
These properties allow function to return extra stuffs. Usually done to avoid breaking format of existing result (to maintain API compatibility). The attributes after func.
is up to the respective function. An example is the get_args_from_argv()
function in the Perinci::Sub::GetArgs::Argv Perl module. The function returns $args
but from v0.26 it also wants to give hints about whether or not there are missing arguments. It can do this via func.missing_arg
result metadata.
Properties: cmdline.*
Interpreted by Perinci::CmdLine. See its documentation for more detail.
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: time
(Unix timestamp), type
(string).
Normally, the first element of the log will contain information about who produced the result and where/when. It has the type
key with the value of create
. It should be a hash with the following keys:
package => STR
Package (namespace) where this result is produced.
file => STR
File name where the result is created. Might be a relative or absolute path.
line => INT
Line number where the result is created.
func => STR
Function name where this result is produced.
stack_trace => ARRAY
Optional, a stack trace. In Perl this can be produced by using << [caller(1), caller(2), ...] >>.
Property: prev => ARRAY
Store "previous result". Result MUST be enveloped. Usually useful when tracing errors, especially in conjunction with logs
: 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 err()
for a convenience function for this, and Perinci::CmdLine's way of displaying it.
Example:
sub f1 {
...
if (error) { return [500, "Can't f1: blah"] }
...
}
sub f2 {
...
my $res = f1(...);
if ($res is error) { return [500, "Can't f2", undef, {prev=>$res}] }
...
}
sub f3 {
...
my $res = f1(...);
if ($res is error) { return [500, "Can't f3", undef, {prev=>$res}] }
}
Property: encoding => str
Specify encoding for result. Currently the only recommended value is base64
. This applies to actual result (third element in enveloped result) as well as all values of func.*
properties. Result as well as all func.*
properties must be strings. This can be used for example when enveloped result is represented in a serialization format that is not binary-safe, e.g. JSON:
[200, "OK", "AAAA", {"encoding":"base64", "func.extra":"dWphbmc="}]
In the above example, actual result is 3 zero bytes ("\0\0\0") encoded in base64, while func.extra
contains the string "ujang".
Property: arg_errors => hash
When a function wants to give information on what arguments fail validation, it can put the information here. This is usually only present when response status is 400 (bad arguments). Keys are argument names (or paths: separate submetadata argument with slash /
) while values are string error messages. Example:
# full error response
[400, "Some arguments fail validation", undef, {
arg_errors => {
name=>"Missing",
"location/street"=>"Missing",
age=>"Must be numbers only",
},
}]
Property: arg_warnings => hash
Like arg_errors
but warnings only. Can be present even when response status is non-error (200).
FAQ
SEE ALSO
HOMEPAGE
Please visit the project's homepage at https://metacpan.org/release/Rinci.
SOURCE
Source repository is at https://github.com/perlancar/perl-Rinci.
BUGS
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Rinci
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.
AUTHOR
perlancar <perlancar@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2014 by perlancar@cpan.org.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.