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();

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.