NAME

Term::CLI::Argument - generic parent class for arguments in Term::CLI

VERSION

version 0.059000

SYNOPSIS

 use Term::CLI::Argument;

 my $arg = Term::CLI::Argument->new(name => 'varname');

DESCRIPTION

Generic parent class for arguments in Term::CLI(3p). Inherits from Term::CLI::Element(3p).

CLASS STRUCTURE

Inherits from:

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

Consumes:

None.

CONSTRUCTORS

new ( name => VARNAME ... )

Create a new Term::CLI::Argument object and return a reference to it.

The name attribute is required.

Other possible attributes are:

min_occur => INT

The minimal number of times the argument must occur. A negative or zero value means there is no minimum.

The default is 1.

max_occur => INT

The maximum number of times the argument may occur. A negative or zero value means there is no maximum.

The default is 1.

occur => INT

A shortcut to setting min_occur and max_occur to the same value. Specifying this will override any min_occur or max_occur attributes.

METHODS

Accessors

Accessors are inherited from Term::CLI::Element(3p).

Additionally, there are the following:

min_occur ( [ INT ] )

Get or set the min_occur attribute.

max_occur ( [ INT ] )

Get or set the max_occur attribute.

Other

occur ( [ INT [, INT ] ] )

When called with no arguments, returns two-element list containing the min_occur and max_occur values, respectively.

When called with one argument, it will set both the min_occur and max_occur attributes to the given value.

type

Return the argument "type". By default, this is the object's class name with the Term::CLI::Argument:: prefix removed. Can be overloaded to provide a different value.

validate ( TEXT, STATE )

Check whether TEXT is a valid value for this object. Return the (possibly normalised) value if it is valid. Otherwise, return nothing (i.e. undef or the empty list, depending on call context) and set the error() attribute).

By default, this method only checks whether value is defined and not an empty string.

Sub-classes should probably override this.

The validate function can be made context-aware by inspecting the STATE parameter, a HashRef containing the same key/value pairs as in the arguments to the command callback function (see also Term::CLI::Role::CommandSet):

    STATE = {
        status       => Int,
        error        => Str,
        options      => HashRef,
        arguments    => ArrayRef[Value],
        command_line => Str,
        command_path => ArrayRef[InstanceOf['Term::CLI::Command']],
    }

The arguments array holds the argument values (scalars) that were parsed up until now (not including the current argument value).

The command_path array holds the Term::CLI::Command objects that were parsed up until now. This means that the command to which this argument applies can be accessed with:

    CURRENT_COMMAND = STATE->{command_path}->[-1];

The command_line is the full string as it was passed from readline.

NOTE:

Care should be taken to not modify the values in the STATE HashRef. Modifications may result in unexpected behaviour.

BUNDLED SUB-CLASSES

The Term::CLI(3p) distribution comes bundled with a number of arugment classes.

Term::CLI::Argument::Bool

Parse, complete, and validate boolean arguments.

Term::CLI::Argument::Enum

Parse, complete, and validate "enum"-like arguments (pre-defined lists of words).

Term::CLI::Argument::Filename

Parse, complete, and validate file/path names.

Term::CLI::Argument::Number

Parse and validate numbers.

Term::CLI::Argument::String

Parse and validate generic strings.

Term::CLI::Argument::TypeTiny

Parse and validate Type::Tiny(3p) arguments.

SEE ALSO

Term::CLI(3p), Term::CLI::Argument::Enum(3p), Term::CLI::Argument::Filename(3p), Term::CLI::Argument::Number(3p), Term::CLI::Argument::String(3p), Term::CLI::Argument::TypeTiny(3p), Term::CLI::Element(3p).

AUTHOR

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

COPYRIGHT AND LICENSE

Copyright (c) 2018 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.

cpanm Term::CLI

perl -MCPAN -e shell
install Term::CLI