NAME¶
Rinci::result - Function/method result metadata
VERSION¶
This document describes version 1.1.52 of Rinci::result (from Perl distribution
Rinci), released on 2014-06-29.
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.
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}] }
}
FAQ¶
SEE ALSO¶
Rinci
HOMEPAGE¶
Please visit the project's homepage at
<
https://metacpan.org/release/Rinci>.
SOURCE¶
Source repository is at <
https://github.com/sharyanto/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¶
Steven Haryanto <stevenharyanto@gmail.com>
COPYRIGHT AND LICENSE¶
This software is copyright (c) 2014 by Steven Haryanto.
This is free software; you can redistribute it and/or modify it under the same
terms as the Perl 5 programming language system itself.