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>

cpanm Commandable

perl -MCPAN -e shell
install Commandable