/ 
Mnet-5.25
River stage zero No dependents
/ Mnet::Opts::Cli

NAME

Mnet::Opts::Cli - Define and parse command line options

SYNOPSIS

# required to use this module
use Mnet::Opts::Cli;

# define --sample cli option
Mnet::Opts::Cli::define({
    getopt      => "sample=s",
    default     => "",
    help_tip    => "set to input string",
    help_text   => "
        use --sample to set an input string
        refer to perldoc for more information
    ",
});

# optional environment variable can also be parsed for options
my $env = "Mnet";

# call in list context for cli opts object and any extra args
my ($cli, @extras) = Mnet::Opts::Cli->new($env);

# call in scalar context to disallow extra args
$cli = Mnet::Opts::Cli->new($env);

# access parsed cli options using method calls
my $value = $cli->sample;

DESCRIPTIONS

Mnet::Opts::Cli can be used by scripts to define and parse command line options, as shown in the example above.

An optional environment variable can be used to set options, as shown in the example above. This can be to secure passwords so they don't appear in system process table, as below:

export Mnet="--password secret"
script.pl

Note that the specified environment variable is not parsed if the --test option is set on the command line. Refer to Mnet::Test for more information.

METHODS

Mnet::Opts::Cli implements the methods listed below.

Mnet::Opts::Cli::define

Mnet::Opts::Cli::define(\%specs)

This function may be used during initialization to define cli options which can be parsed by the Mnet::Opts->cli class method in this module, as in the example which follows that define a --sample string option:

use Mnet::Cli::Opts;
Mnet::Opts::Cli::define({ getopt => 'sample=s' });

An error is issued if an option with the same name has already been defined.

Note that getopt option names defined with this function must start with a letter and contain only letters, numbers, and the dash character. Dashes are replaced with underscores after the options are parsed, so they may be referred to more easily in script code.

The following Getopt::Long option specification types are supported:

opt    --opt       boolean option, set true if --opt is set
opt!   --[no]opt   negatable option, returns false if --noopt is set
opt=i  --opt <i>   required integer, error if input value is not set
opt:i  --opt [i]   optional integer, returns null if value not set
opt=s  --opt <s>   required string, error if input value is not set
opt:s  --opt [s]   optional string, returns null if value not set

The following keys in the specs input hash reference argument are supported:

getopt      required option name and type, see perldoc Getopt::Long
default     default value for option, defaults to undefined
help_hide   set to hide option in --help list of available options
help_tip    short tip text for --help list of available options
help_text   longer help text to show in --help for specific options
record      set so option is saved in Mnet::Test record/replay files
redact      set to prevent option value showing in Mnet::Log output

Refer to Getopt::Long for more information.

new

$opts = Mnet::Opts::Cli->new($env_var)
or ($cli, @extras) = Mnet::Opts::Cli->new($env_var)

The new class method may be used to retrieve an options object containing defined options parsed from the command line and an array contining any extra command line arguments.

The env_var argument is optional, and can be set to the name of an environment variable where additional command line options can be securely set.

If called in list context this method will return an opts object containing values for defined options parsed from the command line followed by a list of any other extra arguments that were present on the command line.

use Mnet::Opts::Cli;
my ($cli, @extras) = Mnet::Opts::Cli->new();

If not called in list context an error will be issued if extra command line arguments exist.

use Mnet::Opts::Cli;
my $cli = Mnet::Opts::Cli->new();

Options are applied in the following order:

child Mnet::Batch command lines
command line
replayed command line
optional environment variable
Mnet::Opts::Set use pragmas
Mnet::Opts::Cli::define default key

Note that errors are not issued for unknown options that may be set for other scripts in the optional env_var environment variable. Also note that this environment variable is not parsed if the --test option is set on the command line.

The perl ARGV array is not modified by this module.

TESTING

When used with the Mnet::Test --record option this module will save all cli options to the specified file if they were defined with the record option attribute set true. Any extra arguments specified on the command line will also be saved. For more info about enabling the recording of individual options refer to the define function in this module and the --test-reset option.

When the --replay option is used this module will load all cli options saved in the specified Mnet::Test file then apply options specified on the command line on top of the replayed options.

When the --replay option is used for an Mnet::Test file which was recorded with extra arguments the extra arguments from the replay file will be used unless there were extra arguments on the command line, in which case the command line arguments will replace the arguments read from the replay file.

The --record option can be used to re-save the current --replay file after applying new command line options and/or extra arguments.

SEE ALSO

Getopt::Long

Mnet

Mnet::Opts

Mnet::Test