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