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>

2023-01-08

perl v5.36.0