NAME
    Perinci::Examples - Example modules containing metadata and various
    example functions

VERSION
    version 0.15

SYNOPSIS
     use Perinci::Examples qw(delay);
     delay();

DESCRIPTION
    This module and its submodules contain 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) 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.

SEE ALSO
    Perinci

    Perinci::Examples::Bin

AUTHOR
    Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2013 by Steven Haryanto.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.

FUNCTIONS
    None are exported by default, but they are exportable.

  call_gen_array(%args) -> [status, msg, result, meta]
    Call gen_array().

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

    Arguments ('*' denotes required arguments):

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

        Array length.

    Return value:

    Returns an enveloped result (an array). First element (status) is an
    integer containing HTTP status code (200 means OK, 4xx caller error, 5xx
    function error). Second element (msg) is a string containing error
    message, or 'OK' if status is 200. Third element (result) is optional,
    the actual result. Fourth element (meta) is called result metadata and
    is optional, a hash that contains extra information.

  call_randlog(%args) -> [status, msg, result, meta]
    Call randlog().

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

    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.

    Return value:

    Returns an enveloped result (an array). First element (status) is an
    integer containing HTTP status code (200 means OK, 4xx caller error, 5xx
    function error). Second element (msg) is a string containing error
    message, or 'OK' if status is 200. Third element (result) is optional,
    the actual result. Fourth element (meta) is called result metadata and
    is optional, a hash that contains extra information.

  delay(%args) -> [status, msg, result, meta]
    Sleep, by default for 10 seconds.

    Can be used to test the *time_limit* property.

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

    Return value:

    Returns an enveloped result (an array). First element (status) is an
    integer containing HTTP status code (200 means OK, 4xx caller error, 5xx
    function error). Second element (msg) is a string containing error
    message, or 'OK' if status is 200. Third element (result) is optional,
    the actual result. Fourth element (meta) is called result metadata and
    is optional, a hash that contains extra information.

  dies() -> [status, msg, result, meta]
    Dies tragically.

    Can be used to test exception handling.

    No arguments.

    Return value:

    Returns an enveloped result (an array). First element (status) is an
    integer containing HTTP status code (200 means OK, 4xx caller error, 5xx
    function error). Second element (msg) is a string containing error
    message, or 'OK' if status is 200. Third element (result) is optional,
    the actual result. Fourth element (meta) is called result metadata and
    is optional, a hash that contains extra information.

  err(%args) -> [status, msg, result, meta]
    Return error response.

    Arguments ('*' denotes required arguments):

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

        Error code to return.

    Return value:

    Returns an enveloped result (an array). First element (status) is an
    integer containing HTTP status code (200 means OK, 4xx caller error, 5xx
    function error). Second element (msg) is a string containing error
    message, or 'OK' if status is 200. Third element (result) is optional,
    the actual result. Fourth element (meta) is called result metadata and
    is optional, a hash that contains extra information.

  gen_array(%args) -> [status, msg, result, meta]
    Generate an array of specified length.

    Also tests result schema.

    Arguments ('*' denotes required arguments):

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

        Array length.

    Return value:

    Returns an enveloped result (an array). First element (status) is an
    integer containing HTTP status code (200 means OK, 4xx caller error, 5xx
    function error). Second element (msg) is a string containing error
    message, or 'OK' if status is 200. Third element (result) is optional,
    the actual result. Fourth element (meta) is called result metadata and
    is optional, a hash that contains extra information.

  gen_hash(%args) -> [status, msg, result, meta]
    Generate a hash with specified number of pairs.

    Also tests result schema.

    Arguments ('*' denotes required arguments):

    *   pairs => *int*

        Number of pairs.

    Return value:

    Returns an enveloped result (an array). First element (status) is an
    integer containing HTTP status code (200 means OK, 4xx caller error, 5xx
    function error). Second element (msg) is a string containing error
    message, or 'OK' if status is 200. Third element (result) is optional,
    the actual result. Fourth element (meta) is called result metadata and
    is optional, a hash that contains extra information.

  merge_hash(%args) -> [status, msg, result, meta]
    Merge two hashes.

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

    Arguments ('*' denotes required arguments):

    *   h1* => *hash*

        First hash (left-hand side).

    *   h2* => *hash*

        First hash (right-hand side).

    Return value:

    Returns an enveloped result (an array). First element (status) is an
    integer containing HTTP status code (200 means OK, 4xx caller error, 5xx
    function error). Second element (msg) is a string containing error
    message, or 'OK' if status is 200. Third element (result) is optional,
    the actual result. Fourth element (meta) is called result metadata and
    is optional, a hash that contains extra information.

  noop(%args) -> [status, msg, result, meta]
    Do nothing, return original argument.

    This function is pure (produce no side effects).

    Arguments ('*' denotes required arguments):

    *   arg => *any*

        Argument.

    Return value:

    Returns an enveloped result (an array). First element (status) is an
    integer containing HTTP status code (200 means OK, 4xx caller error, 5xx
    function error). Second element (msg) is a string containing error
    message, or 'OK' if status is 200. Third element (result) is optional,
    the actual result. Fourth element (meta) is called result metadata and
    is optional, a hash that contains extra information.

  randlog(%args) -> [status, msg, result, meta]
    Produce some random Log::Any log messages.

    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.

    Return value:

    Returns an enveloped result (an array). First element (status) is an
    integer containing HTTP status code (200 means OK, 4xx caller error, 5xx
    function error). Second element (msg) is a string containing error
    message, or 'OK' if status is 200. Third element (result) is optional,
    the actual result. Fourth element (meta) is called result metadata and
    is optional, a hash that contains extra information.

  sum(%args) -> [status, msg, result, meta]
    Sum numbers in array.

    Examples:

     sum(array => [1, 2, 3]); # -> 6

     sum(array => [1.1, 2.1, 3.1], round => 1); # -> 6

     sum(array => ["a"]); # ERROR 400

     sum();

     sum();

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

    Arguments ('*' denotes required arguments):

    *   array* => *array*

        Array.

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

        Whether to round result to integer.

    Return value:

    Returns an enveloped result (an array). First element (status) is an
    integer containing HTTP status code (200 means OK, 4xx caller error, 5xx
    function error). Second element (msg) is a string containing error
    message, or 'OK' if status is 200. Third element (result) is optional,
    the actual result. Fourth element (meta) is called result metadata and
    is optional, a hash that contains extra information.

  test_completion(%args) -> [status, msg, result, meta]
    Do nothing, return nothing.

    This function is used to test argument completion.

    This function is pure (produce no side effects).

    Arguments ('*' denotes required arguments):

    *   f1 => *float*

    *   i1 => *int*

    *   i2 => *int*

    *   s1 => *str*

    *   s2 => *str*

    *   s3 => *str*

    Return value:

    Returns an enveloped result (an array). First element (status) is an
    integer containing HTTP status code (200 means OK, 4xx caller error, 5xx
    function error). Second element (msg) is a string containing error
    message, or 'OK' if status is 200. Third element (result) is optional,
    the actual result. Fourth element (meta) is called result metadata and
    is optional, a hash that contains extra information.

  test_validate_args(%args) -> [status, msg, result, meta]
    Does nothing, only here to test # VALIDATE_ARGS.

    Arguments ('*' denotes required arguments):

    *   a => *int*

    *   b => *str*

    *   h1 => *hash*

    Return value:

    Returns an enveloped result (an array). First element (status) is an
    integer containing HTTP status code (200 means OK, 4xx caller error, 5xx
    function error). Second element (msg) is a string containing error
    message, or 'OK' if status is 200. Third element (result) is optional,
    the actual result. Fourth element (meta) is called result metadata and
    is optional, a hash that contains extra information.

  undescribed_args(%args) -> [status, msg, 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.

    Arguments ('*' denotes required arguments):

    *   arg1 => *any*

    *   arg2 => *any*

    *   arg3 => *any*

    *   arg4 => *any*

    Return value:

    Returns an enveloped result (an array). First element (status) is an
    integer containing HTTP status code (200 means OK, 4xx caller error, 5xx
    function error). Second element (msg) is a string containing error
    message, or 'OK' if status is 200. Third element (result) is optional,
    the actual result. Fourth element (meta) is called result metadata and
    is optional, a hash that contains extra information.

