Rinci::resmeta(3pm)

📦
version 1.1.104 · 3 versions
, in debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Rinci::resmeta 💖

okay bestie, so this is a page from the User Contributed Perl Documentation section (3pm, obviously), and it's literally all about function/method result metadata. yes, that Rinci::resmeta. buckle up 🎀

✨ NAME ✨

Rinci::resmeta — Function/method result metadata 🦋

🌸 SPECIFICATION VERSION 🌸

1.1

⭐ VERSION ⭐

This document describes version 1.1.104 of Rinci::resmeta (from Perl distribution Rinci), released on 2023-09-30. periodt 💅

👑 INTRODUCTION 👑

So this doc is describing metadata for a function/method result. no cap. And like, this spec is part of Rinci — so if you haven't already done a read up on that, bestie, please go do that first, fr fr. 🙈

🔥 SPECIFICATION 🔥

Currently there are several properties being used. here we go, one by one:

🍓 cmdline.*

Interpreted by Perinci::CmdLine. Peep its documentation for more detail, iykyk.

🍓 content_type

Value: str* (MIME content type)

You can use this to describe the MIME content type of the result. Example enveloped result (in Perl):

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

See also "Properties: func_content_type.*".

Note: borrowed from HTTP. yes, we're out here borrowing, iconic behavior 💅

🍓 func.*

Value: any.

These properties let a function return extra results. Usually done so we don't break the format of an existing result (gotta maintain that API compatibility, bestie 🫶). What goes after func. is totally up to the respective function. An example is the get_args_from_argv() function in the Perinci::Sub::GetArgs::Argv Perl module. That 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 the "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,
    },
}]

🍓 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".

🍓 len

Value: int*

The "len", "part_start" and "part_len" properties specify the range of data when a function sends a partial result. So like, imagine your function is returning a partial content of a large file where the 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. And when returning partial content, status will be 206. slay. ✨

🍓 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. again. we love a reborrow 😭

🍓 logs

Value: array[hash]

Stores a 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

Package (namespace) where this result is produced.

  • file

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

  • line

Line number where the result is created.

  • func

Function name where this result is produced.

  • stack_trace

Optional, a stack trace. In Perl this can be produced by using << [caller(1), caller(2), ...] >>.

🍓 part_len

Value: int*

See "Property: len"

🍓 part_start

Value: int*

See "Property: len".

🍓 perm_err

Value: bool

Indicate that the 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. not me learning networking through error codes 💀

🍓 prev

Value: any

Store "previous result". Result MUST be enveloped. Usually useful when tracing errors, especially in conjunction with "logs": when reporting an 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}] }
}

🍓 results

Value: 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 so it can store "status", "message", as well as additional data like "item_id" or whatever the function wants. main character energy, honestly 👑

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

🍓 schema

Value: sah::schema

Describe result's schema. Has lower precedence than schema from function metadata's result property. (so like, the function metadata one wins, okurrr)

🍓 stream

Value: 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 the caller can then fetch data from it. 🌊

🍓 caption

Value: str*

Optional.

🍓 undo_data

Value: any

(DEPRECATED) Explained in "undo" feature section in Rinci::function. yeah bestie it's deprecated, don't @ me 😭

💀 FAQ 💀

(that's literally it. no questions. no answers. iconic minimalism 🌈)

🌸 HOMEPAGE 🌸

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

🦋 SOURCE 🦋

Source repository is at <https://github.com/perlancar/perl-Rinci>.

⭐ SEE ALSO ⭐

Rinci

👑 AUTHOR 👑

perlancar <perlancar@cpan.org>

🫶 CONTRIBUTING 🫶

To contribute, you can send patches by email/via RT, or send pull requests on GitHub. (pick your fighter 💅)

Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via:

% prove -l

If you want to build the distribution (e.g. to try to install it locally on your system), you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond that are considered a bug and can be reported to me. (yes, a bug. so if you find extra steps, tell him 👀)

This software is copyright (c) 2023, 2022, 2021, 2020, 2019, 2018, 2017, 2016, 2015, 2014, 2013, 2012 by perlancar <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. 🎀

🐛 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. (receipts, bestie — bring receipts 🧾)

and that's the whole page!! 💖 this was documented with perl v5.38.2 and dated 2024-01-20, and yeah, that footer energy is giving official ✨. mwah, go forth and metadate your results 💅🦋🌸

📦 where this page comes from