NAME

Term::CLI::Role::CommandSet - Role for (sub-)commands in Term::CLI

VERSION

version 0.04004

SYNOPSIS

 package Term::CLI::Command {

    use Moo;

    with('Term::CLI::Role::CommandSet');

    ...
 };

 my $cmd = Term::CLI::Command->new( ... );

 $cmd->callback->( %args ) if $cmd->has_callback;

 if ( $cmd->has_commands ) {
    my $cmd_ref = $cmd->find_command( $cmd_name );
    die $cmd->error unless $cmd_ref;
 }

 say "command names:", join(', ', $cmd->command_names);

 $cmd->callback->( $cmd, %args ) if $cmd->has_callback;

 %args = $cmd->try_callback( %args );

DESCRIPTION

Role for Term::CLI(3p) elements that contain a set of Term::CLI::Command(3p) objects.

This role is used by Term::CLI(3p) and Term::CLI::Command(3p).

ATTRIBUTES

This role defines two additional attributes:

commands => ArrayRef

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

Note that the elements of the array are copied over to an internal array, so modifications to the ArrayRef will not be seen.

callback => CodeRef

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

ACCESSORS AND PREDICATES

has_callback

has_commands

Predicate functions that return whether or not any (sub-)commands have been added to this object.

callback ( [ CODEREF ] )

CODEREF to be called when the command is executed. The callback is called as:

   OBJ->callback->(OBJ,
        status       => Int,
        error        => Str,
        options      => HashRef,
        arguments    => ArrayRef[Value],
        command_line => Str,
        command_path => ArrayRef[InstanceOf['Term::CLI::Command']],
   );

Where:

CLI_REF

Reference to the current Term::CLI object.

status

Indicates the status of parsing/execution so far. It has the following meanings:

< 0

Negative status values indicate a parse error. This is a sign that no action should be taken, but some error handling should be performed. The actual parse error can be found under the error key. A typical thing to do in this case is for one of the callbacks in the chain (e.g. the one on the Term::CLI object to print the error to STDERR).

0

The command line parses as valid and execution so far has been successful.

> 0

Some error occurred in the execution of the action. Callback functions need to set this by themselves.

error

In case of a negative status, this will contain the parse error. In all other cases, it may or may not contain useful information.

options

Reference to a hash containing all command line options. Compatible with the options hash as set by Getopt::Long(3p).

arguments

Reference to an array containing all the arguments to the command. Each value is a scalar value, possibly converted by its corresponding Term::CLI::Argument's validate method (e.g. 3e-1 may have been converted to 0.3).

unparsed

Reference to an array containing all the words on the command line that have not been parsed as arguments or sub-commands yet. In case of parse errors, this often contains elements, and otherwise should be empty.

command_line

The complete command line as given to the Term::CLI::execute method.

command_path

Reference to an array containing the "parse tree", i.e. a list of object references:

    [
        InstanceOf['Term::CLI'],
        InstanceOf['Term::CLI::Command'],
        ...
    ]

The first item in the command_path list is always the top-level Term::CLI object, while the last is always the same as the OBJ_REF parameter.

The callback is expected to return a hash (list) containing at least the same keys. The command_path, arguments, and options should be considered read-only.

Note that a callback can be called even in the case of errors, so you should always check the status before doing anything.

commands

Return the list of subordinate Term::CLI::Command objects (i.e. "sub-commands") sorted on name.

parent

Return a reference to the object that "owns" this object. This is typically another object class that consumes this Term::CLI::Role::CommandSet role, such as Term::CLI(3p) or Term::CLI::Command(3p), or undef.

METHODS

add_command ( CMD_REF, ... )

Add the given CMD_REF command(s) to the list of (sub-)commands, setting each CMD_REF's parent in the process.

command_names

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

find_matches ( Str )

Return a list of all commands in this object that match the Str prefix.

find_command ( Str )

Check whether Str uniquely matches a command in this Term::CLI object. Returns a reference to the appropriate Term::CLI::Command object if successful; otherwise, it sets the objects error field and returns undef.

Example:

    my $sub_cmd = $cmd->find_command($prefix);
    die $cmd->error unless $sub_cmd;

root_node

Walks parent chain until it can go no further. Returns a reference to the object at the top. In a functional setup, this is expected to be a Term::CLI(3p) object.

try_callback ( ARGS )

Wrapper function that will call the object's callback function if it has been set, otherwise simply returns its arguments.

SEE ALSO

Term::CLI(3p), Term::CLI::Command(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.