The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Commandable-0.12
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).

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.

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

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>