view release on metacpan or  search on metacpan

lib/Perinci/CmdLine/Base.pm  view on Meta::CPAN

must return a hashref of subcommand specifications. If called with argument
C<name> it must return subcommand specification for subcommand with the
requested name only.

=head2 summary => str

Optional, displayed in description of the option in help/usage text.

=head2 tags => array of str

For grouping or categorizing subcommands, e.g. when displaying list of
subcommands.

=head2 url => str

Required if you only want to run one function. URL should point to a function
entity.

Alternatively you can provide multiple functions from which the user can select
using the first argument (see B<subcommands>).

=head2 read_env => bool (default: 1)

Whether to read environment variable for default options.

=head2 env_name => str

Environment name to read default options from. Default is from program name,
upper-cased, sequences of dashes/nonalphanums replaced with a single underscore,
plus a C<_OPT> suffix. So if your program name is called C<cpandb-cpanmeta> the
default environment name is C<CPANDB_CPANMETA_OPT>.

=head2 read_config => bool (default: 1)

Whether to read configuration files.

=head2 config_filename => str|array[str]|array[hash]

Configuration filename(s). The default is C<< program_name . ".conf" >>. For
example, if your program is named C<foo-bar>, config_filename will be
C<foo-bar.conf>.

You can specify an array of filename strings, which will be checked in order,
e.g.: C<< ["myapp.conf", "myapp.ini"] >>.

You can also specify an array of hashrefs, for more complex scenario. Each hash
can contain these keys: C<filename>, C<section>. For example:

 [
     {filename => 'mysuite.conf', section=>'myapp1'},
     {filename => 'myapp1.conf'}, # section = GLOBAL (default)
 ]

This means, configuration will be searched in C<mysuite.conf> under the section
C<myapp1>, and then in C<myapp1.conf> in the default/global section.

=head2 config_dirs => array of str

Which directories to look for configuration file. The default is to look at the
user's home and then system location. On Unix, it's C<< [ "$ENV{HOME}/.config",
$ENV{HOME}, "/etc"] >>. If $ENV{HOME} is empty, getpwuid() is used to get home
directory entry.

=head2 cleanser => obj

Object to cleanse result for JSON output. By default this is an instance of
L<Data::Clean::ForJSON> and should not be set to other value in most cases.

=head2 use_cleanser => bool (default: 1)

When a function returns result, and the user wants to display the result as
JSON, the result might need to be cleansed first (using L<Data::Clean::ForJSON>
by default) before it can be encoded to JSON, for example it might contain Perl
objects or scalar references or other stuffs. If you are sure that your function
does not produce those kinds of data, you can set this to false to produce a
more lightweight script.

=head2 extra_urls_for_version => array of str

An array of extra URLs for which version information is to be displayed for
the action being performed.

=head2 skip_format => bool

If set to 1, assume that function returns raw text that need not be translated,
and so will not offer common command-line options C<--format>, C<--json>, as
well as C<--naked-res>.

As an alternative to this, can also be done on a per-function level by setting
function metadata property C<cmdline.skip_format> to true. Or, can also be done
on a per-function result basis by returning result metadata
C<cmdline.skip_format> set to true.

=head2 use_utf8 => bool (default: from env UTF8, or 0)

Whether or not to set utf8 flag on output. If undef, will default to UTF8
environment. If that is also undef, will default to 0.

=head2 default_dry_run => bool (default: 0)

If set to 1, then dry-mode will be turned on by default unless user uses
DRY_RUN=0 or C<--no-dry-run>.

=head2 log => bool

Whether to enable logging. Default is off. If true, will load L<Log::ger::App>.

=head2 log_level => str

Set default log level. Will be overridden by C<< $r->{log_level} >> which is set
from command-line options like C<--log-level>, C<--trace>, etc.

=head1 METHODS

=head2 $cmd->run() => ENVRES

The main method to run your application. See L</"PROGRAM FLOW (NORMAL)"> for
more details on what this method does.

=head2 $cmd->do_completion() => ENVRES