Properties: cmdline.*¶

Interpreted by Perinci::CmdLine. See its documentation for more detail.

Properties: content_type¶

Value: str* (MIME content type)

Can be used to describe the MIME content type of result. Example enveloped result (in Perl):

 [200, "OK", "...", {content_type => "image/jpeg"}]

See also "Properties: func_content_type.*".

Note: borrowed from HTTP.

Properties: func.* => ANY¶

These properties allow function to return extra results. 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. Some other examples (in Perl):

 # result from check_user()
 [200, "OK", 1,         # 1 means valie
 {
     "func.detail" => { # detailed check result
         last_login      => '2021-01-21T01:55:40Z',
         password_secure => 1,
         quota_exceeded  => 0,
     },
 }]

Properties: func_content_type.*¶

Value: str* (MIME content type)

Can be used to describe the MIME content type of each extra result. Example (in Perl):

 func.attachment => '...',
 func_content_type.attachment => 'image/jpeg',

See also "Property: content_type".

Properties: location¶

Value: str* (URL)

Can be used to specify that the content is elsewhere. Used in combination with 301 or 302 result status. Example (in Perl):

 # result from a function that generates a chart
 [301, "Moved", undef, {content_type => "image/jpeg", location=>"file:/tmp/asd9uxzw.png"}]

Note: borrowed from HTTP.

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

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: schema => SCHEMA¶

Describe result's schema. Has lower precedence than schema from function metadata's result property.

Property: undo_data => ANY¶

(DEPRECATED) Explained in "undo" feature section in Rinci::function.