Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Rinci::resmeta(3)     User Contributed Perl Documentation    Rinci::resmeta(3)

NAME
       Rinci::resmeta -	Function/method	result metadata

VERSION
       This document describes version 1.1.84 of Rinci::resmeta	(from Perl
       distribution Rinci), released on	2016-12-28.

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, "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}] }
	}

   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.

perl v5.24.1			  2016-12-28		     Rinci::resmeta(3)

NAME | VERSION | SPECIFICATION VERSION | INTRODUCTION | SPECIFICATION | Property: part_start => int | Property: len => int | Property: part_len => int | Property: stream => bool | FAQ | HOMEPAGE | SOURCE | BUGS | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Rinci::resmeta&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help