NAME

Term::CLI::Argument::Tree - class for tree arguments in Term::CLI

VERSION

version 0.059000

SYNOPSIS

 use Term::CLI::Argument::Tree;

 # static values
 my $arg = Term::CLI::Argument::Tree->new(
     name => 'arg1',
     values => { l1 => { l2 => 't1', l3 => undef } }
 );

 my $values = $arg->values; # returns { l1 => { l2 => 't1', l3 => undef } }

 # dynamic values
 my $arg = Term::CLI::Argument::Tree->new(
     name => 'arg1',
     values => sub {  my %values = (...); \%values },
 );

DESCRIPTION

This class provides a multi-valued argument representing levels in a hierarchical data structure. For example, with the structure presented in the "Synopsis", the following sequences of command line argument values are accepted:

  l1
  l1 l2
  l1 l2 t1
  l1 l3

The object provides completion at each level.

Because this argument hoovers up an indeterminate number of input tokens it should be the last argument object specified.

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::Tree(
        name         => STRING,
        values       => HashRef | CodeRef,
        cache_values => BOOL,
    );

See also Term::CLI::Argument(3p). The values argument is mandatory and can either be a reference to a hash, or a code refrerence. The latter 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::Tree" object.

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

ACCESSORS

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

values

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

Note that once set, changing the hash pointed to by the reference will result in undefined behaviour.

cache_values

cache_values ( [ BOOL ] )

Returns or sets whether the values hash should be cached in case values is a code reference.

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

If the value is changed from true to false, the cache 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 Hashref containing the valid values for this argument object.

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

SEE ALSO

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

AUTHOR

Diab Jerius <djeriusr@cpan.org>.

COPYRIGHT AND LICENSE

Copyright (c) 2022 Diab Jerius, Smithsonian Astrophysical Observatory

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