/ 
Commandable-0.14
River stage one • 4 direct dependents • 7 total dependents
/ Commandable::Finder

NAME

Commandable::Finder - an interface for discovery of Commandable::Commands

SYNOPSIS

use Commandable::Finder::...;

my $finder = Commandable::Finder::...->new(
   ...
);

$finder->find_and_invoke( Commandable::Invocation->new( $text ) );

DESCRIPTION

This base class is common to the various finder subclasses:

METHODS

configure

$finder = $finder->configure( %conf );

Sets configuration options on the finder instance. Returns the finder instance itself, to permit easy chaining.

The following configuration options are recognised:

allow_multiple_commands

If enabled, the "find_and_invoke" method will permit multiple command invocations within a single call.

require_order

If enabled, stop processing options when the first non-option argument is seen.

bundling

If enabled, short (single-letter) options of simple boolean type can be combined into a single -abc... argument. Incrementable options can be specified multiple times (as common with things like -vvv for --verbose 3).

add_global_options

$finder->add_global_options( @optspecs );

Since version 0.13.

Adds additional global options to the stored set.

Each is specified as a HASH reference containing keys to specify one option, in the same style as the per-command options used by Commandable::Finder::Packages.

In addition, each should also provide a key named into, whose value should be a SCALAR or CODE reference to be used for applying the value for the option when it is parsed. SCALAR references will be assigned to directly; CODE references will be invoked with the option's name and value as positional arguments:

$$into = $value;
$into->( $name, $value );

This style permits a relatively easy upgrade from such modules as Getopt::Long, to handle global options.

GetOptions(
   'verbose|v+' => \my $VERBOSE,
   'silent|s'   => \my $SILENT,
) or exit 1;

Can now become

$finder->add_global_options(
   { name => "verbose|v", mode => "inc", into => \my $VERBOSE,
      description => "Increase verbosity of output" },
   { name => "silent|s", into => \my $SILENT,
      description => "Silence output entirely" },
);

with the added benefit of automated integration with the global help command, more consistent option parsing along with other command handling, and so on.

handle_global_options

$finder->handle_global_options( $cinv );

Since version 0.13.

Extracts global options from the command invocation and process them into the into references previously supplied.

Normally it would not be necessary to invoke this directly, because the main "find_and_invoke" method does this anyway. It is provided in case the implementing program performs its own command handling or changes the logic in some other way.

find_commands

@commands = $finder->find_commands;

Returns a list of command instances, in no particular order. Each will be an instance of Commandable::Command.

find_command

$command = $finder->find_command( $cmdname );

Returns a command instance of the given name as an instance of Commandable::Command, or undef if there is none.

parse_invocation

@vals = $finder->parse_invocation( $command, $cinv );

Since version 0.12.

Parses values out of a Commandable::Invocation instance according to the specification for the command's arguments. Returns a list of perl values suitable to pass into the function implementing the command.

This method will throw an exception if mandatory arguments are missing.

find_and_invoke

$result = $finder->find_and_invoke( $cinv );

A convenient wrapper around the common steps of finding a command named after the initial token in a Commandable::Invocation, parsing arguments from it, and invoking the underlying implementation function.

If the allow_multiple_commands configuration option is set, it will repeatedly attempt to parse a command name followed by arguments and options while the invocation string is non-empty.

find_and_invoke_list

$result = $finder->find_and_invoke_list( @tokens );

A further convenience around creating a Commandable::Invocation from the given list of values and using that to invoke a command.

find_and_invoke_ARGV

$result = $finder->find_and_invoke_ARGV();

A further convenience around creating a Commandable::Invocation from the @ARGV array and using that to invoke a command. Often this allows an entire wrapper script to be created in a single line of code:

exit Commandable::Finder::SOMESUBCLASS->new( ... )
   ->find_and_invoke_ARGV();

BUILTIN COMMANDS

The following built-in commands are automatically provided.

help

help

help $commandname

With no arguments, prints a summary table of known command names and their descriptive text. If any global options have been registered, these are described as well.

With a command name argument, prints more descriptive text about that command, additionally detailing the arguments and options.

The package that implements a particular command can provide more output by implementing a method called commandable_more_help, which will take as a single argument the name of the command being printed. It should make use of the various printing methods in Commandable::Output to generate whatever extra output it wishes.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>