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

VERSION
    This document describes version 0.29 of Perinci::Examples (from Perl
    distribution Perinci-Examples), released on 2014-08-21.

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.

FUNCTIONS
  arg_default(%args) -> [status, msg, result, meta]
    Demonstrate argument default value from default and/or schema.

    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.

    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.

     (any)

  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.

     (array)

  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.

     (any)

  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.

     (any)

  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.

     (any)

  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.

     (any)

  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.

     (array)

  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* (default: 10)

        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.

     (array)

  gen_sample_data(%args) -> [status, msg, result, meta]
    Generate sample data of various form.

    Arguments ('*' denotes required arguments):

    *   form* => *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.

     (any)

  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.

     (hash)

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

    Will also return argument passed to it.

    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.

     (any)

  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.

     (any)

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

    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.

     (any)

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

    Examples:

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

    First example.

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

    Second example, using argv.

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

    Third example, invalid arguments.

     sum();

    Total numbers found in a file (4th example, bash).

     sum();

    2-dice roll (5th example, perl).

    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.

     (any)

  test_args_as_array($a0, $a1, $a2) -> [status, msg, result, meta]
    Arguments ('*' denotes required arguments):

    *   a0 => *str*

    *   a1 => *str*

    *   a2 => *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.

     (any)

  test_args_as_arrayref([$a0, $a1, $a2]) -> [status, msg, result, meta]
    Arguments ('*' denotes required arguments):

    *   a0 => *str*

    *   a1 => *str*

    *   a2 => *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.

     (any)

  test_args_as_hashref(\%args) -> [status, msg, result, meta]
    Arguments ('*' denotes required arguments):

    *   a0 => *str*

    *   a1 => *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.

     (any)

  test_common_opts(%args) -> [status, msg, result, meta]
    This function has arguments with the same name as Perinci::CmdLine
    common options.

    Arguments ('*' denotes required arguments):

    *   action => *str*

    *   cmd => *str*

    *   debug => *bool*

    *   format => *str*

    *   format_options => *str*

    *   help => *bool*

    *   json => *bool*

    *   log_level => *str*

    *   perl => *bool*

    *   quiet => *bool*

    *   subcommands => *str*

    *   trace => *bool*

    *   verbose => *bool*

    *   version => *str*

    *   yaml => *bool*

    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.

     (any)

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

    This function is used to test argument completion.

    This function is pure (produce no side effects).

    Arguments ('*' denotes required arguments):

    *   a1 => *array*

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

    *   a2 => *array*

        Array with element_completion routine that generate random letter.

    *   a3 => *array*

        Array with element_completion routine that dies.

    *   arg0 => *any*

        Argument without any schema.

    *   f0 => *float*

        Float with just "float" schema defined.

    *   f1 => *float*

        Float with xmin/xmax on the schema.

    *   i0 => *int*

        Integer with just "int" schema defined.

    *   i1 => *int*

        Integer with min/xmax on the schema.

    *   i2 => *int*

        Integer with large range min/max on the schema.

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

    *   s2 => *str*

        String with completion routine that generate random letter.

    *   s3 => *str*

        String with completion routine that dies.

    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.

     (any)

  test_dry_run() -> [status, msg, result, meta]
    Will return 'wet' if not run under dry run mode, or 'dry' if dry run.

    This function supports dry-run operation.

    No arguments.

    Special arguments:

    *   -dry_run => *bool*

        Pass -dry_run=>1 to enable simulation mode.

    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.

     (any)

  test_result_naked(%args) -> any
    Arguments ('*' denotes required arguments):

    *   a0 => *str*

    *   a1 => *str*

    Return value:

     (any)

  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.

     (str)

  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.

     (any)

SEE ALSO
    Perinci

    Perinci::Examples::Bin

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

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

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.

AUTHOR
    Steven Haryanto <stevenharyanto@gmail.com>

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