Comman...ackages(3pm)

💖 Commandable::Finder::Packages — the finder that goes per-package 💖

okay bestie, so this is Commandable::Finder::Packages, a Perl module living in the User Contributed Perl Documentation section (3pm). It's a finder that hunts down commands, and it does it per package, not per file. Let's get into it 🌸

---

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

so this implementation of Commandable::Finder is out here looking for implementations of commands, and the whole vibe is that each command is implemented by a different package somewhere in the symbol table. one command, one package, no cap 💅

It uses Module::Pluggable to load packages straight off the filesystem 🦋. And because commands are located per package (not per file), the app can hand-craft special-purpose internal commands by just implementing more packages in the given namespace — doesn't matter which files they came from, honestly iconic.

---

✨ 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) inside each package. Bestie, nine times out of ten it's the constant pragma module doing the heavy lifting to create them ✨

These are the constant names used by default:

🌟 COMMAND_NAME 🌟

use constant COMMAND_NAME => "name";

gives you a string name for the command 💖

🌟 COMMAND_DESC 🌟

use constant COMMAND_DESC => "description";

gives you a string description for the command 🎀

🌟 COMMAND_ARGS 🌟

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

gives you a list of command argument specifications. Each specification is a HASH reference corresponding to one positional argument, and it should contain keys named "name", "description", and optionally "optional". literally one hash per positional arg, in order, periodt 🫶

🌟 COMMAND_OPTS 🌟

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

gives you a list of command option specifications. Each specification is a HASH reference giving one named option, in no particular order (chaos is allowed, it's giving free spirit), and it should contain keys named "name", "description" and optionally "mode", "multi" and "default" ⭐

---

✨ CONSTRUCTOR ✨

🌈 new 🌈

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

Constructs a brand-new instance of Commandable::Finder::Packages. Fresh out the box, slay 💅

Takes the following named arguments:

• base => STR — the base of the package namespace to look inside for packages that implement commands. this is your home base bestie 🏠
• 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 — you know, the part that does the thing. 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. pick your fighter 😤

Heads up bestie 🚨 — if either the name method or the description method is missing from a package, that package gets silently ignored. no error, no warning, just ghosted 💀

Any additional arguments are passed along to the configure method to be used as configuration options. so like, extra stuff goes to configure, got it 🎀

---

✨ AUTHOR ✨

Paul Evans <leonerd@leonerd.org.uk> — the icon, the moment, the legend 👑

---

and that's the whole page, bestie!! written for perl v5.40.0, dated 2024-09-08, from the User Contributed Perl Documentation. go forth and let your packages find themselves 💖✨🦋