Venus::Cli

Cli Class

Cli Class for Perl 5

method: arg method: cmd method: exit method: fail method: help method: get method: okay method: opt method: parsed method: parser method: pass method: set method: str method: test

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(['--help']);

$cli->set('opt', 'help', {
  help => 'Show help information',
});

# $cli->opt('help');

# [1]

# $cli->parsed;

# {help => 1}

This package provides a superclass and methods for creating simple yet robust command-line interfaces.

Venus::Kind::Utility

Venus::Role::Stashable

The data attribute holds an arrayref of command-line arguments and defaults to @ARGV.

data(arrayref $data) (arrayref)

{ since => '2.55', }

=example-1 data

# given: synopsis

package main;

my $data = $cli->data([]);

# []

The arg method returns the value passed to the CLI that corresponds to the registered argument using the name provided.

arg(string $name) (any)

{ since => '2.55', }

=example-1 arg

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(['example', '--help']);

my $name = $cli->arg('name');

# undef

The cmd method returns truthy or falsy if the value passed to the CLI that corresponds to the argument registered and associated with the registered command using the name provided.

cmd(string $name) (any)

{ since => '2.55', }

=example-1 cmd

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(['example', 'execute']);

my $name = $cli->cmd('name');

# undef

The exit method exits the program using the exit code provided. The exit code defaults to 0. Optionally, you can dispatch before exiting by providing a method name or coderef, and arguments.

exit(number $code, string | coderef $code, any @args) (any)

{ since => '2.55', }

=example-1 exit

# given: synopsis

package main;

my $exit = $cli->exit;

# ()

The fail method exits the program with the exit code 1. Optionally, you can dispatch before exiting by providing a method name or coderef, and arguments.

fail(string | coderef $code, any @args) (any)

{ since => '2.55', }

=example-1 fail

# given: synopsis

package main;

my $fail = $cli->fail;

# ()

The get method returns arg, opt, cmd, or str configuration values from the configuration database.

get(string $type, string $name) (any)

{ since => '2.55', }

The help method returns a string representing "usage" information based on the configuration of the CLI.

help() (string)

{ since => '2.55', }

=example-1 help

package main;

use Venus::Cli;

my $cli = Venus::Cli->new;

my $help = $cli->help;

# "Usage: application"

The okay method exits the program with the exit code 0. Optionally, you can dispatch before exiting by providing a method name or coderef, and arguments.

okay(string | coderef $code, any @args) (any)

{ since => '2.55', }

=example-1 okay

# given: synopsis

package main;

my $okay = $cli->okay;

# ()

The opt method returns the value passed to the CLI that corresponds to the registered option using the name provided.

opt(string $name) (any)

{ since => '2.55', }

=example-1 opt

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(['example', '--help']);

my $name = $cli->opt('help');

# undef

The parsed method returns the values provided to the CLI for all registered arguments and options as a hashref.

parsed() (hashref)

{ since => '2.55', }

The parser method returns a Venus::Opts object using the "spec" returned based on the CLI configuration.

parser() (Venus::Opts)

{ since => '2.55', }

The pass method exits the program with the exit code 0. Optionally, you can dispatch before exiting by providing a method name or coderef, and arguments.

pass(string | coderef $code, any @args) (any)

{ since => '3.10', }

=example-1 pass

# given: synopsis

package main;

my $pass = $cli->pass;

# ()

The set method stores configuration values for arg, opt, cmd, or str data in the configuration database, and returns the invocant.

The following are configurable arg properties:

+=over 4

+=item *

The default property specifies the "default" value to be used if none is provided.

+=item *

The help property specifies the help text to output in usage instructions.

+=item *

The label property specifies the label text to output in usage instructions.

+=item *

The name property specifies the name of the argument.

+=item *

The prompt property specifies the text to be used in a prompt for input if no value is provided.

+=item *

The range property specifies the zero-indexed position where the CLI arguments can be found, using range notation.

+=item *

The required property specifies whether the argument is required and throws an exception is missing when fetched.

+=item *

The type property specifies the data type of the argument. Valid types are number parsed as a Getopt::Long integer, string parsed as a Getopt::Long string, float parsed as a Getopt::Long float, boolean parsed as a Getopt::Long flag, or yesno parsed as a Getopt::Long string. Otherwise, the type will default to boolean.

+=back

The following are configurable cmd properties:

+=over 4

+=item *

The arg property specifies the CLI argument where the command can be found.

+=item *

The help property specifies the help text to output in usage instructions.

+=item *

The label property specifies the label text to output in usage instructions.

+=item *

The name property specifies the name of the command.

+=back

The following are configurable opt properties:

+=over 4

+=item *

The alias property specifies the alternate identifiers that can be provided.

+=item *

The default property specifies the "default" value to be used if none is provided.

+=item *

The help property specifies the help text to output in usage instructions.

+=item *

The label property specifies the label text to output in usage instructions.

+=item *

The multi property denotes whether the CLI will accept multiple occurrences of the option.

+=item *

The name property specifies the name of the option.

+=item *

The prompt property specifies the text to be used in a prompt for input if no value is provided.

+=item *

The required property specifies whether the option is required and throws an exception is missing when fetched.

+=item *

The type property specifies the data type of the option. Valid types are number parsed as a Getopt::Long integer, string parsed as a Getopt::Long string, float parsed as a Getopt::Long float, boolean parsed as a Getopt::Long flag, or yesno parsed as a Getopt::Long string. Otherwise, the type will default to boolean.

+=back

set(string $type, string $name, string | hashref $data) (any)

{ since => '2.55', }

The spec method returns parser specifications for use with Getopt::Long.

spec() (arrayref)

{ since => '2.55', }

The str method gets or sets configuration strings used in CLI help text based on the arguments provided. The "help" method uses "name", "description", "header", and "footer" strings.

str(string $name) (any)

{ since => '2.55', }

The test method validates the values for the arg or opt specified and returns the value(s) associated. If validation failed an exception is thrown.

test(string $type, string $name) (any)

{ since => '3.10', }

This package may raise an error_on_arg_validation exception.

This package may raise an error_on_opt_validation exception.

t/Venus.t: present: authors t/Venus.t: present: license

cpanm Venus

perl -MCPAN -e shell
install Venus