Commandable::Finder::Packages(3p)

NAME
"Commandable::Finder::Packages" - find commands stored per package

SYNOPSIS
   use Commandable::Finder::Packages;

   my $finder = Commandable::Finder::Packages->new(
      base => "MyApp::Command",
   );

   my $help_command = $finder->find_command( "help" );

   foreach my $command ( $finder->find_commands ) {
      ...
   }

DESCRIPTION
This implementation of Commandable::Finder looks for implementations of commands, where each command is implemented by a different package somewhere in the symbol table.

This class uses Module::Pluggable to load packages from the filesystem. As commands are located per package (and not per file), the application can provide special-purpose internal commands by implementing more packages in the given namespace, regardless of which files they come from.

CONSTANTS
   package My::App::Commands::example;

   use constant COMMAND_NAME => "example";
   use constant COMMAND_DESC => "an example of a command";

   ...

Properties about each command are stored as methods (usually constant methods) within each package. Often the constant pragma module is used to create them.

The following constant names are used by default:

  COMMAND_NAME
   use constant COMMAND_NAME => "name";

Gives a string name for the command.

  COMMAND_DESC
   use constant COMMAND_DESC => "description";

Gives a string description for the command.

  COMMAND_ARGS
   use constant COMMAND_ARGS => (
      { name => "argname", description => "description" },
   );

Gives a list of command argument specifications. Each specification is a HASH reference corresponding to one positional argument, and should contain keys named "name", "description", and optionally "optional".

  COMMAND_OPTS
   use constant COMMAND_OPTS => (
      { name => "optname", description => "description" },
   );

Gives a list of command option specifications. Each specification is a HASH reference giving one named option, in no particular order, and should contain keys named "name", "description" and optionally "mode", "multi" and "default".

CONSTRUCTOR

  new
   $finder = Commandable::Finder::Packages->new( %args )

Constructs a new instance of "Commandable::Finder::Packages".

Takes the following named arguments:

base => STR
    The base of the package namespace to look inside for packages that implement commands.

name_method => STR
    Optional. Gives the name of the method inside each command package to invoke to generate the name of the command. Default "COMMAND_NAME".

description_method => STR
    Optional. Gives the name of the method inside each command package to invoke to generate the description text of the command. Default "COMMAND_DESC".

arguments_method => STR
    Optional. Gives the name of the method inside each command package to invoke to generate a list of argument specifications. Default "COMMAND_ARGS".

options_method => STR
    Optional. Gives the name of the method inside each command package to invoke to generate a list of option specifications. Default "COMMAND_OPTS".

code_method => STR
    Optional. Gives the name of the method inside each command package which implements the actual command behaviour. Default "run".

named_by_package => BOOL
    Optional. If true, the name of each command will be taken from its package name. with the leading "base" string removed. If absent or false, the "name_method" will be used instead.

If either name or description method are missing from a package, that package is silently ignored.

Any additional arguments are passed to the "configure" method to be used as configuration options.

AUTHOR
Paul Evans <leonerd@leonerd.org.uk>