NAME

Venus::Cli - Cli Class

ABSTRACT

Cli Class for Perl 5

SYNOPSIS

  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}

DESCRIPTION

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

ATTRIBUTES

This package has the following attributes:

data

  data(arrayref $data) (arrayref)

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

Since 2.55

data example 1

  # given: synopsis
  package main;
  my $data = $cli->data([]);
  # []

INHERITS

This package inherits behaviors from:

Venus::Kind::Utility

INTEGRATES

This package integrates behaviors from:

Venus::Role::Stashable

METHODS

This package provides the following methods:

arg

  arg(string $name) (any)

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

Since 2.55

arg example 1

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new(['example', '--help']);
  my $name = $cli->arg('name');
  # undef

arg example 2

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new(['example', '--help']);
  $cli->set('arg', 'name', {
    range => '0',
  });
  my $name = $cli->arg('name');
  # ["example"]

arg example 3

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new(['example', '--help']);
  $cli->set('arg', 'name', {
    range => '0',
  });
  my ($name) = $cli->arg('name');
  # "example"

arg example 4

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new(['--help']);
  $cli->set('arg', 'name', {
    prompt => 'Enter a name',
    range => '0',
  });
  my ($name) = $cli->arg('name');
  # prompts for name, e.g.
  # > name: Enter a name
  # > example
  # "example"

arg example 5

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new(['--help']);
  $cli->set('arg', 'name', {
    default => 'example',
    range => '0',
  });
  my ($name) = $cli->arg('name');
  # "example"

arg example 6

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new(['example', '--help']);
  $cli->set('arg', 'name', {
    type => 'string',
    range => '0',
  });
  my ($name) = $cli->arg('name');
  # "example"

cmd

  cmd(string $name) (any)

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.

Since 2.55

cmd example 1

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new(['example', 'execute']);
  my $name = $cli->cmd('name');
  # undef

cmd example 2

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new(['example', 'execute']);
  $cli->set('arg', 'action', {
    range => '1',
  });
  $cli->set('cmd', 'execute', {
    arg => 'action',
  });
  my $is_execute = $cli->cmd('execute');
  # 1

cmd example 3

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new(['example', 'execute']);
  $cli->set('arg', 'action', {
    range => '1',
  });
  $cli->set('cmd', 'execute', {
    arg => 'action',
  });
  my ($is_execute) = $cli->cmd('execute');
  # 1

cmd example 4

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new(['example']);
  $cli->set('arg', 'action', {
    prompt => 'Enter the desired action',
    range => '1',
  });
  $cli->set('cmd', 'execute', {
    arg => 'action',
  });
  my ($is_execute) = $cli->cmd('execute');
  # prompts for action, e.g.
  # > name: Enter the desired action
  # > execute
  # 1

cmd example 5

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new(['example']);
  $cli->set('arg', 'action', {
    default => 'execute',
    range => '1',
  });
  $cli->set('cmd', 'execute', {
    arg => 'action',
  });
  my ($is_execute) = $cli->cmd('execute');
  # 1

cmd example 6

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new(['example', 'execute']);
  $cli->set('arg', 'action', {
    type => 'string',
    range => '1',
  });
  $cli->set('cmd', 'execute', {
    arg => 'action',
  });
  my ($is_execute) = $cli->cmd('execute');
  # 1

cmd example 7

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new(['example']);
  $cli->set('arg', 'action', {
    type => 'string',
    range => '1',
  });
  $cli->set('cmd', 'execute', {
    arg => 'action',
  });
  my ($is_execute) = $cli->cmd('execute');
  # 0

exit

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

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.

Since 2.55

exit example 1

  # given: synopsis
  package main;
  my $exit = $cli->exit;
  # ()

exit example 2

  # given: synopsis
  package main;
  my $exit = $cli->exit(0);
  # ()

exit example 3

  # given: synopsis
  package main;
  my $exit = $cli->exit(1);
  # ()

exit example 4

  # given: synopsis
  package main;
  my $exit = $cli->exit(1, 'stash', 'executed', 1);
  # ()

fail

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

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.

Since 2.55

fail example 1

  # given: synopsis
  package main;
  my $fail = $cli->fail;
  # ()

fail example 2

  # given: synopsis
  package main;
  my $fail = $cli->fail('stash', 'executed', 1);
  # ()

get

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

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

Since 2.55

get example 1

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new;
  my $get = $cli->get;
  # undef

get example 2

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new;
  my $get = $cli->get('opt', 'help');
  # undef

get example 3

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new;
  $cli->set('opt', 'help', {
    alias => 'h',
  });
  my $get = $cli->get('opt', 'help');
  # {name => 'help', alias => 'h'}

get example 4

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new;
  $cli->set('opt', 'help', {
    alias => 'h',
  });
  my $get = $cli->get('opt');
  # {help => {name => 'help', alias => 'h'}}

help

  help() (string)

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

Since 2.55

help example 1

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new;
  my $help = $cli->help;
  # "Usage: application"

help example 2

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new;
  $cli->set('str', 'name', 'program');
  my $help = $cli->help;
  # "Usage: program"

help example 3

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new;
  $cli->set('str', 'name', 'program');
  $cli->set('arg', 'command', {
    help => 'Command to execute',
  });
  my $help = $cli->help;
  # "Usage: program [<argument>]
  #
  # Arguments:
  #
  #   command
  #     Command to execute
  #     (optional)"

help example 4

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new;
  $cli->set('str', 'name', 'program');
  $cli->set('arg', 'command', {
    help => 'Command to execute',
    required => 1
  });
  my $help = $cli->help;
  # "Usage: program <argument>
  #
  # Arguments:
  #
  #   command
  #     Command to execute
  #     (required)"

help example 5

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new;
  $cli->set('str', 'name', 'program');
  $cli->set('arg', 'command', {
    help => 'Command to execute',
    type => 'string',
    required => 1,
  });
  my $help = $cli->help;
  # "Usage: program <argument>
  #
  # Arguments:
  #
  #   command
  #     Command to execute
  #     (required)
  #     (string)"

help example 6

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new;
  $cli->set('str', 'name', 'program');
  $cli->set('arg', 'command', {
    help => 'Command to execute',
    required => 1,
  });
  $cli->set('cmd', 'create', {
    help => 'Create new resource',
    arg => 'command',
  });
  my $help = $cli->help;
  # "Usage: program <argument>
  #
  # Arguments:
  #
  #   command
  #     Command to execute
  #     (required)
  #
  # Commands:
  #
  #   create
  #     Create new resource
  #     (ccommand)"

help example 7

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new;
  $cli->set('str', 'name', 'program');
  $cli->set('arg', 'command', {
    help => 'Command to execute',
    required => 1,
  });
  $cli->set('opt', 'help', {
    help => 'Show help information',
    alias => ['?', 'h'],
  });
  $cli->set('cmd', 'create', {
    help => 'Create new resource',
    arg => 'command',
  });
  my $help = $cli->help;
  # "Usage: program <argument> [<option>]
  #
  # Arguments:
  #
  #   command
  #     Command to execute
  #     (required)
  #
  # Options:
  #
  #   -?, -h, --help
  #     Show help information
  #     (optional)
  #
  # Commands:
  #
  #   create
  #     Create new resource
  #     (command)"

help example 8

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new;
  $cli->set('str', 'name', 'program');
  $cli->set('arg', 'files', {
    help => 'File paths',
    required => 1,
    range => '0:',
  });
  $cli->set('opt', 'verbose', {
    help => 'Show details during processing',
    alias => ['v'],
  });
  my $help = $cli->help;
  # "Usage: program <argument>, ... [<option>]
  #
  # Arguments:
  #
  #   files, ...
  #     File paths
  #     (required)
  #
  # Options:
  #
  #   -v, --verbose
  #     Show details during processing
  #     (optional)"

okay

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

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.

Since 2.55

okay example 1

  # given: synopsis
  package main;
  my $okay = $cli->okay;
  # ()

okay example 2

  # given: synopsis
  package main;
  my $okay = $cli->okay('stash', 'executed', 1);
  # ()

opt

  opt(string $name) (any)

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

Since 2.55

opt example 1

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new(['example', '--help']);
  my $name = $cli->opt('help');
  # undef

opt example 2

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new(['example', '--help']);
  $cli->set('opt', 'help', {});
  my $name = $cli->opt('help');
  # [1]

opt example 3

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new(['example', '--help']);
  $cli->set('opt', 'help', {});
  my ($name) = $cli->opt('help');
  # 1

opt example 4

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new([]);
  $cli->set('opt', 'name', {
    prompt => 'Enter a name',
    type => 'string',
    multi => 0,
  });
  my ($name) = $cli->opt('name');
  # prompts for name, e.g.
  # > name: Enter a name
  # > example
  # "example"

opt example 5

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new(['--name', 'example']);
  $cli->set('opt', 'name', {
    prompt => 'Enter a name',
    type => 'string',
    multi => 0,
  });
  my ($name) = $cli->opt('name');
  # Does not prompt
  # "example"

opt example 6

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new(['example', '--name', 'example', '--name', 'example']);
  $cli->set('opt', 'name', {
    type => 'string',
    multi => 1,
  });
  my (@name) = $cli->opt('name');
  # ("example", "example")

parsed

  parsed() (hashref)

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

Since 2.55

parsed example 1

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new(['example', '--help']);
  $cli->set('arg', 'name', {
    range => '0',
  });
  $cli->set('opt', 'help', {
    alias => 'h',
  });
  my $parsed = $cli->parsed;
  # {name => "example", help => 1}

parser

  parser() (Venus::Opts)

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

Since 2.55

parser example 1

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new;
  $cli->set('opt', 'help', {
    help => 'Show help information',
    alias => 'h',
  });
  my $parser = $cli->parser;
  # bless({...}, 'Venus::Opts')

pass

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

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.

Since 3.10

pass example 1

  # given: synopsis
  package main;
  my $pass = $cli->pass;
  # ()

pass example 2

  # given: synopsis
  package main;
  my $pass = $cli->pass('stash', 'executed', 1);
  # ()

set

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

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:

The "default" property specifies the "default" value to be used if none is provided.
The "help" property specifies the help text to output in usage instructions.
The "label" property specifies the label text to output in usage instructions.
The "name" property specifies the name of the argument.
The "prompt" property specifies the text to be used in a prompt for input if no value is provided.
The "range" property specifies the zero-indexed position where the CLI arguments can be found, using range notation.
The "required" property specifies whether the argument is required and throws an exception is missing when fetched.
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".

The following are configurable "cmd" properties:

The "arg" property specifies the CLI argument where the command can be found.
The "help" property specifies the help text to output in usage instructions.
The "label" property specifies the label text to output in usage instructions.
The "name" property specifies the name of the command.

The following are configurable "opt" properties:

The "alias" property specifies the alternate identifiers that can be provided.
The "default" property specifies the "default" value to be used if none is provided.
The "help" property specifies the help text to output in usage instructions.
The "label" property specifies the label text to output in usage instructions.
The "multi" property denotes whether the CLI will accept multiple occurrences of the option.
The "name" property specifies the name of the option.
The "prompt" property specifies the text to be used in a prompt for input if no value is provided.
The "required" property specifies whether the option is required and throws an exception is missing when fetched.
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".

Since 2.55

set example 1

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new;
  my $set = $cli->set;
  # undef

set example 2

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new;
  my $set = $cli->set('opt', 'help');
  # bless({...}, 'Venus::Cli')

set example 3

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new;
  my $set = $cli->set('opt', 'help', {
    alias => 'h',
  });
  # bless({...}, 'Venus::Cli')

set example 4

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new;
  my $set = $cli->set('opt', 'help', {
    alias => ['?', 'h'],
  });
  # bless({...}, 'Venus::Cli')

str

  str(string $name) (any)

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.

Since 2.55

str example 1

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new;
  $cli->set('str', 'name', 'program');
  my $str = $cli->str('name');
  # "program"

test

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

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.

Since 3.10

test example 1

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new(['help']);
  $cli->set('arg', 'name', {
    type => 'string',
    range => '0',
  });
  my ($name) = $cli->test('arg', 'name');
  # "help"

test example 2

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new(['--help']);
  $cli->set('arg', 'name', {
    type => 'string',
    range => '0',
  });
  my ($name) = $cli->test('arg', 'name');
  # Exception! (isa Venus::Cli::Error) (see error_on_arg_validation)
  # Invalid argument: name: received (undef), expected (string)

test example 3

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new(['example', '--name', 'example']);
  $cli->set('opt', 'name', {
    type => 'string',
    multi => 1,
  });
  my ($name) = $cli->test('opt', 'name');
  # "example"

test example 4

  package main;
  use Venus::Cli;
  my $cli = Venus::Cli->new(['example', '--name', 'example']);
  $cli->set('opt', 'name', {
    type => 'number',
    multi => 1,
  });
  my ($name) = $cli->test('opt', 'name');
  # Exception! (isa Venus::Cli::Error) (see error_on_opt_validation)
  # Invalid option: name: received (undef), expected (number)

ERRORS

This package may raise the following errors:

error: "error_on_arg_validation"

This package may raise an error_on_arg_validation exception.

example 1

  # given: synopsis;
  my $input = {
    throw => 'error_on_arg_validation',
    error => "...",
    name => "example",
    type => "string",
  };
  my $error = $cli->catch('error', $input);
  # my $name = $error->name;
  # "on_arg_validation"
  # my $message = $error->render;
  # "Invalid argument: example: ..."
  # my $name = $error->stash('name');
  # "example"
  # my $type = $error->stash('type');
  # "string"

error: "error_on_opt_validation"

This package may raise an error_on_opt_validation exception.

example 1

  # given: synopsis;
  my $input = {
    throw => 'error_on_opt_validation',
    error => "...",
    name => "example",
    type => "string",
  };
  my $error = $cli->catch('error', $input);
  # my $name = $error->name;
  # "on_opt_validation"
  # my $message = $error->render;
  # "Invalid option: example: ..."
  # my $name = $error->stash('name');
  # "example"
  # my $type = $error->stash('type');
  # "string"

AUTHORS

Awncorp, "awncorp@cpan.org"

LICENSE

This program is free software, you can redistribute it and/or modify it under the terms of the Apache license version 2.0.