NAME
Perinci::Examples::CLI - Example for CLI help/usage generation
VERSION
This document describes version 0.49 of Perinci::Examples::CLI (from Perl distribution Perinci-Examples), released on 2015-01-20.
DESCRIPTION
{en_US The example(s) in this package are for demonstrating how the function metadata is converted into CLI help example (produced by --help
or --help --verbose
). Also for testing how it is converted into POD for scripts (i.e. the OPTIONS
section). }
FUNCTIONS
demo_cli_opts(%args) -> [status, msg, result, meta]
{en_US Summary for `demo_cli_opts`}.
Examples:
demo_cli_opts( array1 => ["elem1", "elem2"], int1 => 10, str1 => "a value");
Summary for an example.
demo_cli_opts( array1 => [1, 2], int1 => 20, str1 => "x");
A second example.
{en_US Description for demo_cli_opts
.
This is another paragraph from the description. Description by default is assumed to be marked up in Markdown (currently referring to CommonMark).
This paragraph should be set in verbatim.
}
Arguments ('*' denotes required arguments):
are_baz => bool
{en_US This demonstrate negation of --are-foo to --arent-foo}.
array1* => array[str]
{en_US Positional, greedy, and plural}.
{en_US Argument with non-scalar types (like array or hash) can be specified in the CLI using
--ARG-json
or--ARG-yaml
. Arguments with type of array of string can also be specified using multiple--ARG
options.This option also links to another option. }
bool1 => bool
{en_US A bool option}.
{en_US CLI framework should generate
--nobool1
(and--nobool1
) automatically.This option has an alias,
-z
. Because the alias has its own summary/description, it will be displayed separately. }flag1 => bool
{en_US A flag option}.
{en_US A flag option is a bool option with the value of 1 (true). It is meant to activate something if specified and there is no notion of disabling by specifying the opposite. Thus the CLI framework should not generate a
--noflag1
option.This flag has an alias
-f
with no summary/description nor code. So the CLI framework should display the alias along with the option. Note that short (single-letter) options/aliases do not get--noX
. }full => bool (default: 1)
{en_US Turn on full processing}.
{en_US Another bool option with on default.
CLI framework should perhaps show
--nobool2
instead of--bool2
because--bool2
is active by default. And if it does so, it should also show the negative summary in thesummary.alt.bool.not
attribute instead of the normalsummary
property. }full2 => bool (default: 1)
{en_US Use full processing (2)}.
{en_US Another bool option with on default. Because this option does not have
summary.alt.bool.not
, CLI framework should not show any summary, despite the existence ofsummary
. }gender => str
{en_US A string option}.
{en_US This option contains flag aliases that have code. }
hash1 => hash (default: {default=>1})
{en_US Demonstrate hash argument with default value from schema}.
input => buf
{en_US Specify input}.
{en_US This option demonstrates the
cmdline_src
property. Also, since schema type isbuf
, we know that the value is binary data. CLI framework will provide--input-base64
to allow specifying binary data encoded in base64. }int1* => int
{en_US Demonstrate an option with no summary. And a required option. }
int2 => int (default: 10)
{en_US Another int option}.
{en_US Demonstrate a scalar/simple default value. }
is_bar => bool
{en_US This demonstrate negation of --is-foo to --isnt-foo}.
output => str
{en_US Specify output filename}.
{en_US This option demonstrates how the option would be displayed in the help/usage. Due to the
x.schema.entity
attribute giving hint about what the value is, CLI framework can show:--output=file
instead of the plain and less informative:
--output=s
}
pass => str
str1* => str
{en_US A required option as well as positional argument}.
with_foo => bool
{en_US This demonstrate negation of --with-foo to --without-foo}.
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.
Return value: (any)
demo_cli_opts_shorter(%args) -> [status, msg, result, meta]
{en_US Function summary}.
Examples:
demo_cli_opts_shorter( bool1 => 1, str1 => "a value");
Summary for an example.
Arguments ('*' denotes required arguments):
bool1 => bool
{en_US Another bool option}.
flag1 => bool
str1* => str
{en_US A required option as well as positional argument}.
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.
Return value: (any)
SEE ALSO
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) 2015 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.