GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  RINCI::RESMETA (3)

.ds Aq ’

NAME

Rinci::resmeta - Function/method result metadata

CONTENTS

VERSION

This document describes version 1.1.79 of Rinci::resmeta (from Perl distribution Rinci), released on 2016-02-25.

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.

    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.

    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:
o package => STR

Package (namespace) where this result is produced.

o file => STR

File name where the result is created. Might be a relative or absolute path.

o line => INT

Line number where the result is created.

o func => STR

Function name where this result is produced.

o 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, "Cant f1: blah"] }
     ...
 }

 sub f2 {
     ...
     my $res = f1(...);
     if ($res is error) { return [500, "Cant f2", undef, {prev=>$res}] }
     ...
 }

 sub f3 {
     ...
     my $res = f1(...);
     if ($res is error) { return [500, "Cant f3", undef, {prev=>$res}] }
 }



    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 status, message, as well as additional data like 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
      ],
 }]



Property: part_start => int

Property: len => int

Property: part_len => int

The len, part_start and 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 len is 24500000, part_len is 5000000, and part_start is 10000000. When returning partial content, status will be 206.

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 getline or getitem methods, where caller can then fetch data from it.

FAQ

HOMEPAGE

Please visit the project’s homepage at <https://metacpan.org/release/Rinci>.

SOURCE

Source repository is at <https://github.com/perlancar/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.

SEE ALSO

Rinci

AUTHOR

perlancar <perlancar@cpan.org>

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.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 RINCI::RESMETA (3) 2016-02-25

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.