perlancar > Perinci-Examples > Perinci::Examples

Download:
Perinci-Examples-0.43.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: 0.43   Source  

NAME ^

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

VERSION ^

This document describes version 0.43 of Perinci::Examples (from Perl distribution Perinci-Examples), released on 2014-11-20.

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.

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.

Arguments ('*' denotes required 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)

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

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

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

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

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

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

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

Arguments ('*' denotes required 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.

 (buf)

gen_sample_data(%args) -> [status, msg, result, meta]

Generate sample data of various form.

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

Arguments ('*' denotes required 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)

merge_hash(%args) -> [status, msg, 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 already generates and embeds argument validation code in the source code, so duplication is not desired, thus the attribute.

Arguments ('*' denotes required 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.

 (hash)

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

Arguments ('*' denotes required 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)

noop(%args) -> [status, msg, 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 pure (produce no side effects).

Arguments ('*' denotes required 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)

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

Produce some random Log::Any log messages.

Arguments ('*' denotes required 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)

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

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

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]

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 @_.

Arguments ('*' denotes required 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)

test_args_as_arrayref([$a0, $a1, $a2]) -> [status, msg, 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].

Arguments ('*' denotes required 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)

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

Arguments ('*' denotes required 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)

test_binary(%args) -> [status, msg, 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/test_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/test_binary",
     {v=>1.2}); # => [200,"OK","\0\0\0",{}]

Arguments ('*' denotes required 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.

 (buf)

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

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.

Arguments ('*' denotes required 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)

test_dry_run() -> [status, msg, 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 supports dry-run operation.

No arguments.

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

test_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].

Arguments ('*' denotes required arguments):

Return value:

 (any)

test_validate_args(%args) -> [status, msg, result, meta]

Does nothing, only here to test # VALIDATE_ARGS.

Arguments ('*' denotes required 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.

 (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):

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/perlancar/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 ^

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE ^

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

syntax highlighting: