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>

perl v5.40.0                                       2024-09-08                           Commandable::Finder(3pm)