NAME

       Rinci::result - Function/method result metadata

VERSION

       version 1.1.43

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) 2013 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.

perl v5.18.1                                       2013-12-25                                 Rinci::result(3pm)