NAME

Rinci::result - Function/method result metadata

VERSION

version 1.1.39

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: 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

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.