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").

   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.

   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.

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>

perl v5.36.0                                       2023-10-01                           Commandable::Finder(3pm)