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

cpanm Mnet

perl -MCPAN -e shell
install Mnet