NAME

Perinci::CmdLine::Classic - Rinci/Riap-based command-line application framework

VERSION

This document describes version 1.818 of Perinci::CmdLine::Classic (from Perl distribution Perinci-CmdLine-Classic), released on 2023-10-30.

SYNOPSIS

In gen-random-num script:

use Perinci::CmdLine::Classic;

our %SPEC;

$SPEC{gen_random_num} = {
    v => 1.1,
    summary => 'Generate some random numbers',
    args => {
        count => {
            summary => 'How many numbers to generate',
            schema => ['int*' => min=>0],
            default => 1,
            cmdline_aliases=>{n=>{}},
            req => 1,
            pos => 0,
        },
        min => {
            summary => 'Lower limit of random number',
            schema => 'float*',
            default => 0,
        },
        max => {
            summary => 'Upper limit of random number',
            schema => 'float*',
            default => 1,
        },
    },
    result_naked => 1,
};
sub gen_random_num {
    my %args = @_;

    my @res;
    for (1..$args{count}) {
        push @res, $args{min} + rand()*($args{max}-$args{min});
    }
    \@res;
}

Perinci::CmdLine::Classic->new(url => '/main/gen_random_num')->run;

Run your script:

% ./gen-random-num
0.999473691060306

% ./gen-random-num --min 1 --max 10 5
1.27390166158969
1.69077475473679
8.97748327778684
5.86943773494068
8.34341298182493

JSON output support out of the box:

% ./gen-random-num -n3 --json
[200,"OK (envelope added by Perinci::Access::Lite)",[0.257073684902029,0.393782991540746,0.848740540017513],{}]

Automatic help message:

% ./gen-random-num -h
gen-random-num - Generate some random numbers

Usage:
  gen-random-num --help (or -h, -?)
  gen-random-num --version (or -v)
  gen-random-num [options] [count]
Options:
  --config-path=s     Set path to configuration file
  --config-profile=s  Set configuration profile to use
  --count=i, -n       How many numbers to generate (=arg[0]) [1]
  --format=s          Choose output format, e.g. json, text [undef]
  --help, -h, -?      Display this help message
  --json              Set output format to json
  --max=f             Upper limit of random number [1]
  --min=f             Lower limit of random number [0]
  --naked-res         When outputing as JSON, strip result envelope [0]
  --no-config         Do not use any configuration file
  --version, -v

Automatic configuration file support:

% cat ~/gen-random-num.conf
count=5
max=0.01

% ./gen-random-num
0.00105268954838724
0.00701443611501844
0.0021247476506154
0.00813872824513005
0.00752832346491306

Automatic tab completion support:

% complete -C gen-random-num gen-random-num
% gen-random-num --mi<tab>

See Perinci::CmdLine::Manual for details on other available features (subcommands, automatic formatting of data structures, automatic schema validation, dry-run mode, automatic POD generation, remote function support, automatic CLI generation, automatic --version, automatic HTTP API, undo/transactions, configurable output format, logging, progress bar, colors/Unicode, and more).

DESCRIPTION

Perinci::CmdLine is a command-line application framework. It allows you to create full-featured CLI applications easily and quickly.

See Perinci::CmdLine::Manual for more details.

There is also a blog post series on Perinci::CmdLine tutorial: https://perlancar.wordpress.com/category/pericmd-tut/

Perinci::CmdLine::Classic is the heavier backend implementation which supports some extra features currently not supported by the default backend implementation Perinci::CmdLine::Lite. These features come at some startup overhead cost and more dependencies. You normally should use Perinci::CmdLine::Any instead to be able to switch backend on the fly.

Screenshots:

Autogenerated help message

Autogenerated help message (verbose mode)

Progress bar

Tab completion

Some output formats

Undo/redo

REQUEST KEYS

See also Perinci::CmdLine::Base. Extra stuffs put by this module to the $r hash/stash.

format_options => hash

RESULT METADATA

All those supported by Perinci::CmdLine::Base, plus:

x.hint.result_binary => bool

If set to true, then when formatting to text formats, this class won't print any newline to keep the data being printed unmodified.

ATTRIBUTES

All the attributes of Perinci::CmdLine::Base, plus:

use_utf8 => BOOL

From Term::App::Role::Attrs (please see its docs for more details). There are several other attributes added by the role.

undo => BOOL (optional, default 0)

Whether to enable undo/redo functionality. Some things to note if you intend to use undo:

These common command-line options will be recognized

--undo, --redo, --history, --clear-history.
Transactions will be used

use_tx=>1 will be passed to Perinci::Access, which will cause it to initialize the transaction manager. Riap requests begin_tx and commit_tx will enclose the call request to function.
Called function will need to support transaction and undo

Function which does not meet qualifications will refuse to be called.

Exception is when subcommand is specified with undo=>0, where transaction will not be used for that subcommand. For an example of disabling transaction for some subcommands, see bin/u-trash in the distribution.

undo_dir => STR (optional, default ~/.<program_name>/.undo)

Where to put undo data. This is actually the transaction manager's data dir.

METHODS

All the methods of Perinci::CmdLine::Base, plus:

ENVIRONMENT

All the environment variables that Perinci::CmdLine::Base supports, plus:

PERINCI_CMDLINE_COLOR_THEME => STR

Can be used to set color_theme.

PROGRESS => BOOL

Explicitly turn the progress bar on/off.

COLOR => INT

Please see Term::App::Role::Attrs.

UTF8 => BOOL

Please see Term::App::Role::Attrs.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Perinci-CmdLine-Classic.

SOURCE

Source repository is at https://github.com/perlancar/perl-Perinci-CmdLine-Classic.

AUTHOR

perlancar <perlancar@cpan.org>

CONTRIBUTORS

s1 <s1@localhost>
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-CmdLine-Classic

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::CmdLine::Classic, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Perinci::CmdLine::Classic

CPAN shell

perl -MCPAN -e shell
install Perinci::CmdLine::Classic

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)