Venus::Cli

Cli Class

Cli Class for Perl 5

method: args method: argument method: argument_choice method: argument_choices method: argument_count method: argument_default method: argument_errors method: argument_help method: argument_label method: argument_list method: argument_multiples method: argument_name method: argument_names method: argument_prompt method: argument_range method: argument_required method: argument_type method: argument_validate method: argument_value method: argument_wants method: assigned_arguments method: assigned_options method: boolean method: choice method: choice_argument method: choice_count method: choice_default method: choice_errors method: choice_help method: choice_label method: choice_list method: choice_multiples method: choice_name method: choice_names method: choice_prompt method: choice_range method: choice_required method: choice_type method: choice_validate method: choice_value method: choice_wants method: command method: dispatch method: exit method: fail method: float method: has_input method: has_input_arguments method: has_input_options method: has_output method: has_output_debug_events method: has_output_error_events method: has_output_fatal_events method: has_output_info_events method: has_output_trace_events method: has_output_warn_events method: help method: input method: input_argument_count method: input_argument_list method: input_arguments method: input_arguments_defined method: input_arguments_defined_count method: input_arguments_defined_list method: input_option_count method: input_option_list method: input_options method: input_options_defined method: input_options_defined_count method: input_options_defined_list method: lines method: log method: log_debug method: log_error method: log_events method: log_fatal method: log_flush method: log_handler method: log_info method: log_level method: log_trace method: log_warn method: multiple method: new method: no_input method: no_input_arguments method: no_input_options method: no_output method: no_output_debug_events method: no_output_error_events method: no_output_fatal_events method: no_output_info_events method: no_output_trace_events method: no_output_warn_events method: number method: okay method: option method: option_aliases method: option_count method: option_default method: option_errors method: option_help method: option_label method: option_list method: option_multiples method: option_name method: option_names method: option_prompt method: option_range method: option_required method: option_type method: option_validate method: option_value method: option_wants method: optional method: opts method: output method: output_debug_events method: output_error_events method: output_fatal_events method: output_info_events method: output_trace_events method: output_warn_events method: parse method: parse_specification method: parsed method: parsed_arguments method: parsed_options method: pass method: reorder method: reorder_arguments method: reorder_choices method: reorder_options method: reorder_routes method: route method: route_argument method: route_choice method: route_count method: route_handler method: route_help method: route_label method: route_list method: route_name method: route_names method: route_range method: required method: reset method: single method: spec method: string method: usage method: usage_argument_default method: usage_argument_help method: usage_argument_label method: usage_argument_required method: usage_argument_token method: usage_arguments method: usage_choice_help method: usage_choice_label method: usage_choice_required method: usage_choices method: usage_description method: usage_footer method: usage_gist method: usage_header method: usage_line method: usage_name method: usage_option_default method: usage_option_help method: usage_option_label method: usage_option_required method: usage_option_token method: usage_options method: usage_summary method: usage_version method: vars method: yesno

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

# $cli->usage;

# ...

# $cli->parsed;

# {help => 1}

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

Venus::Kind::Utility

Venus::Role::Printable

The name attribute is read-write, accepts (string) values, and is optional.

name(string $name) (string)

{ since => '4.15', }

The version attribute is read-write, accepts (string) values, and is optional.

version(string $version) (string)

{ since => '4.15', }

The summary attribute is read-write, accepts (string) values, and is optional.

summary(string $summary) (string)

{ since => '4.15', }

The description attribute is read-write, accepts (string) values, and is optional.

description(string $description) (string)

{ since => '4.15', }

The header attribute is read-write, accepts (string) values, and is optional.

header(string $header) (string)

{ since => '4.15', }

The footer attribute is read-write, accepts (string) values, and is optional.

footer(string $footer) (string)

{ since => '4.15', }

The arguments attribute is read-write, accepts (hashref) values, and is optional.

arguments(hashref $arguments) (hashref)

{ since => '4.15', }

The options attribute is read-write, accepts (hashref) values, and is optional.

options(hashref $options) (hashref)

{ since => '4.15', }

The choices attribute is read-write, accepts (hashref) values, and is optional.

choices(hashref $choices) (hashref)

{ since => '4.15', }

The data attribute is read-write, accepts (hashref) values, and is optional.

data(hashref $data) (hashref)

{ since => '4.15', }

The args method returns the list of parsed command-line arguments as a Venus::Args object.

args() (Venus::Args)

{ since => '4.15', }

The argument method registers and returns the configuration for the argument specified. The method takes a name (argument name) and a hashref of configuration values. The possible configuration values are as follows:

+=over 4

+=item *

The name key holds the name of the argument.

+=item *

The label key holds the name of the argument as it should be displayed in the CLI help text.

+=item *

The help key holds the help text specific to this argument.

+=item *

The default key holds the default value that should used if no value for this argument is provided to the CLI.

+=item *

The multiples key denotes whether this argument can be used more than once, to collect multiple values, and holds a 1 if multiples are allowed and a 0 otherwise.

+=item *

The prompt key holds the question or statement that should be presented to the user of the CLI if no value has been provided for this argument and no default value has been set.

+=item *

The range key holds a two-value arrayref where the first value is the starting index and the second value is the ending index. These values are used to select values from the parsed arguments array as the value(s) for this argument. This value is ignored if the multiples key is set to 0.

+=item *

The required key denotes whether this argument is required or not, and holds a 1 if required and a 0 otherwise.

+=item *

The type key holds the data type of the argument expected. Valid values are "number", "string", "float", "boolean", or "yesno". Note: Valid boolean values are 1, 0, "true", and "false".

+=back

argument(string $name, hashref $data) (maybe[hashref])

{ since => '4.15', }

The argument_choice method returns the parsed argument value only if it corresponds to a registered choice associated with the named argument. If the value (or any of the values) doesn't map to a choice, this method will return an empty arrayref. Returns a list in list context.

argument_choice(string $name) (arrayref)

{ since => '4.15', }

The argument_choices method returns all registered choices associated with the argument named. Returns a list in list context.

argument_choices(string $name) (arrayref)

{ since => '4.15', }

The argument_count method returns the count of registered arguments.

argument_count() (number)

{ since => '4.15', }

=example-1 argument_count

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $argument_count = $cli->argument_count;

# 0

The argument_default method returns the default configuration value for the named argument.

argument_default(string $name) (string)

{ since => '4.15', }

=example-1 argument_default

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $argument_default = $cli->argument_default;

# ""

The argument_errors method returns a list of "issues", if any, for each value returned by "argument_value" for the named argument. Returns a list in list context.

argument_errors(string $name) (within[arrayref, Venus::Validate])

{ since => '4.15', }

=example-1 argument_errors

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $argument_errors = $cli->argument_errors;

# []

The argument_help method returns the help configuration value for the named argument.

argument_help(string $name) (string)

{ since => '4.15', }

=example-1 argument_help

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $argument_help = $cli->argument_help;

# ""

The argument_label method returns the label configuration value for the named argument.

argument_label(string $name) (string)

{ since => '4.15', }

=example-1 argument_label

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $argument_label = $cli->argument_label;

# ""

The argument_list method returns a list of registered argument configurations. Returns a list in list context.

argument_list(string $name) (within[arrayref, hashref])

{ since => '4.15', }

=example-1 argument_list

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $argument_list = $cli->argument_list;

# []

The argument_multiples method returns the multiples configuration value for the named argument.

argument_multiples(string $name) (boolean)

{ since => '4.15', }

=example-1 argument_multiples

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $argument_multiples = $cli->argument_multiples;

# false

The argument_name method returns the name configuration value for the named argument.

argument_name(string $name) (string)

{ since => '4.15', }

=example-1 argument_name

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $argument_name = $cli->argument_name;

# ""

The argument_names method returns the names (keys) of registered arguments in the order declared. Returns a list in list context.

argument_names(string $name) (within[arrayref, string])

{ since => '4.15', }

=example-1 argument_names

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $argument_names = $cli->argument_names;

# []

The argument_prompt method returns the prompt configuration value for the named argument.

argument_prompt(string $name) (string)

{ since => '4.15', }

=example-1 argument_prompt

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $argument_prompt = $cli->argument_prompt;

# ""

The argument_range method returns the range configuration value for the named argument.

argument_range(string $name) (string)

{ since => '4.15', }

=example-1 argument_range

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $argument_range = $cli->argument_range;

# ""

The argument_required method returns the required configuration value for the named argument.

argument_required(string $name) (boolean)

{ since => '4.15', }

=example-1 argument_required

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $argument_required = $cli->argument_required;

# false

The argument_type method returns the type configuration value for the named argument. Valid values are as follows:

+=over 4

+=item *

number

+=item *

string

+=item *

float

+=item *

boolean - Note: Valid boolean values are 1, 0, "true", and "false".

+=item *

yesno

+=back

argument_type(string $name) (string)

{ since => '4.15', }

=example-1 argument_type

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $argument_type = $cli->argument_type;

# ""

The argument_validate method returns a Venus::Validate object for each value returned by "argument_value" for the named argument. Returns a list in list context.

argument_validate(string $name) (Venus::Validate | within[arrayref, Venus::Validate])

{ since => '4.15', }

=example-1 argument_validate

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $argument_validate = $cli->argument_validate;

# []

The argument_value method returns the parsed argument value for the named argument.

argument_value(string $name) (any)

{ since => '4.15', }

=example-1 argument_value

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $argument_value = $cli->argument_value;

# undef

The argument_wants method returns the wants configuration value for the named argument.

argument_wants(string $name) (string)

{ since => '4.15', }

=example-1 argument_wants

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $argument_wants = $cli->argument_wants;

# ""

The assigned_arguments method gets the values for the registered arguments.

assigned_arguments() (hashref)

{ since => '4.15', }

=example-1 assigned_arguments

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

$cli->argument('extra', {
  range => '0:',
  type => 'string',
});

local @ARGV = qw(--input stdin --output stdout hello world);

my $assigned_arguments = $cli->assigned_arguments;

# {extra => 'hello'}

The assigned_options method gets the values for the registered options.

assigned_options() (hashref)

{ since => '4.15', }

=example-1 assigned_options

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

$cli->argument('extra', {
  range => '0:',
  type => 'string',
});

local @ARGV = qw(--input stdin --output stdout hello world);

my $assigned_options = $cli->assigned_options;

# {input => 'stdin', output => 'stdout'}

The boolean method is a configuration dispatcher and shorthand for {'type', 'boolean'}. It returns the data or dispatches to the next configuration dispatcher based on the name provided and merges the configurations produced.

boolean(string $method, any @args) (any)

{ since => '4.15', }

The choice method registers and returns the configuration for the choice specified. The method takes a name (choice name) and a hashref of configuration values. The possible configuration values are as follows:

+=over 4

+=item *

The name key holds the name of the argument.

+=item *

The label key holds the name of the argument as it should be displayed in the CLI help text.

+=item *

The help key holds the help text specific to this argument.

+=item *

The argument key holds the name of the argument that this choice is a value for.

+=item *

The wants key holdd the text to be used as a value placeholder in the CLI help text.

+=back

choice(string $name, hashref $data) (maybe[hashref])

{ since => '4.15', }

=example-1 choice

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

$cli->argument('input', {
  range => '0',
  type => 'string',
});

my $choice = $cli->choice('stdin', {
  argument => 'input',
});

# {
#   name => 'stdin',
#   label => undef,
#   help => undef,
#   argument => 'input',
#   index => 0,
#   wants => 'string',
# }

The choice_argument method returns the argument configuration corresponding with the argument value of the named choice.

choice_argument(string $name) (hashref)

{ since => '4.15', }

=example-1 choice_argument

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

$cli->argument('input', {
  type => 'string',
});

$cli->choice('stdin', {
  argument => 'input',
});

my $choice_argument = $cli->choice_argument('stdin');

# {
#   name => 'input',
#   label => undef,
#   help => 'Expects a string value',
#   default => undef,
#   multiples => 0,
#   prompt => undef,
#   range => undef,
#   required => 0,
#   type => 'string',
#   index => 0,
#   wants => 'string',
# }

The choice_count method returns the count of registered choices.

choice_count() (number)

{ since => '4.15', }

=example-1 choice_count

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $choice_count = $cli->choice_count;

# 0

The choice_default method returns the default configuration value for the argument corresponding to the named choice.

choice_default(string $name) (string)

{ since => '4.15', }

=example-1 choice_default

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

$cli->argument('input', {
  default => 'file',
  type => 'string',
});

$cli->choice('stdin', {
  argument => 'input',
});

my $choice_default = $cli->choice_default('stdin');

# "file"

The choice_errors method returns a list of "issues", if any, for each value returned by "choice_value" for the named choice. Returns a list in list context.

choice_errors(string $name) (within[arrayref, Venus::Validate])

{ since => '4.15', }

=example-1 choice_errors

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $choice_errors = $cli->choice_errors;

# []

The choice_help method returns the help configuration value the named choice.

choice_help(string $name) (string)

{ since => '4.15', }

=example-1 choice_help

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $choice_help = $cli->choice_help;

# ""

The choice_label method returns the label configuration value for the named choice.

choice_label(string $name) (string)

{ since => '4.15', }

=example-1 choice_label

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $choice_label = $cli->choice_label;

# ""

The choice_list method returns a list of registered choice configurations. Returns a list in list context.

choice_list(string $name) (within[arrayref, hashref])

{ since => '4.15', }

=example-1 choice_list

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $choice_list = $cli->choice_list;

# []

The choice_multiples method returns the multiples configuration value for the argument corresponding to the named choice.

choice_multiples(string $name) (boolean)

{ since => '4.15', }

=example-1 choice_multiples

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $choice_multiples = $cli->choice_multiples;

# false

The choice_name method returns the name configuration value for the named choice.

choice_name(string $name) (string)

{ since => '4.15', }

=example-1 choice_name

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $choice_name = $cli->choice_name;

# ""

The choice_names method returns the names (keys) of registered choices in the order declared. Returns a list in list context.

choice_names(string $name) (within[arrayref, string])

{ since => '4.15', }

=example-1 choice_names

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $choice_names = $cli->choice_names;

# []

The choice_prompt method returns the prompt configuration value for the argument corresponding to the named choice.

choice_prompt(string $name) (string)

{ since => '4.15', }

=example-1 choice_prompt

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $choice_prompt = $cli->choice_prompt;

# ""

The choice_range method returns the range configuration value for the argument corresponding to the named choice.

choice_range(string $name) (string)

{ since => '4.15', }

=example-1 choice_range

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $choice_range = $cli->choice_range;

# ""

The choice_required method returns the required configuration value for the argument corresponding to the named choice.

choice_required(string $name) (boolean)

{ since => '4.15', }

=example-1 choice_required

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $choice_required = $cli->choice_required;

# false

The choice_type method returns the type configuration value for the argument corresponding to the named choice.

choice_type(string $name) (string)

{ since => '4.15', }

=example-1 choice_type

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $choice_type = $cli->choice_type;

# ""

The choice_validate method returns a Venus::Validate object for each value returned by "choice_value" for the named choice. Returns a list in list context.

choice_validate(string $name) (within[arrayref, Venus::Validate])

{ since => '4.15', }

=example-1 choice_validate

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $choice_validate = $cli->choice_validate;

# []

The choice_value method returns the parsed choice value for the named choice.

choice_value(string $name) (any)

{ since => '4.15', }

=example-1 choice_value

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $choice_value = $cli->choice_value;

# undef

The choice_wants method returns the wants configuration value for the argument corresponding to the named choice.

choice_wants(string $name) (string)

{ since => '4.15', }

=example-1 choice_wants

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $choice_wants = $cli->choice_wants;

# ""

The command method creates and associates an argument, choice, and route. It takes an argument name, a choice name (string or arrayref of parts), and a handler (method name or coderef). The method returns the route configuration for the command.

command(string $argument, string | arrayref $choice, string | coderef $handler) (maybe[hashref])

{ since => '4.15', }

=example-1 command

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $command = $cli->command('command', ['user', 'create'], 'handle_user_create');

# {
#   name => 'user create',
#   label => undef,
#   help => undef,
#   argument => 'command',
#   choice => 'user create',
#   handler => 'handle_user_create',
#   range => ':1',
#   index => 0,
# }

The dispatch method parses CLI arguments, matches them against registered routes, and invokes the appropriate handler. If the handler is a coderef, it is called with the CLI instance, "assigned_arguments", and "assigned_options". If the handler is a local method name, it is called with </assigned_arguments>, and "assigned_options". If the handler is a package name, the package is loaded and instantiated. If the package is a Venus::Task, its "handle" in Venus::Task method is called. If the package is a Venus::Cli, its "dispatch" method is called. When dispatching to a package, only the relevant portion of the command line arguments (after the matched command) is passed.

dispatch(any @args) (any)

{ since => '4.15', }

=example-1 dispatch

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $dispatch = $cli->dispatch;

# undef

The exit method terminates the program with a specified exit code. If no exit code is provided, it defaults to 0, indicating a successful exit. This method can be used to end the program explicitly, either after a specific task is completed or when an error occurs that requires halting execution. This method can dispatch to another method or callback before exiting.

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

{ since => '4.15', }

The fail method terminates the program with a the exit code 1, indicating a failure on exit. This method can be used to end the program explicitly, either after a specific task is completed or when an error occurs that requires halting execution. This method can dispatch to another method or callback before exiting.

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

{ since => '4.15', }

The float method is a configuration dispatcher and shorthand for {'type', 'float'}. It returns the data or dispatches to the next configuration dispatcher based on the name provided and merges the configurations produced.

float(string $method, any @args) (any)

{ since => '4.15', }

The has_input method returns true if input arguments and/or options are found, and otherwise returns false.

has_input() (boolean)

{ since => '4.15', }

=example-1 has_input

# given: synopsis

package main;

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

my $has_input = $cli->has_input;

# false

The has_input_arguments method returns true if input arguments are found, and otherwise returns false.

has_input_arguments() (boolean)

{ since => '4.15', }

=example-1 has_input_arguments

# given: synopsis

package main;

$cli->argument('args', {
  range => '0:',
  type => 'string',
});

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

my $has_input_arguments = $cli->has_input_arguments;

# false

The has_input_options method returns true if input options are found, and otherwise returns false.

has_input_options() (boolean)

{ since => '4.15', }

=example-1 has_input_options

# given: synopsis

package main;

$cli->argument('args', {
  range => '0:',
  type => 'string',
});

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

my $has_input_options = $cli->has_input_options;

# false

The has_output method returns true if output events are found, and otherwise returns false.

has_output() (boolean)

{ since => '4.15', }

=example-1 has_output

# given: synopsis

package main;

$cli->argument('args', {
  range => '0:',
  type => 'string',
});

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

my $has_output = $cli->has_output;

# false

The has_output_debug_events method returns true if debug output events are found, and otherwise returns false.

has_output_debug_events() (boolean)

{ since => '4.15', }

=example-1 has_output_debug_events

# given: synopsis

package main;

$cli->argument('args', {
  range => '0:',
  type => 'string',
});

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

$cli->log_info('example output');

my $has_output_debug_events = $cli->has_output_debug_events;

# false

The has_output_error_events method returns true if error output events are found, and otherwise returns false.

has_output_error_events() (boolean)

{ since => '4.15', }

=example-1 has_output_error_events

# given: synopsis

package main;

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

$cli->log_info('example output');

my $has_output_error_events = $cli->has_output_error_events;

# false

The has_output_fatal_events method returns true if fatal output events are found, and otherwise returns false.

has_output_fatal_events() (boolean)

{ since => '4.15', }

=example-1 has_output_fatal_events

# given: synopsis

package main;

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

$cli->log_info('example output');

my $has_output_fatal_events = $cli->has_output_fatal_events;

# false

The has_output_info_events method returns true if info output events are found, and otherwise returns false.

has_output_info_events() (boolean)

{ since => '4.15', }

=example-1 has_output_info_events

# given: synopsis

package main;

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

$cli->log_info('example output');

my $has_output_info_events = $cli->has_output_info_events;

# true

The has_output_trace_events method returns true if trace output events are found, and otherwise returns false.

has_output_trace_events() (boolean)

{ since => '4.15', }

=example-1 has_output_trace_events

# given: synopsis

package main;

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

$cli->log_info('example output');

my $has_output_trace_events = $cli->has_output_trace_events;

# false

The has_output_warn_events method returns true if warn output events are found, and otherwise returns false.

has_output_warn_events() (boolean)

{ since => '4.15', }

=example-1 has_output_warn_events

# given: synopsis

package main;

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

$cli->log_info('example output');

my $has_output_warn_events = $cli->has_output_warn_events;

# false

The help method uses "log_info" method to output CLI usage/help text.

help() (Venus::Cli)

{ since => '4.15', }

=example-1 help

# given: synopsis

package main;

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

my $help = $cli->help;

# bless(..., "Venus::Cli")

The input method returns input arguments in scalar context, and returns arguments and options in list context. Arguments and options are returned as hashrefs.

input() (hashref)

{ since => '4.15', }

=example-1 input

# given: synopsis

package main;

$cli->argument('args', {
  range => '0:',
  type => 'string',
});

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

my $input = $cli->input;

# {args => undef}

The input_argument_count method returns the number of arguments provided to the CLI.

input_argument_count() (number)

{ since => '4.15', }

=example-1 input_argument_count

# given: synopsis

package main;

$cli->argument('args', {
  range => '0:',
  multiples => 1,
  type => 'string',
});

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

my $input_argument_count = $cli->input_argument_count;

# 1

The input_argument_list method returns the list of argument names as an arrayref in scalar context, and as a list in list context.

input_argument_list() (arrayref)

{ since => '4.15', }

=example-1 input_argument_list

# given: synopsis

package main;

$cli->argument('args', {
  range => '0:',
  multiples => 1,
  type => 'string',
});

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

my $input_argument_list = $cli->input_argument_list;

# ['args']

The input_arguments method returns the list of argument names and values as a hashref.

input_arguments() (hashref)

{ since => '4.15', }

=example-1 input_arguments

# given: synopsis

package main;

$cli->argument('args', {
  range => '0:',
  multiples => 1,
  type => 'string',
});

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

my $input_arguments = $cli->input_arguments;

# {args => []}

The input_arguments_defined method returns the list of argument names and values as a hashref, excluding undefined and empty arrayref values.

input_arguments_defined() (hashref)

{ since => '4.15', }

=example-1 input_arguments_defined

# given: synopsis

package main;

$cli->argument('args', {
  range => '0:',
  multiples => 1,
  type => 'string',
});

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

my $input_arguments_defined = $cli->input_arguments_defined;

# {}

The input_arguments_defined_count method returns the number of arguments found using "input_arguments_defined".

input_arguments_defined_count() (number)

{ since => '4.15', }

=example-1 input_arguments_defined_count

# given: synopsis

package main;

$cli->argument('args', {
  range => '0:',
  multiples => 1,
  type => 'string',
});

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

my $input_arguments_defined_count = $cli->input_arguments_defined_count;

# 0

The input_arguments_defined_list method returns the list of argument names found, using "input_arguments_defined", as an arrayref in scalar context, and as a list in list context.

input_arguments_defined_list() (arrayref)

{ since => '4.15', }

=example-1 input_arguments_defined_list

# given: synopsis

package main;

$cli->argument('args', {
  range => '0:',
  multiples => 1,
  type => 'string',
});

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

my $input_arguments_defined_list = $cli->input_arguments_defined_list;

# []

The input_option_count method returns the number of options provided to the CLI.

input_option_count() (number)

{ since => '4.15', }

=example-1 input_option_count

# given: synopsis

package main;

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

my $input_option_count = $cli->input_option_count;

# 2

The input_option_list method returns the list of option names as an arrayref in scalar context, and as a list in list context.

input_option_list() (arrayref)

{ since => '4.15', }

=example-1 input_option_list

# given: synopsis

package main;

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

my $input_option_list = $cli->input_option_list;

# ['input', 'output']

The input_options method returns the list of option names and values as a hashref.

input_options() (hashref)

{ since => '4.15', }

=example-1 input_options

# given: synopsis

package main;

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

my $input_options = $cli->input_options;

# {input => undef, output => undef}

The input_options_defined method returns the list of option names and values as a hashref, excluding undefined and empty arrayref values.

input_options_defined() (hashref)

{ since => '4.15', }

=example-1 input_options_defined

# given: synopsis

package main;

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

my $input_options_defined = $cli->input_options_defined;

# {}

The input_options_defined_count method returns the number of options found using "input_options_defined".

input_options_defined_count() (number)

{ since => '4.15', }

=example-1 input_options_defined_count

# given: synopsis

package main;

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

my $input_options_defined_count = $cli->input_options_defined_count;

# 0

The input_options_defined_list method returns the list of option names found, using "input_options_defined", as an arrayref in scalar context, and as a list in list context.

input_options_defined_list() (arrayref)

{ since => '4.15', }

=example-1 input_options_defined_list

# given: synopsis

package main;

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

my $input_options_defined_list = $cli->input_options_defined_list;

# []

The lines method takes a string of text, a maximum character length for each line, and an optional number of spaces to use for indentation (defaulting to 0). It returns the text formatted as a string where each line wraps at the specified length and is indented with the given number of spaces. The default lenght is 80.

lines(string $text, number $length, number $indent) (string)

{ since => '4.15', }

The log method returns a Venus::Log object passing "log_handler" and "log_level" to its constructor.

log() (Venus::Log)

{ since => '4.15', }

The log_debug method dispatches to the debug method on the object returned by "log".

log_debug(any @args) (Venus::Log)

{ since => '4.15', }

=example-1 log_debug

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $log_debug = $cli->log_debug('Example debug');

# bless(..., "Venus::Log")

The log_error method dispatches to the error method on the object returned by "log".

log_error(any @args) (Venus::Log)

{ since => '4.15', }

=example-1 log_error

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $log_error = $cli->log_error('Example error');

# bless(..., "Venus::Log")

The log_events method returns the log messages collected by the default "log_handler".

log_events() (arrayref)

{ since => '4.15', }

=example-1 log_events

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

$cli->log_debug('Example debug');

$cli->log_error('Example error');

my $log_events = $cli->log_events;

# [['debug', 'Example debug'], ['debug', 'Example error']]

The log_fatal method dispatches to the fatal method on the object returned by "log".

log_fatal(any @args) (Venus::Log)

{ since => '4.15', }

=example-1 log_fatal

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $log_fatal = $cli->log_fatal('Example fatal');

# bless(..., "Venus::Log")

The log_flush method dispatches to the method or callback provided for each "log event", then purges all log events.

log_flush(string | coderef $code) (Venus::Cli)

{ since => '4.15', }

=example-1 log_flush

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

$cli->log_debug('Example debug 1');

$cli->log_debug('Example debug 2');

my $log_flush = $cli->log_flush(sub{
  push @{$cli->{flushed} ||= []}, $_;
});

# bless(..., "Venus::Cli")

The log_handler method is passed to the Venus::Log constructor in "log" and by default handles log events by recording them to be "flushed" later.

log_handler() (coderef)

{ since => '4.15', }

=example-1 log_handler

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $log_handler = $cli->log_handler;

# sub{...}

The log_info method dispatches to the info method on the object returned by "log".

log_info(any @args) (Venus::Log)

{ since => '4.15', }

=example-1 log_info

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $log_info = $cli->log_info('Example info');

# bless(..., "Venus::Log")

The log_level method is passed to the Venus::Log constructor in "log" and by default specifies a log-level of debug.

log_level() (string)

{ since => '4.15', }

=example-1 log_level

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $log_level = $cli->log_level;

# "trace"

The log_trace method dispatches to the trace method on the object returned by "log".

log_trace(any @args) (Venus::Log)

{ since => '4.15', }

=example-1 log_trace

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $log_trace = $cli->log_trace('Example trace');

# bless(..., "Venus::Log")

The log_warn method dispatches to the warn method on the object returned by "log".

log_warn(any @args) (Venus::Log)

{ since => '4.15', }

=example-1 log_warn

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $log_warn = $cli->log_warn('Example warn');

# bless(..., "Venus::Log")

The multiple method is a configuration dispatcher and shorthand for {'multiples', true}. It returns the data or dispatches to the next configuration dispatcher based on the name provided and merges the configurations produced.

multiple(string $method, any @args) (any)

{ since => '4.15', }

The new method constructs an instance of the package.

new(any @args) (Venus::Cli)

{ since => '4.15', }

=example-1 new

package main;

use Venus::Cli;

my $cli = Venus::Cli->new('mycli');

# bless(..., "Venus::Cli")

# $cli->name;

# "mycli"

The no_input method returns true if no arguments or options are provided to the CLI, and false otherwise.

no_input() (boolean)

{ since => '4.15', }

=example-1 no_input

# given: synopsis

package main;

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

my $no_input = $cli->no_input;

# true

The no_input_arguments method returns true if no arguments are provided to the CLI, and false otherwise.

no_input_arguments() (boolean)

{ since => '4.15', }

=example-1 no_input_arguments

# given: synopsis

package main;

$cli->argument('args', {
  range => '0:',
  multiples => 1,
  type => 'string',
});

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

my $no_input_arguments = $cli->no_input_arguments;

# true

The no_input_options method returns true if no options are provided to the CLI, and false otherwise.

no_input_options() (boolean)

{ since => '4.15', }

=example-1 no_input_options

# given: synopsis

package main;

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

my $no_input_options = $cli->no_input_options;

# true

The no_output method returns true if no output events are found, and false otherwise.

no_output() (boolean)

{ since => '4.15', }

=example-1 no_output

# given: synopsis

package main;

my $no_output = $cli->no_output;

# true

The no_output_debug_events method returns true if no debug output events are found, and false otherwise.

no_output_debug_events() (boolean)

{ since => '4.15', }

=example-1 no_output_debug_events

# given: synopsis

package main;

$cli->log_info('example output');

my $no_output_debug_events = $cli->no_output_debug_events;

# true

The no_output_error_events method returns true if no error output events are found, and false otherwise.

no_output_error_events() (boolean)

{ since => '4.15', }

=example-1 no_output_error_events

# given: synopsis

package main;

$cli->log_info('example output');

my $no_output_error_events = $cli->no_output_error_events;

# true

The no_output_fatal_events method returns true if no fatal output events are found, and false otherwise.

no_output_fatal_events() (boolean)

{ since => '4.15', }

=example-1 no_output_fatal_events

# given: synopsis

package main;

$cli->log_info('example output');

my $no_output_fatal_events = $cli->no_output_fatal_events;

# true

The no_output_info_events method returns true if no info output events are found, and false otherwise.

no_output_info_events() (boolean)

{ since => '4.15', }

=example-1 no_output_info_events

# given: synopsis

package main;

$cli->log_info('example output');

my $no_output_info_events = $cli->no_output_info_events;

# false

The no_output_trace_events method returns true if no trace output events are found, and false otherwise.

no_output_trace_events() (boolean)

{ since => '4.15', }

=example-1 no_output_trace_events

# given: synopsis

package main;

$cli->log_info('example output');

my $no_output_trace_events = $cli->no_output_trace_events;

# true

The no_output_warn_events method returns true if no warn output events are found, and false otherwise.

no_output_warn_events() (boolean)

{ since => '4.15', }

=example-1 no_output_warn_events

# given: synopsis

package main;

$cli->log_info('example output');

my $no_output_warn_events = $cli->no_output_warn_events;

# true

The number method is a configuration dispatcher and shorthand for {'type', 'number'}. It returns the data or dispatches to the next configuration dispatcher based on the name provided and merges the configurations produced.

number(string $method, any @args) (any)

{ since => '4.15', }

The okay method terminates the program with a the exit code 0, indicating a successful exit. This method can be used to end the program explicitly, either after a specific task is completed or when an error occurs that requires halting execution. This method can dispatch to another method or callback before exiting.

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

{ since => '4.15', }

The option method registers and returns the configuration for the option specified. The method takes a name (option name) and a hashref of configuration values. The possible configuration values are as follows:

+=over 4

+=item *

The name key holds the name of the option.

+=item *

The label key holds the name of the option as it should be displayed in the CLI help text.

+=item *

The help key holds the help text specific to this option.

+=item *

The default key holds the default value that should used if no value for this option is provided to the CLI.

+=item *

The aliases (or alias) key holds the arrayref of aliases that can be provided to the CLI to specify a value (or values) for this option.

+=item *

The multiples key denotes whether this option can be used more than once, to collect multiple values, and holds a 1 if multiples are allowed and a 0 otherwise.

+=item *

The prompt key holds the question or statement that should be presented to the user of the CLI if no value has been provided for this option and no default value has been set.

+=item *

The range key holds a two-value arrayref where the first value is the starting index and the second value is the ending index. These values are used to select values from the parsed arguments array as the value(s) for this argument. This value is ignored if the multiples key is set to 0.

+=item *

The required key denotes whether this option is required or not, and holds a 1 if required and a 0 otherwise.

+=item *

The type key holds the data type of the option expected. Valid values are "number", "string", "float", "boolean", or "yesno". Note: Valid boolean values are 1, 0, "true", and "false".

+=item *

The wants key holds the text to be used as a value being assigned to the option in the usage text. This value defaults to the type specified, or "string".

+=back

option(string $name, hashref $data) (maybe[hashref])

{ since => '4.15', }

The option_aliases method returns the aliases configuration value for the named option.

option_aliases(string $name) (arrayref)

{ since => '4.15', }

=example-1 option_aliases

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $option_aliases = $cli->option_aliases;

# []

The option_count method returns the count of registered options.

option_count() (number)

{ since => '4.15', }

=example-1 option_count

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $option_count = $cli->option_count;

# 0

The option_default method returns the default configuration value for the named option.

option_default(string $name) (string)

{ since => '4.15', }

=example-1 option_default

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $option_default = $cli->option_default;

# ""

The option_errors method returns a list of "issues", if any, for each value returned by "option_value" for the named option. Returns a list in list context.

option_errors(string $name) (within[arrayref, Venus::Validate])

{ since => '4.15', }

=example-1 option_errors

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $option_errors = $cli->option_errors;

# []

The option_help method returns the help configuration value for the named option.

option_help(string $name) (string)

{ since => '4.15', }

=example-1 option_help

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $option_help = $cli->option_help;

# ""

The option_label method returns the label configuration value for the named option.

option_label(string $name) (string)

{ since => '4.15', }

=example-1 option_label

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $option_label = $cli->option_label;

# ""

The option_list method returns a list of registered option configurations. Returns a list in list context.

option_list(string $name) (within[arrayref, hashref])

{ since => '4.15', }

=example-1 option_list

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $option_list = $cli->option_list;

# []

The option_multiples method returns the multiples configuration value for the named option.

option_multiples(string $name) (boolean)

{ since => '4.15', }

=example-1 option_multiples

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $option_multiples = $cli->option_multiples;

# false

The option_name method returns the name configuration value for the named option.

option_name(string $name) (string)

{ since => '4.15', }

=example-1 option_name

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $option_name = $cli->option_name;

# ""

The option_names method returns the names (keys) of registered options in the order declared. Returns a list in list context.

option_names(string $name) (within[arrayref, string])

{ since => '4.15', }

=example-1 option_names

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $option_names = $cli->option_names;

# []

The option_prompt method returns the prompt configuration value for the named option.

option_prompt(string $name) (string)

{ since => '4.15', }

=example-1 option_prompt

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $option_prompt = $cli->option_prompt;

# ""

The option_range method returns the range configuration value for the named option.

option_range(string $name) (string)

{ since => '4.15', }

=example-1 option_range

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $option_range = $cli->option_range;

# ""

The option_required method returns the required configuration value for the named option.

option_required(string $name) (boolean)

{ since => '4.15', }

=example-1 option_required

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $option_required = $cli->option_required;

# false

The option_type method returns the type configuration value for the named option. Valid values are as follows:

+=over 4

+=item *

number

+=item *

string

+=item *

float

+=item *

boolean - Note: Valid boolean values are 1, 0, "true", and "false".

+=item *

yesno

+=back

option_type(string $name) (string)

{ since => '4.15', }

=example-1 option_type

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $option_type = $cli->option_type;

# ""

The option_validate method returns a Venus::Validate object for each value returned by "option_value" for the named option. Returns a list in list context.

option_validate(string $name) (Venus::Validate | within[arrayref, Venus::Validate])

{ since => '4.15', }

=example-1 option_validate

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $option_validate = $cli->option_validate;

# []

The option_value method returns the parsed option value for the named option.

option_value(string $name) (any)

{ since => '4.15', }

=example-1 option_value

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $option_value = $cli->option_value;

# undef

The option_wants method returns the wants configuration value for the named option.

option_wants(string $name) (string)

{ since => '4.15', }

=example-1 option_wants

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $option_wants = $cli->option_wants;

# ""

The optional method is a configuration dispatcher and shorthand for {'required', false}. It returns the data or dispatches to the next configuration dispatcher based on the name provided and merges the configurations produced.

optional(string $method, any @args) (any)

{ since => '4.15', }

The opts method returns the list of parsed command-line options as a Venus::Opts object.

opts() (Venus::Opts)

{ since => '4.15', }

=example-1 opts

# given: synopsis

package main;

my $opts = $cli->opts;

# bless(..., "Venus::Opts")

The output method returns the list of output events as an arrayref in scalar context, and a list in list context. The method optionally takes a log-level and if provided will only return output events for that log-level.

output(string $level) (any)

{ since => '4.15', }

=example-1 output

# given: synopsis

package main;

my $output = $cli->output;

# undef

The output_debug_events method returns the list of debug output events as an arrayref in scalar context, and a list in list context.

output_debug_events() (arrayref)

{ since => '4.15', }

=example-1 output_debug_events

# given: synopsis

package main;

$cli->log_info('example output');

my $output_debug_events = $cli->output_debug_events;

# []

The output_error_events method returns the list of error output events as an arrayref in scalar context, and a list in list context.

output_error_events() (arrayref)

{ since => '4.15', }

=example-1 output_error_events

# given: synopsis

package main;

$cli->log_info('example output');

my $output_error_events = $cli->output_error_events;

# []

The output_fatal_events method returns the list of fatal output events as an arrayref in scalar context, and a list in list context.

output_fatal_events() (arrayref)

{ since => '4.15', }

=example-1 output_fatal_events

# given: synopsis

package main;

$cli->log_info('example output');

my $output_fatal_events = $cli->output_fatal_events;

# []

The output_info_events method returns the list of info output events as an arrayref in scalar context, and a list in list context.

output_info_events() (arrayref)

{ since => '4.15', }

=example-1 output_info_events

# given: synopsis

package main;

$cli->log_warn('example output');

my $output_info_events = $cli->output_info_events;

# []

The output_trace_events method returns the list of trace output events as an arrayref in scalar context, and a list in list context.

output_trace_events() (arrayref)

{ since => '4.15', }

=example-1 output_trace_events

# given: synopsis

package main;

$cli->log_info('example output');

my $output_trace_events = $cli->output_trace_events;

# []

The output_warn_events method returns the list of warn output events as an arrayref in scalar context, and a list in list context.

output_warn_events() (arrayref)

{ since => '4.15', }

=example-1 output_warn_events

# given: synopsis

package main;

$cli->log_info('example output');

my $output_warn_events = $cli->output_warn_events;

# []

The parse method accepts arbitrary input (typically strings or arrayrefs of strings) and parses out the arguments and options made available via "parsed_arguments" and "parsed_options" respectively. If no arguments are provided @ARGV is used as a default.

parse(any @args) (Venus::Cli)

{ since => '4.15', }

=example-1 parse

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $parse = $cli->parse;

# bless(..., "Venus::Cli")

# $cli->parsed_arguments

# []

# $result->parsed_options

# {}

The parsed method is shorthand for calling the "parsed_arguments" and/or "parsed_options" method directly. In scalar context this method returns "parsed_options". In list context returns "parsed_options" and "parsed_arguments" in that order.

parsed() (arrayref | hashref)

{ since => '4.15', }

=example-1 parsed

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $parsed = $cli->parsed;

# {}

The parsed_arguments method gets or sets the set of parsed arguments. This method calls "parse" if no data has been set.

parsed_arguments(arrayref $data) (arrayref)

{ since => '4.15', }

=example-1 parsed_arguments

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

$cli->argument('extra', {
  range => '0:',
  type => 'string',
});

local @ARGV = qw(--input stdin --output stdout hello world);

my $parsed_arguments = $cli->parsed_arguments;

# ['hello', 'world']

The parsed_options method method gets or sets the set of parsed options. This method calls "parse" if no data has been set.

parsed_options(hashref $data) (hashref)

{ since => '4.15', }

=example-1 parsed_options

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

$cli->argument('extra', {
  range => '0:',
  type => 'string',
});

local @ARGV = qw(--input stdin --output stdout hello world);

my $parsed_options = $cli->parsed_options;

# {input => 'stdin', output => 'stdout'}

The pass method terminates the program with a the exit code 0, indicating a successful exit. This method can be used to end the program explicitly, either after a specific task is completed or when an error occurs that requires halting execution. This method can dispatch to another method or callback before exiting.

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

{ since => '4.15', }

The reorder method re-indexes the "arguments", "choices", and "options", based on the order they were declared.

reorder() (Venus::Cli)

{ since => '4.15', }

=example-1 reorder

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

$cli->argument('input', {
  type => 'string',
  index => 1,
});

$cli->argument('output', {
  type => 'string',
  index => 3,
});

$cli->option('file', {
  type => 'string',
  index => 1,
});

$cli->option('directory', {
  type => 'string',
  index => 3,
});

$cli->choice('stdin', {
  argument => 'input',
  type => 'string',
  index => 1,
});

$cli->choice('stdout', {
  argument => 'output',
  type => 'string',
  index => 3,
});

my $reorder = $cli->reorder;

# bless(..., "Venus::Cli")

The reorder_arguments method re-indexes the "arguments" based on the order they were declared.

reorder_arguments() (Venus::Cli)

{ since => '4.15', }

=example-1 reorder_arguments

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

$cli->argument('input', {
  type => 'string',
  index => 1,
});

$cli->argument('output', {
  type => 'string',
  index => 3,
});

my $reorder_arguments = $cli->reorder_arguments;

# bless(..., "Venus::Cli")

The reorder_choices method re-indexes the "choices" based on the order they were declared.

reorder_choices() (Venus::Cli)

{ since => '4.15', }

=example-1 reorder_choices

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

$cli->argument('input', {
  type => 'string',
  index => 1,
});

$cli->argument('output', {
  type => 'string',
  index => 3,
});

$cli->choice('stdin', {
  argument => 'input',
  type => 'string',
  index => 1,
});

$cli->choice('stdout', {
  argument => 'output',
  type => 'string',
  index => 3,
});

my $reorder_choices = $cli->reorder_choices;

# bless(..., "Venus::Cli")

The reorder_options method re-indexes the "options" based on the order they were declared.

reorder_options() (Venus::Cli)

{ since => '4.15', }

=example-1 reorder_options

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

$cli->option('file', {
  type => 'string',
  index => 1,
});

$cli->option('directory', {
  type => 'string',
  index => 3,
});

my $reorder_options = $cli->reorder_options;

# bless(..., "Venus::Cli")

The reorder_routes method reorders the registered routes based on their indices. This method returns the invocant.

reorder_routes() (Venus::Cli)

{ since => '4.15', }

=example-1 reorder_routes

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

$cli->route('user create', {
  handler => 'handle_user_create',
  index => 1,
});

$cli->route('user delete', {
  handler => 'handle_user_delete',
  index => 0,
});

my $reorder_routes = $cli->reorder_routes;

# bless(..., "Venus::Cli")

The route method registers and returns the configuration for the route specified. The method takes a name (route name) and a hashref of configuration values. The possible configuration values are as follows:

+=over 4

+=item *

The name key holds the name of the route.

+=item *

The label key holds the name of the route as it should be displayed in the CLI help text.

+=item *

The help key holds the help text specific to this route.

+=item *

The argument key holds the name of the argument that this route is associated with.

+=item *

The choice key holds the name of the choice that this route is associated with.

+=item *

The handler key holds the (local) method name, or Venus::Cli derived package, or coderef to execute when this route is matched.

+=item *

The range key holds the range specification for the argument.

+=item *

The wants key holds the text to be used as a value placeholder in the CLI help text.

+=back

route(string $name, hashref $data) (maybe[hashref])

{ since => '4.15', }

=example-1 route

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $route = $cli->route('user create');

# undef

The route_argument method returns the argument configuration for the named route.

route_argument(string $name) (maybe[hashref])

{ since => '4.15', }

=example-1 route_argument

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $route_argument = $cli->route_argument;

# ""

The route_choice method returns the choice configuration for the named route.

route_choice(string $name) (maybe[hashref])

{ since => '4.15', }

=example-1 route_choice

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $route_choice = $cli->route_choice;

# ""

The route_count method returns the number of registered routes.

route_count() (number)

{ since => '4.15', }

=example-1 route_count

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $route_count = $cli->route_count;

# 0

The route_handler method returns the handler for the named route.

route_handler(string $name) (maybe[string | coderef])

{ since => '4.15', }

=example-1 route_handler

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $route_handler = $cli->route_handler;

# undef

The route_help method returns the help text for the named route.

route_help(string $name) (string)

{ since => '4.15', }

=example-1 route_help

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $route_help = $cli->route_help;

# ""

The route_label method returns the label for the named route.

route_label(string $name) (string)

{ since => '4.15', }

=example-1 route_label

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $route_label = $cli->route_label;

# ""

The route_list method returns a list of all registered route configurations in insertion order.

route_list() (arrayref[hashref])

{ since => '4.15', }

=example-1 route_list

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $route_list = $cli->route_list;

# []

The route_name method returns the name of the named route.

route_name(string $name) (string)

{ since => '4.15', }

=example-1 route_name

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $route_name = $cli->route_name;

# ""

The route_names method returns a list of all registered route names in insertion order.

route_names() (arrayref[string])

{ since => '4.15', }

=example-1 route_names

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $route_names = $cli->route_names;

# []

The route_range method returns the range for the named route.

route_range(string $name) (string)

{ since => '4.15', }

=example-1 route_range

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $route_range = $cli->route_range;

# ""

The required method is a configuration dispatcher and shorthand for {'required', true}. It returns the data or dispatches to the next configuration dispatcher based on the name provided and merges the configurations produced.

required(string $method, any @args) (any)

{ since => '4.15', }

The reset method clears the argument and option configurations, cached parsed values, and returns the invocant.

reset() (Venus::Cli)

{ since => '4.15', }

=example-1 reset

# given: synopsis

package main;

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

my $reset = $cli->reset;

# bless(..., "Venus::Cli")

The single method is a configuration dispatcher and shorthand for {'multiples', false}. It returns the data or dispatches to the next configuration dispatcher based on the name provided and merges the configurations produced.

single(string $method, any @args) (any)

{ since => '4.15', }

The spec method configures the CLI instance from a hashref specification. It accepts a hashref containing any of the following keys: name, version, summary, description, header, footer, arguments, options, choices, routes, and commands. The method returns the invocant.

spec(hashref $data) (Venus::Cli)

{ since => '4.15', }

=example-1 spec

package main;

use Venus::Cli;

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

my $spec = $cli->spec;

# bless(..., "Venus::Cli")

The string method is a configuration dispatcher and shorthand for {'type', 'string'}. It returns the data or dispatches to the next configuration dispatcher based on the name provided and merges the configurations produced.

string(string $method, any @args) (any)

{ since => '4.15', }

The usage method provides the command-line usage information for the CLI. It outputs details such as available choices, arguments, options, and a general summary of how to use the CLI. This method is useful for users needing guidance on the various arguments, options, and choices available, and how they work.

usage() (string)

{ since => '4.15', }

=example-1 usage

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $usage = $cli->usage;

# "Usage: mycli"

The usage_argument_default method renders the default configuration value for the named argument for use in the CLI "usage" text.

usage_argument_default(string $name) (string)

{ since => '4.15', }

=example-1 usage_argument_default

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $usage_argument_default = $cli->usage_argument_default;

# ""

The usage_argument_help method renders the help configuration value for the named argument for use in the CLI "usage" text.

usage_argument_help(string $name) (string)

{ since => '4.15', }

=example-1 usage_argument_help

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $usage_argument_help = $cli->usage_argument_help;

# ""

The usage_argument_label method renders the label configuration value for the named argument for use in the CLI "usage" text.

usage_argument_label(string $name) (string)

{ since => '4.15', }

=example-1 usage_argument_label

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $usage_argument_label = $cli->usage_argument_label;

# ""

The usage_argument_required method renders the required configuration value for the named argument for use in the CLI "usage" text.

usage_argument_required(string $name) (string)

{ since => '4.15', }

=example-1 usage_argument_required

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $usage_argument_required = $cli->usage_argument_required;

# "(optional)"

The usage_argument_token method renders the token configuration value for the named argument for use in the CLI "usage" text.

usage_argument_token(string $name) (string)

{ since => '4.15', }

=example-1 usage_argument_token

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $usage_argument_token = $cli->usage_argument_token;

# ""

The usage_arguments method renders all registered arguments for use in the CLI "usage" text.

usage_arguments() (string)

{ since => '4.15', }

=example-1 usage_arguments

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

$cli->argument('input', {
  type => 'string',
});

$cli->argument('output', {
  type => 'string',
});

my $usage_arguments = $cli->usage_arguments;

# Arguments:
#   [<input>]
#     Expects a string value
#     (optional)
#   [<output>]
#     Expects a string value
#     (optional)

The usage_choice_help method renders the help configuration value for the named choice for use in the CLI "usage" text.

usage_choice_help(string $name) (string)

{ since => '4.15', }

=example-1 usage_choice_help

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $usage_choice_help = $cli->usage_choice_help;

# ""

The usage_choice_label method renders the label configuration value for the named choice for use in the CLI "usage" text.

usage_choice_label(string $name) (string)

{ since => '4.15', }

=example-1 usage_choice_label

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $usage_choice_label = $cli->usage_choice_label;

# ""

The usage_choice_required method renders the required configuration value for the named choice for use in the CLI "usage" text.

usage_choice_required(string $name) (string)

{ since => '4.15', }

=example-1 usage_choice_required

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $usage_choice_required = $cli->usage_choice_required;

# ""

The usage_choices method renders all registered choices for use in the CLI "usage" text.

usage_choices() (string)

{ since => '4.15', }

=example-1 usage_choices

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

$cli->argument('input', {
  type => 'string',
});

$cli->choice('stdin', {
  argument => 'input',
});

$cli->argument('output', {
  type => 'string',
});

$cli->choice('stdout', {
  argument => 'output',
});

my $usage_choices = $cli->usage_choices;

# Choices for [<input>]:
#   stdin
#     Expects a string value
#     [<input>]
#
# Choices for [<output>]:
#   stdout
#     Expects a string value
#     [<output>]

The usage_description method renders the description for use in the CLI "usage" text.

usage_description() (string)

{ since => '4.15', }

=example-1 usage_description

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $description = $cli->description('Example description');

my $usage_description = $cli->usage_description;

# "Example description"

The usage_footer method renders the footer for use in the CLI "usage" text.

usage_footer() (string)

{ since => '4.15', }

=example-1 usage_footer

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $footer = $cli->footer('Example footer');

my $usage_footer = $cli->usage_footer;

# "Example footer"

The usage_gist method renders the CLI top-line describing the name, version, and/or summary.

usage_gist() (string)

{ since => '4.15', }

=example-1 usage_gist

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $usage_gist = $cli->usage_gist;

# ""

The usage_header method renders the header for use in the CLI "usage" text.

usage_header() (string)

{ since => '4.15', }

=example-1 usage_header

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $header = $cli->header('Example header');

my $usage_header = $cli->usage_header;

# "Example header"

The usage_line method renders the CLI usage line for use in the CLI "usage" text.

usage_line() (string)

{ since => '4.15', }

=example-1 usage_line

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $usage_line = $cli->usage_line;

# "Usage: mycli"

The usage_name method renders the CLI name for use in the CLI "usage" text.

usage_name() (string)

{ since => '4.15', }

=example-1 usage_name

package main;

use Venus::Cli;

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

my $usage_name = $cli->usage_name;

# ""

The usage_option_default method renders the default configuration value for the named option for use in the CLI "usage" text.

usage_option_default(string $name) (string)

{ since => '4.15', }

=example-1 usage_option_default

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $usage_option_default = $cli->usage_option_default;

# ""

The usage_option_help method renders the help configuration value for the named option for use in the CLI "usage" text.

usage_option_help(string $name) (string)

{ since => '4.15', }

=example-1 usage_option_help

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $usage_option_help = $cli->usage_option_help;

# ""

The usage_option_label method renders the label configuration value for the named option for use in the CLI "usage" text.

usage_option_label(string $name) (string)

{ since => '4.15', }

=example-1 usage_option_label

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $usage_option_label = $cli->usage_option_label;

# ""

The usage_option_required method renders the required configuration value for the named option for use in the CLI "usage" text.

usage_option_required(string $name) (string)

{ since => '4.15', }

=example-1 usage_option_required

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $usage_option_required = $cli->usage_option_required;

# "(optional)"

The usage_option_token method renders the token configuration value for the named option for use in the CLI "usage" text.

usage_option_token(string $name) (string)

{ since => '4.15', }

=example-1 usage_option_token

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $usage_option_token = $cli->usage_option_token;

# ""

The usage_options method renders all registered options for use in the CLI "usage" text.

usage_options() (string)

{ since => '4.15', }

=example-1 usage_options

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

$cli->option('input', {
  type => 'string',
});

$cli->option('output', {
  type => 'string',
});

my $usage_options = $cli->usage_options;

# Options:
#   [--input=<string>]
#     Expects a string value
#     (optional)
#   [--output=<string>]
#     Expects a string value
#     (optional)

The usage_summary method renders the summary for use in the CLI "usage" text.

usage_summary() (string)

{ since => '4.15', }

=example-1 usage_summary

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $summary = $cli->summary('Example summary');

my $usage_summary = $cli->usage_summary;

# "Example summary"

The usage_version method renders the description for use in the CLI "usage" text.

usage_version() (string)

{ since => '4.15', }

=example-1 usage_version

package main;

use Venus::Cli;

my $cli = Venus::Cli->new(name => 'mycli');

my $version = $cli->version('0.0.1');

my $usage_version = $cli->usage_version;

# "0.0.1"

The vars method returns the list of parsed command-line options as a Venus::Vars object.

vars() (Venus::Vars)

{ since => '4.15', }

=example-1 vars

# given: synopsis

package main;

my $vars = $cli->vars;

# bless(..., "Venus::Vars")

The yesno method is a configuration dispatcher and shorthand for {'type', 'yesno'}. It returns the data or dispatches to the next configuration dispatcher based on the name provided and merges the configurations produced.

yesno(string $method, any @args) (any)

{ since => '4.15', }

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

cpanm Venus

perl -MCPAN -e shell
install Venus