NAME

Perinci::Examples - Various examples of Rinci metadata

VERSION

This document describes version 0.825 of Perinci::Examples (from Perl distribution Perinci-Examples), released on 2024-07-17.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

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

To install Perinci::Examples, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Perinci::Examples

CPAN shell

perl -MCPAN -e shell
install Perinci::Examples

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

DESCRIPTION

FUNCTIONS

arg_default

args_as_array

args_as_arrayref

args_as_hashref

binary

call_gen_array

call_randlog

comment_fruit

common_opts

completion

delay

dies

dry_run

dry_run_default

err

gen_array

gen_hash

gen_random_bytes

gen_sample_data

merge_hash

multi_status

noop

noop2

randlog

result_naked

return_args

sum

undescribed_args

validate_args

HOMEPAGE

SOURCE

SEE ALSO

AUTHOR

CONTRIBUTOR

CONTRIBUTING

COPYRIGHT AND LICENSE

BUGS

Module Install Instructions