package Rinci::resmeta; # just to make PodWeaver happy
# DATE
# VERSION
1;
# ABSTRACT: Function/method result metadata
__END__
=pod
=encoding UTF-8
=head1 NAME
Rinci::resmeta - Function/method result metadata
=head1 VERSION
This document describes version 1.1.84 of Rinci::resmeta (from Perl distribution Rinci), released on 2016-12-28.
=head1 SPECIFICATION VERSION
1.1
=head1 INTRODUCTION
This document describes metadata for function/method result. This specification
is part of L<Rinci>. Please do a read up on it first, if you have not already
done so.
=head1 SPECIFICATION
There are currently several properties being used:
=head2 Property: undo_data => ANY
(DEPRECATED) Explained in C<undo> feature section in L<Rinci::function>.
=head2 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.
=head2 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 C<func.> is up to the respective function. An example is the
C<get_args_from_argv()> function in the L<Perinci::Sub::GetArgs::Argv> Perl
module. The function returns C<$args> but from v0.26 it also wants to give hints
about whether or not there are missing arguments. It can do this via
C<func.missing_arg> result metadata.
=head2 Properties: cmdline.*
Interpreted by L<Perinci::CmdLine>. See its documentation for more detail.
=head2 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:
C<time> (Unix timestamp), C<type> (string).
Normally, the first element of the log will contain information about who
produced the result and where/when. It has the C<type> key with the value of
C<create>. It should be a hash with the following keys:
=over
=item * package => STR
Package (namespace) where this result is produced.
=item * file => STR
File name where the result is created. Might be a relative or absolute path.
=item * line => INT
Line number where the result is created.
=item * func => STR
Function name where this result is produced.
=item * stack_trace => ARRAY
Optional, a stack trace. In Perl this can be produced by using << [caller(1),
caller(2), ...] >>.
=back
=head2 Property: prev => ARRAY
Store "previous result". Result MUST be enveloped. Usually useful when tracing
errors, especially in conjunction with C<logs>: when reporting error that
results from a call to another function, the original result can be set here, to
preserve information. See L<Perinci::Sub::Util>'s C<err()> for a convenience
function for this, and L<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}] }
}
=head2 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:
[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},
],
}]
Each result is a hash to be able to store C<status>, C<message>, as well as
additional data like C<item_id> or whatever the function wants.
Another example, a function wants to give information on what arguments fail
validation:
[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
],
}]
=head1 Property: part_start => int
=head1 Property: len => int
=head1 Property: part_len => int
The C<len>, C<part_start> and C<part_len> 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 C<len> is 24500000, C<part_len>
is 5000000, and C<part_start> is 10000000. When returning partial content,
status will be 206.
=head1 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 C<getline> or
C<getitem> methods, where caller can then fetch data from it.
=head1 FAQ
=head1 HOMEPAGE
Please visit the project's homepage at L<https://metacpan.org/release/Rinci>.
=head1 SOURCE
Source repository is at L<https://github.com/perlancar/perl-Rinci>.
=head1 BUGS
Please report any bugs or feature requests on the bugtracker website L<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.
=head1 SEE ALSO
L<Rinci>
=head1 AUTHOR
perlancar <perlancar@cpan.org>
=head1 COPYRIGHT AND LICENSE
This software is copyright (c) 2016 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.
=cut