/usr/share/perl5/Rinci/resmeta.pod is in librinci-perl 1.1.84-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 | 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
|