NAME

Term::CLI::Command - Class for (sub-)commands in Term::CLI

VERSION

version 0.060000

SYNOPSIS

use Term::CLI::Command;
use Term::CLI::Argument::Filename;
use Data::Dumper;

my $copy_cmd = Term::CLI::Command->new(
   name => 'copy',
   options => [ 'verbose!' ],
   arguments => [
       Term::CLI::Argument::Filename->new(name => 'src'),
       Term::CLI::Argument::Filename->new(name => 'dst'),
   ],
   callback => sub {
       my ($self, %args) = @_;
       print Data::Dumper->Dump([\%args], ['args']);
       return (%args, status => 0);
   }
);

DESCRIPTION

Class for command elements in Term::CLI(3p).

CLASS STRUCTURE

Inherits from:

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

Consumes:

Term::CLI::Role::ArgumentSet(3p), Term::CLI::Role::CommandSet(3p), Term::CLI::Role::HelpText(3p), Term::CLI::Role::State(3p).

CONSTRUCTORS

new ( name => VARNAME ... )

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

The name attribute is required.

Other attributes are:

arguments => ArrayRef

Reference to an array containing Term::CLI::Argument(3p) object instances that describe the parameters that the command takes, or undef.

See also Term::CLI::Role::ArgumentSet.

callback => CodeRef

Reference to a subroutine that should be called when the command is executed, or undef.

commands => ArrayRef

Reference to an array containing Term::CLI::Command object instances that describe the sub-commands that the command takes, or undef.

See also Term::CLI::Role::CommandSet.

require_sub_command => Bool

If the command has sub-commands, it is normally required that the input contains one of the sub-commands after this command. However, it may be desirable to allow the command to appear "naked", i.e. without a sub-command. For such cases, set the require_sub_command to a false value.

See also Term::CLI::Role::CommandSet.

options => ArrayRef

Reference to an array containing command options in Getopt::Long(3p) style, or undef.

description => Str

Extended description of the command.

See also Term::CLI::Role::HelpText.

summary => Str

Short description of the command.

See also Term::CLI::Role::HelpText.

usage => Str

Static usage summary of the command.

See also Term::CLI::Role::HelpText.

(NOTE: You will rarely have to specify this, as it can be determined automatically.)

INHERITED METHODS

This class inherits all the attributes and accessors of Term::CLI::Element(3p), Term::CLI::Role::CommandSet(3p), Term::CLI::Role::HelpText(3p), and Term::CLI::Role::ArgumentSet(3p), most notably:

Accessors

has_arguments

See has_arguments in Term::CLI::Role::ArgumentSet.

has_callback

See has_callback in Term::CLI::Role::CommandSet.

has_commands

See has_commands in Term::CLI::Role::CommandSet.

arguments

See arguments in Term::CLI::Role::ArgumentSet.

Returns a list of Term::CLI::Argument object instances.

commands

See commands in Term::CLI::Role::CommandSet.

Returns a list of Term::CLI::Command object instances.

callback ( [ CodeRef ] )

See callback in Term::CLI::Role::CommandSet.

description ( [ Str ] )

See description in Term::CLI::Role::HelpText.

summary ( [ Str ] )

See summary in Term::CLI::Role::HelpText.

usage ( [ Str ] )

See description in Term::CLI::Role::HelpText.

Others

argument_names

Return the list of argument names, in the original order.

command_names

Return the list of (sub-)command names, sorted alphabetically.

find_command ( CMD )

Check whether CMD is a sub-command of this command. If so, return the appropriate Term::CLI::Command reference; otherwise, return undef.

METHODS

Accessors

has_options

Predicate functions that return whether or not the associated attribute has been set.

options ( [ ArrayRef ] )

ArrayRef with command-line options in Getopt::Long(3p) format.

Others

complete ( TEXT, STATE )

Called by Term::CLI::Role::CommandSet's complete_line method, or another Term::CLI::Command's complete function.

The method can complete options, sub-commands, and arguments. Completions of commands and arguments is delegated to the appropriate Term::CLI::Command and Term::CLI::Argument instances, resp.

option_names

Return a list of all command line options for this command. Long options are prefixed with --, and one-letter options are prefixed with -.

Example:

$cmd->options( [ 'verbose|v+', 'debug|d', 'help|h|?' ] );
say join(' ', $cmd->option_names);
# output: --debug --help --verbose -? -d -h -v

execute_command ( KEY => VAL, ... )

This method is called by Term::CLI::Role::CommandSet's execute_line method. It should not be called directly.

It accepts the same list of parameters as the command callback function (see Term::CLI::Role::CommandSet), and returns the same structure.

The arguments parameter (an ArrayRef) should contain the words on the command line that have not been parsed yet.

Depending on whether the object has sub-commands or arguments, the rest of the line is parsed (possibly handing off to another sub-command), and the results are passed to the command's callback function.

SEE ALSO

Term::CLI::Argument(3p), Term::CLI::Element(3p), Term::CLI::Role::ArgumentSet(3p), Term::CLI::Role::CommandSet(3p), Term::CLI::Role::HelpText(3p), Term::CLI(3p), Term::CLI::Util(3p), Getopt::Long(3p).

AUTHOR

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

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