/ 
Dist-Zilla-Plugin-GenPericmdScript-0.425
River stage one • 1 direct dependent • 1 total dependent
/ Dist::Zilla::Plugin::GenPericmdScript

NAME

Dist::Zilla::Plugin::GenPericmdScript - Generate Perinci::CmdLine script

VERSION

This document describes version 0.425 of Dist::Zilla::Plugin::GenPericmdScript (from Perl distribution Dist-Zilla-Plugin-GenPericmdScript), released on 2023-07-11.

SYNOPSIS

In dist.ini:

; generate a script, by default called script/check-palindrome
[GenPericmdScript]
url=/My/Palindrome/check_palindrome

; generate another script, called script/lssrv
[GenPericmdScript / Gen_lssrv]
url=/My/App/list_servers
name=lssrv

After build, script/check-palindrome and script/lssrv will be created.

DESCRIPTION

After you add Rinci metadata to your function, e.g.:

package My::Palindrome;
$SPEC{check_palindrome} = {
    v => 1.1,
    args => {
        text => { schema=>'str*', req=>1, pos=>0 },
        ci   => { schema=>'bool*', cmdline_aliases=>{i=>{}} },
    },
    result_naked => 1,
};
sub check_palindrome {
    my %args = @_;
    my $text = $args{ci} ? lc($args{text}) : $args{text};
    $text eq reverse($text);
}

you can create a command-line script for that function that basically is not much more than:

#!perl
use Perinci::CmdLine::Any;
Perinci::CmdLine::Any->new(url => '/My/Palindrome/check_palindrome');

This Dist::Zilla plugin lets you automate the creation of such scripts.

Creating scripts. To create a single script, put this in dist.ini:

[GenPericmdScript]
;required
url=/My/Palindrome/check_palindrome
;optional
abstract=Check if a text is a palindrome
; ...

To create more scripts, load the plugin again using the [Plugin/Name] syntax, e.g.:

[GenPericmdScript / GenAnotherScript]
...

CONFIGURATION (SCRIPT SPECIFICATION)

allow_prereq

Boolean. Will be passed to Perinci::CmdLine::Gen backend.

allow_unknown_opts

Boolean, default false. Will be passed to Perinci::CmdLine object construction code.

cmdline

String. Select module to use. Default is Perinci::CmdLine::Any, but you can set this to classic (equals to Perinci::CmdLine::Classic), any (Perinci::CmdLine::Any), or lite (Perinci::CmdLine::Lite) or module name.

code_after_end

String.

code_before_instantiate_cmdline

String.

config_dirs

Array of strings. Will be passed to Perinci::CmdLine object construction code.

config_filename

String or array of strings. Will be passed to Perinci::CmdLine object construction code.

copt_help_enable

Boolean, default true. Will be passed to Perinci::CmdLine::Gen backend. Can be used to disable `--help` in generated CLI.

copt_help_getopt

String. Will be passed to Perinci::CmdLine::Gen backend. Can be used to change `--help` in generated CLI to some other option name.

copt_version_enable

Boolean, default true. Will be passed to Perinci::CmdLine::Gen backend. Can be used to disable `--version in generated CLI`.

copt_version_getopt

String. Will be passed to Perinci::CmdLine::Gen backend. Can be used to change the `--version` in generated CLI to some other option name.

default_format

String. Passed to Perinci::CmdLine object construction code.

default_log_level

String. If set, will add this code to the generated script:

BEGIN { no warnings; $main::Log_Level = "..." }

This can be used if you want your script to be verbose by default, for example.

enable_log

Boolean, default false. Will be passed to Perinci::CmdLine object construction code (as log).

exclude_package_functions_match

Regex. Will be passed to Perinci::CmdLine::Gen backend.

extra_urls_for_version

Comma-separated string, will be passed to Perinci::CmdLine object construction code (as array).

include_package_functions_match

Regex. Will be passed to Perinci::CmdLine::Gen backend.

load_modules

Array of strings. Extra modules to load in the generated script.

name

String. Name of script to create. Default will be taken from function (or package) name, with _ replaced to -.

pass_cmdline_object

Boolean, default false. Will be passed to Perinci::CmdLine object construction code.

per_arg_json

Boolean. Will be passed to Perinci::CmdLine::Gen backend.

per_arg_yaml

Boolean. Will be passed to Perinci::CmdLine::Gen backend.

prefer_lite

Boolean, default true. If set to 0 and you are using Perinci::CmdLine::Any, -prefer_lite option will be passed in the code.

read_config

Boolean, default true. Will be passed to Perinci::CmdLine::Gen backend. Can be used to prevent the generated CLI from reading from config files.

read_env

Bool, default true. Will be passed to Perinci::CmdLine::Gen backend. Can be used to prevent the genreated CLI from reading from environment variable.

skip_format

Boolean. Passed to Perinci::CmdLine object construction code.

ssl_verify_hostname

Boolean, default true. If set to 0, will add this code to the generated script:

$ENV{PERL_LWP_SSL_VERIFY_HOSTNAME} = 0;

This can be used if the Riap function URL is https and you don't want to verify.

subcommands

String. For creating a CLI script with subcommands. Value is a whitespace-separated entries of subcommand specification. Each subcommand specification must be in the form of SUBCOMMAND_NAME=URL[:SUMMARY]. Example:

delete=/My/App/delete_item add=/My/App/add_item refresh=/My/App/refresh_item:Refetch an item from source

subcommands_from_package_functions

Boolean. Will be passed to Perinci::CmdLine::Gen backend.

summary

String. Will be passed to Perinci::CmdLine::Gen backend (as script_summary).

url

String, required. Riap URL. If the script does not contain subcommand, this should refer to a function URL. If the script contains subcommands, this should usually refer to a package URL.

use_utf8

Boolean. Passed to Perinci::CmdLine object construction code.

CONFIGURATION (OTHER)

inline_generate_completer => bool (default: 1)

Perinci::CmdLine::Inline-generated scripts currently cannot do shell completion on its own, but relies on a separate completer script (e.g. if the script is script/foo then the completer will be generated at script/_foo). This option can be used to suppress the generation of completer script.

build_load_modules => array[str]

Load modules during build process.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Dist-Zilla-Plugin-GenPericmdScript.

SOURCE

Source repository is at https://github.com/perlancar/perl-Dist-Zilla-Plugin-GenPericmdScript.

SEE ALSO

Perinci::CmdLine, the kind of CLI script this plugin is generating.

Perinci and Rinci, for the background information.

Dist::Zilla::Plugin::Perinci::CmdLine, if you are building Perinci::CmdLine::* distribution.

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 software is copyright (c) 2023, 2022, 2020, 2018, 2017, 2016, 2015, 2014 by perlancar <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.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Dist-Zilla-Plugin-GenPericmdScript

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.