NAME
    Perinci::Examples - Various examples of Rinci metadata

VERSION
    This document describes version 0.824 of Perinci::Examples (from Perl
    distribution Perinci-Examples), released on 2023-07-09.

DESCRIPTION
    This distribution contains an odd mix of various functions, variables,
    and other code entities, along with their Rinci metadata. Mostly used
    for testing Rinci specification and the various Perinci modules.

    Example scripts are put in a separate distribution (see
    Perinci::Examples::Bin) to make dependencies for this distribution
    minimal (e.g. not depending on Perinci::CmdLine::Any) since this example
    module(s) are usually used in the tests of other modules.

    A sample description

     verbatim
     line2

    Another paragraph with *bold*, *italic* text.

FUNCTIONS
  arg_default
    Usage:

     arg_default(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Demonstrate argument default value from default and/or schema.

    Default value can be specified in the "default" property of argument
    specification, e.g.:

     args => {
         arg1 => { schema=>'str', default=>'blah' },
     },

    or in the "default" clause of the argument's schema, e.g.:

     args => {
         arg1 => { schema=>['str', default=>'blah'] },
     },

    or even both. The "default" property in argument specification takes
    precedence.

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   a => *int*

        No defaults.

    *   b => *int* (default: 2)

        Default from "default" property.

    *   c => *int* (default: 3)

        Default from schema.

    *   d => *int* (default: 4)

        Default from "default" property as well as schema.

        "Default" property overrides default value from schema.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  args_as_array
    Usage:

     args_as_array($a0, $a1, $a2) -> [$status_code, $reason, $payload, \%result_meta]

    This function's metadata sets "args_as" property to "array". This means
    it wants to accept argument as an array, like a regular Perl subroutine
    accepting positional arguments in @_.

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   $a0 => *str*

        (No description)

    *   $a1 => *str*

        (No description)

    *   $a2 => *str*

        (No description)

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  args_as_arrayref
    Usage:

     args_as_arrayref([$a0, $a1, $a2]) -> [$status_code, $reason, $payload, \%result_meta]

    This function's metadata sets "args_as" property to "arrayref". This is
    just like "array", except the whole argument list is passed in $_[0].

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   $a0 => *str*

        (No description)

    *   $a1 => *str*

        (No description)

    *   $a2 => *str*

        (No description)

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  args_as_hashref
    Usage:

     args_as_hashref(\%args) -> [$status_code, $reason, $payload, \%result_meta]

    This function's metadata sets "args_as" property to "hashref". This is
    just like "hash", except the whole argument hash is passed in $_[0].

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   a0 => *str*

        (No description)

    *   a1 => *str*

        (No description)

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  binary
    Usage:

     binary(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Accept and send binary data.

    This function sets its argument's schema type as "buf" which indicates
    the argument accepts binary data. Likewise it also sets its result's
    schema type as "buf" which says that function will return binary data.

    The function just returns its argument.

    Note that since the metadata also contains null ("\0") in the "default"
    property of the argument specification, the metadata is also not
    JSON-safe.

    To pass binary data over JSON/Riap, you can use Riap version 1.2 and
    encode the argument with ":base64" suffix, e.g.:

     $res = Perinci::Access->new->request(
         call => "http://example.com/api/Perinci/Examples/binary",
         {v=>1.2, args=>{"data:base64"=>"/wA="}}); # send "\xff\0"

    Without "v=>1.2", encoded argument won't be decoded by the server.

    To pass binary data on the command-line, you can use "--ARG-base64" if
    the command-line library provides it.

    To receive binary result over JSON/Riap, you can use Riap version 1.2
    which will automatically encode binary data with base64 so it is safe
    when transformed as JSON. The client library will also decode the
    encoded result back to the original, so the whole process is transparent
    to you:

     $res = Perinci::Access->new->request(
         call => "http://example.com/api/Perinci/Examples/binary",
         {v=>1.2}); # => [200,"OK","\0\0\0",{}]

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   data => *buf* (default: "\0\0\0")

        (No description)

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (buf)

  call_gen_array
    Usage:

     call_gen_array(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Call gen_array().

    This is to test nested call (e.g. Log::Any::For::Package).

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   len* => *int* (default: 10)

        Array length.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (array[int])

  call_randlog
    Usage:

     call_randlog(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Call randlog().

    This is to test nested call (e.g. Log::Any::For::Package).

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   max_level => *int* (default: 6)

        Maximum level.

    *   min_level => *int* (default: 1)

        Minimum level.

    *   n => *int* (default: 10)

        Number of log messages to produce.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  comment_fruit
    Usage:

     comment_fruit(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Comment on a fruit.

    This function demonstrate argument's "examples" property. It can be used
    to show choices (e.g. in argument completion) but does not require that
    value be one of the examples only.

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   fruit* => *str*

        (No description)

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  common_opts
    Usage:

     common_opts(%args) -> [$status_code, $reason, $payload, \%result_meta]

    This function has arguments with the same name as Perinci::CmdLine
    common options.

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   action => *str*

        (No description)

    *   cmd => *str*

        (No description)

    *   debug => *bool*

        (No description)

    *   format => *str*

        (No description)

    *   format_options => *str*

        (No description)

    *   help => *bool*

        (No description)

    *   json => *bool*

        (No description)

    *   log_level => *str*

        (No description)

    *   perl => *bool*

        (No description)

    *   quiet => *bool*

        (No description)

    *   subcommands => *str*

        (No description)

    *   trace => *bool*

        (No description)

    *   verbose => *bool*

        (No description)

    *   version => *str*

        (No description)

    *   yaml => *bool*

        (No description)

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  completion
    Usage:

     completion(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Do nothing, return args.

    This function is used to test argument completion.

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   a1 => *array[str]*

        Array of strings, where the string has "in" schema clause.

        Completion library can perhaps complete from the "in" value and
        remember completed items when command-line option is repeated, e.g.
        in:

         --a1 <tab>

        it will complete from any "in" value, but in:

         --a1 apple --a1 <tab>

        it can exclude "apple" from the completion candidate.

        Currently the completion library Perinci::Sub::Complete does not do
        this though. Perhaps there can be an option to toggle this behavior.

    *   a2 => *array[str]*

        Array with element_completion routine that generate random letter.

    *   a3 => *array[str]*

        Array with element_completion routine that dies.

        See also "s3".

    *   arg0 => *any*

        Argument without any schema.

    *   f0 => *float*

        Float with just "float" schema defined.

    *   f1 => *float*

        Float with xmin/xmax on the schema.

        A completion library can attempt to provide some possible and
        incremental completion (e.g. if word is currently at one decimal
        digit like 1.2, it can provide completion of 1.20 .. 1.29).

    *   h1 => *hash*

        Hash with "keys" and "allowed_keys" schema clauses and
        "element_completion" property.

    *   h2 => *hash*

        Hash with "element_completion" as well as "index_completion"
        properties.

    *   i0 => *int*

        Integer with just "int" schema defined.

    *   i1 => *int*

        Integer with min/xmax on the schema.

        A completion library (like Perinci::Sub::Complete) can generate a
        list of completion from the low end to the high end of the range, as
        long as it is not too long.

    *   i2 => *int*

        Integer with large range min/max on the schema.

        Unlike in "i1", a completion library probably won't generate a
        number sequence for this argument because they are considered too
        long (1000+ items).

    *   s1 => *str*

        String with possible values in "in" schema clause.

    *   s1b => *str*

        String with possible values in "in" schema clause, contains special
        characters.

        This argument is intended to test how special characters are
        escaped.

    *   s1c => *str*

        String with examples in schema.

    *   s1d => *str*

        String with examples in argument spec.

    *   s2 => *str*

        String with completion routine that generate random letter.

    *   s3 => *str*

        String with completion routine that dies.

        Completion should not display error (except perhaps under
        debugging). It should just provide no completion.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  delay
    Usage:

     delay(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Sleep, by default for 10 seconds.

    Can be used to test the *time_limit* property.

    This function is not exported by default, but exportable.

    Arguments ('*' denotes required arguments):

    *   n => *int* (default: 10)

        Number of seconds to sleep.

    *   per_second => *bool* (default: 0)

        Whether to sleep(1) for n times instead of sleep(n).

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  dies
    Usage:

     dies() -> [$status_code, $reason, $payload, \%result_meta]

    Dies tragically.

    Can be used to test exception handling.

    This function is not exported by default, but exportable.

    No arguments.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  dry_run
    Usage:

     dry_run() -> [$status_code, $reason, $payload, \%result_meta]

    Will return 'wet' if not run under dry run mode, or 'dry' if dry run.

    The way you detect whether we are running under dry-run mode is to check
    the special argument $args{-dry_run}.

    This function is not exported.

    This function supports dry-run operation.

    No arguments.

    Special arguments:

    *   -dry_run => *bool*

        Pass -dry_run=>1 to enable simulation mode.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  dry_run_default
    Usage:

     dry_run_default() -> [$status_code, $reason, $payload, \%result_meta]

    Will return 'wet' if not run under dry run mode, or 'dry' if dry run.

    This function is like "dry_run", except the default mode is dry-run.

    The way you detect whether we are running under dry-run mode is to check
    the special argument $args{-dry_run}.

    This function is not exported.

    This function supports dry-run operation.

    No arguments.

    Special arguments:

    *   -dry_run => *bool*

        Pass -dry_run=>1 to enable simulation mode.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  err
    Usage:

     err(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Return error response.

    This function is not exported by default, but exportable.

    Arguments ('*' denotes required arguments):

    *   code => *int* (default: 500)

        Error code to return.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  gen_array
    Usage:

     gen_array(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Generate an array of specified length.

    Also tests result schema.

    This function is not exported by default, but exportable.

    Arguments ('*' denotes required arguments):

    *   len* => *int* (default: 10)

        Array length.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (array[int])

  gen_hash
    Usage:

     gen_hash(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Generate a hash with specified number of pairs.

    Also tests result schema.

    This function is not exported by default, but exportable.

    Arguments ('*' denotes required arguments):

    *   pairs => *int* (default: 10)

        Number of pairs.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (array[int])

  gen_random_bytes
    Usage:

     gen_random_bytes(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Generate random bytes of specified length.

    This function can also be used to test binary data and Riap 1.2.

    By default it will generate 1K worth of random garbage.

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   len => *int* (default: 1024)

        (No description)

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (buf)

  gen_sample_data
    Usage:

     gen_sample_data(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Generate sample data of various form.

    This function is first written to test Perinci::CmdLine::Lite's text
    formatting rules.

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   form* => *str*

        *   aos is array of scalar, e.g. "[1,2,3]".

        *   aoaos is array of aos, e.g. "[ [1,2,3], [4,5,6] ]".

        *   hos is hash of scalar (values), e.g. "{a=>1, b=>2}".

        *   aohos is array of array of hos, e.g. "[{a=>1,b=>2}, {a=>2}]".

        *   hohos is hash of hos as values, e.g. "{row1=>{a=>1,b=>2},
            row2=>{}}".

        The "aoaos" and "aohos" forms are commonly used for table data.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  merge_hash
    Usage:

     merge_hash(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Merge two hashes.

    This function can be used to test passing nonscalar (hash) arguments.

    This function also tests the
    "x.perinci.sub.wrapper.disable_validate_args" attribute so that
    Perinci::Sub::Wrapper does not generate argument validation code in the
    wrapper. Note that by adding "# VALIDATE_ARG" in the source code, the
    Dist::Zilla::Plugin::Rinci::Wrap plugin already generates and embeds
    argument validation code in the source code, so duplication is not
    desired, thus the attribute.

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   h1* => *hash*

        First hash (left-hand side).

    *   h2* => *hash*

        First hash (right-hand side).

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (hash)

  multi_status
    Usage:

     multi_status(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Example for result metadata property `results`.

    This function might return 200, 207, or 500, randomly. It will set
    result metadata property "results" to contain per-item results. For more
    details, see the corresponding specification in "results" property in
    Rinci::resmeta.

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   n => *any* (default: 5)

        (No description)

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  noop
    Usage:

     noop(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Do nothing, return original argument.

    Will also return argument passed to it.

    This function is also marked as "pure", meaning it will not cause any
    side effects. Pure functions are safe to call directly in a transaction
    (without going through the transaction manager) or during dry-run mode.

    This function is not exported by default, but exportable.

    This function is pure (produce no side effects).

    Arguments ('*' denotes required arguments):

    *   arg => *any*

        Argument.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  noop2
    Usage:

     noop2(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Just like noop, but accepts several arguments.

    Will return arguments passed to it.

    This function is also marked as "pure", meaning it will not cause any
    side effects. Pure functions are safe to call directly in a transaction
    (without going through the transaction manager) or during dry-run mode.

    This function is not exported.

    This function is pure (produce no side effects).

    Arguments ('*' denotes required arguments):

    *   a => *any*

        Argument.

    *   b => *any*

        Argument.

    *   c => *any*

        Argument.

    *   d => *any*

        Argument.

    *   e => *any*

        Argument.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  randlog
    Usage:

     randlog(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Produce some random Log::Any log messages.

    This function is not exported by default, but exportable.

    Arguments ('*' denotes required arguments):

    *   max_level => *int* (default: 6)

        Maximum level.

    *   min_level => *int* (default: 1)

        Minimum level.

    *   n => *int* (default: 10)

        Number of log messages to produce.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  result_naked
    Usage:

     result_naked(%args) -> any

    This function's metadata sets "result_naked" to true. This means
    function returns just the value (e.g. 42) and not with envelope (e.g.
    "[200,"OK",42]"). However, when served over network Riap protocol, the
    function wrapper Perinci::Sub::Wrapper can generate an envelope for the
    result, so the wrapped function wil still return "[200,"OK",42]".

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   a0 => *str*

        (No description)

    *   a1 => *str*

        (No description)

    Return value: (any)

  return_args
    Usage:

     return_args(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Return arguments.

    Can be useful to check what arguments the function gets. Aside from
    normal arguments, sometimes function will receive special arguments
    (those prefixed with dash, "-").

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   arg => *any*

        Argument.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  sum
    Usage:

     sum(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Sum numbers in array.

    Examples:

    *   First example:

         sum(array => [1, 2, 3]); # -> [200, "OK", 6, {}]

    *   Second example, using argv:

         sum(array => [1.1, 2.1, 3.1], round => 1); # -> [200, "OK", 6, {}]

    *   Third example, invalid arguments:

         sum(array => ["a"]);

        Result:

         [
           400,
           "Argument 'array' fails validation: \@[0]: Not of type decimal number",
           undef,
           {},
         ]

    This function can be used to test passing nonscalar (array) arguments.

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   array* => *array[float]*

        Array.

    *   round => *bool* (default: 0)

        Whether to round result to integer.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  undescribed_args
    Usage:

     undescribed_args(%args) -> [$status_code, $reason, $payload, \%result_meta]

    This function has several undescribed args.

    Originally added to see how peri-func-usage or Perinci::To::Text will
    display the usage or documentation for this function.

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   arg1 => *any*

        (No description)

    *   arg2 => *any*

        (No description)

    *   arg3 => *any*

        (No description)

    *   arg4 => *any*

        (No description)

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  validate_args
    Usage:

     validate_args(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Does nothing, only here to test # VALIDATE_ARGS.

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   a => *int*

        (No description)

    *   b => *str*

        (No description)

    *   h1 => *hash*

        (No description)

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (str)

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

SOURCE
    Source repository is at
    <https://github.com/perlancar/perl-Perinci-Examples>.

SEE ALSO
    Perinci

    Perinci::Examples::Bin

AUTHOR
    perlancar <perlancar@cpan.org>

CONTRIBUTOR
    Steven Haryanto <stevenharyanto@gmail.com>

CONTRIBUTING
    To contribute, you can send patches by email/via RT, or send pull
    requests on GitHub.

    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.

COPYRIGHT AND LICENSE
    This software is copyright (c) 2023, 2022, 2020, 2019, 2018, 2017, 2016,
    2015, 2014, 2013, 2012, 2011 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=Perinci-Examples>

    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.