/ 
Term-CLI-0.060000
River stage zero No dependents
/ Term::CLI::Argument::Enum

NAME

Term::CLI::Argument::Enum - class for "enum" string arguments in Term::CLI

VERSION

version 0.060000

SYNOPSIS

use Term::CLI::Argument::Enum;

# static value list
my $arg = Term::CLI::Argument::Enum->new(
    name => 'arg1',
    value_list => [qw( foo bar baz )],
);

my $val_list = $arg->values; # returns ['bar', 'baz', 'foo']

# dynamic value list
my $arg = Term::CLI::Argument::Enum->new(
    name => 'arg1',
    value_list => sub {  my @values = (...); \@values },
);

DESCRIPTION

Class for "enum" string arguments in Term::CLI(3p).

This class inherits from the Term::CLI::Argument(3p) class.

CLASS STRUCTURE

Inherits from:

Term::CLI::Argument(3p).

Consumes:

None.

CONSTRUCTORS

new
OBJ = Term::CLI::Argument::Enum(
    name         => STRING,
    value_list   => ArrayRef | CodeRef,
    cache_values => BOOL,
);

See also Term::CLI::Argument(3p). The value_list argument is mandatory and can either be a reference to an array, or a code refrerence.

A value list consisting of a code reference can be used to implement dynamic values or delayed expansion (where the values have to be fetched from a database or remote system). The code reference will be called with a single argument consisting of the reference to the Term::CLI::Argument::Enum|Term::CLI::Argument::Enum object.

The cache_values attribute can be set to a true value to prevent repeated calls to the value_list code reference. For dynamic value lists this is not desired, but for lists that are generated through expensive queries, this can be useful. The default is 0 (false).

ACCESSORS

See also Term::CLI::Argument(3p).

value_list

A reference to a either a list of valid values for the argument or a subroutine which returns a reference to such a list.

Note that once set, changing the list pointed to by an ArrayRef will result in undefined behaviour.

cache_values
cache_values ( [ BOOL ] )

Returns or sets whether the value list should be cached in case value_list is a code reference.

For dynamic value lists this should be false, but for lists that are generated through expensive queries, it can be useful to set this to true.

If the value is changed from true to false, any cached list is immediately cleared.

METHODS

See also Term::CLI::Argument(3p).

The following methods are added or overloaded:

validate
complete

Overloaded from Term::CLI::Argument(3p).

values

Returns an ArrayRef containing a sorted list of valid values for this argument object.

In case value_list is a CodeRef, it will call the code to expand the list, sort it, and return the result.

EXAMPLES

Return values depending on the time of day:

# Valid values for 'at' depend on the current time of day.
# Before 1pm, 'today' is possible, otherwise only 'tomorrow'.
my $arg = Term::CLI::Argument::Enum(
    name => 'at',
    value_list => sub {
        my ($self) = @_;
        my $hr = (localtime)[2];
        return ($hr < 13) ? ['today', 'tomorrow'] : ['tomorrow'];
    }
);

Return values based on a predefined list of values that can be (temporarily) overridden with local():

my @LIST = qw( one two three );

my $arg = Term::CLI::Argument::Enum(
    name => 'arg',
    value_list => sub { return \@LIST }
);

...

# Will allow 'one', 'two', 'three' for 'arg'.
$cli->execute($cli->readline);

{
    local(@LIST) = qw( four five six );
    # Now allow 'four', 'five', 'six' for 'arg'.
    $cli->execute($cli->readline);
}

# Allow 'one', 'two', 'three' for 'arg' again.
$cli->execute($cli->readline);

SEE ALSO

Term::CLI::Argument(3p), Term::CLI(3p).

AUTHOR

Steven Bakker <sbakker@cpan.org>, 2018.

COPYRIGHT AND LICENSE

Copyright (c) 2018-2022 Steven Bakker

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See "perldoc perlartistic."

This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.