"Commandable::Finder" - an interface for discovery of Commandable::Commands

       Paul Evans <leonerd@leonerd.org.uk>

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

       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.

       This base class is common to the various finder subclasses:

       •   Commandable::Finder::SubAttributes

       •   Commandable::Finder::MethodAttributes

       •   Commandable::Finder::Packages

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

       Sinceversion0.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 );

       Sinceversion0.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 );

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

       "Commandable::Finder" - an interface for discovery of Commandable::Commands

          use Commandable::Finder::...;

          my $finder = Commandable::Finder::...->new(
             ...
          );

          $finder->find_and_invoke( Commandable::Invocation->new( $text ) );