/ 
Perinci-Object-0.311
River stage three • 44 direct dependents • 871 total dependents
/ Perinci::Object::EnvResultMulti

NAME

Perinci::Object::EnvResultMulti - Represent enveloped result (multistatus)

VERSION

This document describes version 0.311 of Perinci::Object::EnvResultMulti (from Perl distribution Perinci-Object), released on 2020-01-02.

SYNOPSIS

use Perinci::Object::EnvResultMulti;
use Data::Dump; # for dd()

sub myfunc {
    ...

    # if unspecified, the default status will be [200, "Success/no items"]
    my $envres = Perinci::Object::EnvResultMulti->new;

    # then you can add result for each item
    $envres->add_result(200, "OK", {item_id=>1});
    $envres->add_result(202, "OK", {item_id=>2, note=>"blah"});
    $envres->add_result(404, "Not found", {item_id=>3});
    ...

    # if you add a success status, the overall status will still be 200

    # if you add a non-success staus, the overall status will be 207, or
    # the non-success status (if no success has been added)

    # finally, return the result
    return $envres->as_struct;

    # the result from the above will be: [207, "Partial success", undef,
    # {results => [
    #     {success=>200, message=>"OK", item_id=>1},
    #     {success=>201, message=>"OK", item_id=>2, note=>"blah"},
    #     {success=>404, message=>"Not found", item_id=>3},
    # ]}]
} # myfunc

To add a payload for each result:

my $envres = Perinci::Object::EnvResultMulti->new;
$envres->add_result(200, "OK", {item_id=>1, payload=>"a"});
$envres->add_result(200, "OK", {item_id=>2, payload=>"b"});
$envres->add_result(200, "OK", {item_id=>3, payload=>"c"});

return $envres->as_struct;
# => [200, "All success", ["a","b","c"], ...]

DESCRIPTION

This class is a subclass of Perinci::Object::EnvResult and provides a convenience method when you want to use multistatus/detailed per-item results (specified in Rinci 1.1.63: results result metadata property). In this case, response status can be 200, 207, or non-success. As you add more per-item results, this class will set/update the overall response status for you.

METHODS

new($res) => OBJECT

Create a new object from $res enveloped result array. If $res is not specified, the default is [200, "Success/no items"].

$envres->add_result($status, $message, \%extra)

Add an item result.

Extra keys:

  • item_id

  • payload

    If you want to add a payload for this result. The final overall payload will be an array composed from this payload.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Perinci-Object.

SOURCE

Source repository is at https://github.com/perlancar/perl-Perinci-Object.

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/perlancar/perl-Perinci-Object/issues

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

Perinci::Object

Perinci::Object::EnvResult

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2021, 2017, 2016, 2015, 2014, 2013, 2012, 2011 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.