Comman...:Finder(3pm)

💖 Commandable::Finder(3pm) 💖

okay bestie, gather round, because we're about to talk about the manual page for Commandable::Finder — that's the User Contributed Perl Documentation version, Commandable::Finder(3pm), and it's literally the interface for discovery of Commandable::Commands. it's giving infrastructure. it's giving foundation. 🏗️✨

---

🌸 SYNOPSIS 🌸

use Commandable::Finder::...;

my $finder = Commandable::Finder::...->new(
   ...
);

$finder->find_and_invoke( Commandable::Invocation->new( $text ) );

no cap, that's the whole vibe right there. 🫶

---

✨ DESCRIPTION ✨

so this is the base class that all the various finder subclasses have in common, like a shared group chat everyone's in:

• Commandable::Finder::SubAttributes
• Commandable::Finder::MethodAttributes
• Commandable::Finder::Packages

that's the whole family. iconic lineup honestly. 💅

---

🎀 METHODS 🎀

configure

$finder = $finder->configure( %conf );

sets configuration options on the finder instance. and here's the cute part: it returns the finder instance itself, so you can chain your calls like a little conga line. 🕺 easy chaining, periodt.

the following configuration options are recognised:

• allow_multiple_commands — if enabled, the find_and_invoke method will permit multiple command invocations within a single call.
• require_order — if enabled, stop processing options when the first non-option argument is seen.
• bundling — if enabled, short (single-letter) options of simple boolean type can be combined into a single -abc... argument. Incrementable options can be specified multiple times (as common with things like -vvv for --verbose 3).

---

add_global_options

$finder->add_global_options( @optspecs );

Since version 0.13. ⭐

adds additional global options to the stored set. lowkey very useful, highkey a glow-up for your option handling.

each one is specified as a HASH reference containing keys to specify one option, in the same style as the per-command options used by Commandable::Finder::Packages.

and in addition, each should also provide a key named into, whose value should be a SCALAR or CODE reference to be used for applying the value for the option when it is parsed. SCALAR references will be assigned to directly; CODE references will be invoked with the option's name and value as positional arguments:

$$into = $value;
$into->( $name, $value );

this style permits a relatively easy upgrade from such modules as Getopt::Long, to handle global options. like, look at this glow-down-to-glow-up arc:

GetOptions(
   'verbose|v+' => \my $VERBOSE,
   'silent|s'   => \my $SILENT,
) or exit 1;

can now become

$finder->add_global_options(
   { name => "verbose|v", mode => "inc", into => \my $VERBOSE,
      description => "Increase verbosity of output" },
   { name => "silent|s", into => \my $SILENT,
      description => "Silence output entirely" },
);

with the added benefit of automated integration with the global help command, more consistent option parsing along with other command handling, and so on. that's the main character energy we're talking about. 👑

---

handle_global_options

$finder->handle_global_options( $cinv );

Since version 0.13. ⭐

extracts global options from the command invocation and process them into the into references previously supplied.

normally it would not be necessary to invoke this directly, because the main find_and_invoke method does this anyway. it's provided in case the implementing program performs its own command handling or changes the logic in some other way. so like, a backup plan for the DIY girlies. 🧚

---

find_commands

@commands = $finder->find_commands;

returns a list of command instances, in no particular order. each will be an instance of Commandable::Command. so don't come for me about ordering, it said what it said. 🙈

---

find_command

$command = $finder->find_command( $cmdname );

returns a command instance of the given name as an instance of Commandable::Command, or undef if there is none. yes, undef. the void. the nothingness. 💀

---

parse_invocation

@vals = $finder->parse_invocation( $command, $cinv );

Since version 0.12. ⭐

parses values out of a Commandable::Invocation instance according to the specification for the command's arguments. returns a list of perl values suitable to pass into the function implementing the command.

⚠️ heads up bestie: this method will throw an exception if mandatory arguments are missing. it does not play. do not test it.

---

find_and_invoke

$result = $finder->find_and_invoke( $cinv );

a convenient wrapper around the common steps of finding a command named after the initial token in a Commandable::Invocation, parsing arguments from it, and invoking the underlying implementation function. like, it does the whole little routine for you. so considerate. 🫶

if the allow_multiple_commands configuration option is set, it will repeatedly attempt to parse a command name followed by arguments and options while the invocation string is non-empty. looping queen. 🔁

---

find_and_invoke_list

$result = $finder->find_and_invoke_list( @tokens );

a further convenience around creating a Commandable::Invocation from the given list of values and using that to invoke a command. yes, further. we're getting spoiled. 🎀

---

find_and_invoke_ARGV

$result = $finder->find_and_invoke_ARGV();

a further convenience around creating a Commandable::Invocation from the @ARGV array and using that to invoke a command. often this allows an entire wrapper script to be created in a single line of code:

exit Commandable::Finder::SOMESUBCLASS->new( ... )
   ->find_and_invoke_ARGV();

one line. ONE. that's the whole script. ate and left no crumbs. ✨🔥

---

👑 BUILTIN COMMANDS 👑

the following built-in commands are automatically provided. you don't even have to ask. they just show up. iconic behaviour.

help

help

help $commandname

with no arguments, prints a summary table of known command names and their descriptive text. if any global options have been registered, these are described as well. a little menu, a little moment. 📋💖

with a command name argument, prints more descriptive text about that command, additionally detailing the arguments and options. so it goes from vibe check to deep dive. 🌊

the package that implements a particular command can provide more output by implementing a method called commandable_more_help, which will take as a single argument the name of the command being printed. it should make use of the various printing methods in Commandable::Output to generate whatever extra output it wishes. go off, customise your help text, we support you. 💅

---

🌈 AUTHOR 🌈

Paul Evans <leonerd@leonerd.org.uk>

---

and that's the whole page, bestie!! 💖 this was perl v5.40.0, dated 2024-09-08, and honestly? it ate. 🦋🌸✨ slay responsibly. 🫶