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",
        help_tip => "set to input string",
    });

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

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

    # 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.

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
    norecord    set so option is not saved to Mnet::Test record/replay
    redact      set to prevent option value from displaying in Mnet::Log

Refer to Getopt::Long for more information.

new

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

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.

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
    Mnet 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 Mnet environment variable. Also note that the Mnet 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 defined without the norecord hash key set true in the specified file along with any extra arguments specified on the command line. 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::Opts::Cli::Cache

Mnet::Opts::Set

Mnet::Test

cpanm Mnet

perl -MCPAN -e shell
install Mnet