plucky (3) Commandable::Finder.3pm.gz

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>