NAME
    Perinci::Sub::Property::result::object - Specify object data in result

VERSION
    This document describes version 0.03 of
    Perinci::Sub::Property::result::object (from Perl distribution
    Perinci-Sub-Property-result-object), released on 2015-01-07.

SYNOPSIS
    In function Rinci metadata:

     result => {
         object => {
             spec => {
                 summary => "Account information",
                 fields  => {
                     id => {
                         summary => "Account ID",
                         schema  => ['int*', {min=>1000}],
                         req     => 1,
                     },
                     name => {
                         summary => "Account name",
                         schema  => 'str*',
                         req     => 1,
                     },
                     account => {
                         summary => "Alias for name, for backward-compat",
                         schema  => "str*",
                     },
                     plan => {
                         summary => "Account's plan name",
                         schema  => 'str*',
                     },
                     is_disabled => {
                         summary => "Whether the account is disabled",
                         schema  => 'bool*',
                     },
                     disk_usage => {
                         summary => "Current disk usage, in MB",
                         schema  => 'float',
                     },
                     bw_usage => {
                         summary => "Current month's data transfer, in GB",
                         schema  => 'float',
                     },
                 },
             },
             # allow_extra_fields => 0,
             # allow_underscore_fields => 0,
         },
         ...
     }

DESCRIPTION
    This property is similar to Perinci::Sub::Property::result::table except
    that it describes a single row (or object a la JavaScript object, or a
    hash):

     {
         id          => 1001,
         name        => "steven",
         account     => "steven",
         plan        => "BIZ A",
         is_disabled => 0,
         disk_usage  => 3788,
         bw_usage    => 120,
     }

    This module offers several things:

    *   (NOT YET IMPLEMENTED) When you generate documentation, the object
        specification is also included in the documentation.

        (NOT YET IMPLEMENTED, IDEA) The user can also perhaps request the
        object specification, e.g. "yourfunc --help=result-object-spec",
        "yourfunc --result-object-spec".

    *   (NOT YET IMPLEMENTED) The wrapper code can optionally validate your
        function result, making sure that your resulting object/hash
        conforms to the specification.

SPECIFICATION
    The value of the "object" property should be a DefHash. Known
    properties:

    *   spec => DEFHASH

        Required. Object data specification, currently follows TableDef
        except that the <pos> property is not used.

    *   allow_extra_fields => BOOL (default: 0)

        Whether to allow the function to return extra fields other than the
        ones specified in "spec".

    *   allow_underscore_fields => BOOL (default: 0)

        Like "allow_extra_fields", but regulates whether to allow any extra
        fields prefixed by an underscore. Underscore-prefixed keys

FAQ
  Why not use the "schema" property in the "result" property?
    That is, in your function metadata:

     result => {
         schema => ['hash*', keys => {
             id          => 'int*',
             name        => 'str*',
             account     => 'str*',
             plan        => 'str*',
             id_disabled => 'bool*',
             disk_usage  => 'float',
             bw_usage    => 'float',
         },
         req_keys => [qw/id name plan/]],
     },

    Actually you can. But with the "object" result property, the intent
    becomes clearer that we want to return object/hash. And this module
    provides the hooks for generating documentation.

HOMEPAGE
    Please visit the project's homepage at
    <https://metacpan.org/release/Perinci-Sub-Property-result-object>.

SOURCE
    Source repository is at
    <https://github.com/perlancar/perl-Perinci-Sub-Property-result-object>.

BUGS
    Please report any bugs or feature requests on the bugtracker website
    <https://rt.cpan.org/Public/Dist/Display.html?Name=Perinci-Sub-Property-
    result-object>

    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.

AUTHOR
    perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2015 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.

