---
name: "Commandable::Finder"
section: "3pm"
platform: "linux"
package: "libcommandable-perl"
version: "0.14-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Commandable::Finder"
---

# Commandable::Finder(3pm)

an interface for discovery of Commandable::Commands

## 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:

- •

  Commandable::Finder::SubAttributes

- •

  Commandable::Finder::MethodAttributes

- •

  Commandable::Finder::Packages

## 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\>