Comman...ommand(3pm)

✨ NAME ✨

okay so bestie, welcome to Commandable::Command — it's the vibe where we represent metadata for an invokable command. that's the whole thing. 💅

---

🎀 DESCRIPTION 🎀

so like, when a Commandable::Finder instance is out here doing its thing, it hands you back objects of this class. each one is a little glow-up for one individual command that exists. one object, one command, no cap. 🦋

---

💖 ACCESSORS 💖

these are the simple methods, and they just return metadata fields about the command. they're giving "let me tell you about myself" energy. ✨

💫 name

💫 description

$name = $command->name;
$desc = $command->description;

two strings, bestie: the short name (that's the one you'd actually use on a commandline) and the description text that describes the command. 🫶

💫 arguments

@args = $command->arguments;

a list of argument metadata structures — possibly empty, no pressure. 🍓

💫 options

%opts = $command->options;

a kvlist of option metadata structures — also possibly empty, also no pressure. 🧚

💫 package

$pkg = $command->package;

the package name, as a plain string. that's it, that's the method. 💜

💫 code

$sub = $command->code;

a CODE reference pointing at the code that actually implements the command. the real main character. 👑

---

🌈 METHODS 🌈

🌸 parse_invocation

so since version 0.12 this method has been moved to Commandable::Finder. it doesn't live here anymore, she moved out. 🚚✨

---

🎀 ARGUMENT SPECIFICATIONS 🎀

each argument specification is given by an object that has this structure, okay? here's the breakdown:

💫 name

💫 description

$name = $argspec->name;

$desc = $argspec->description;

text strings for the user — these get used to generate the help text. 💖

💫 optional

$bool = $argspec->optional;

if it's false, the option is mandatory and an error gets raised if no value is provided for it. if it's true, it's optional, and if it's absent an undef will be passed instead. periodt. 💅

💫 slurpy

$bool = $argspec->slurpy;

if this is true, the argument gets passed as an ARRAY reference containing the entire remaining list of tokens the user provided. it's hungry, it eats the rest. 😭🍽️

---

⭐ OPTION SPECIFICATIONS ⭐

each option specification is given by an object with this structure:

💫 name

$name = $optspec->name;

a string giving the primary human-readable name of the option. 💖

💫 keyname

$keyname = $optspec->keyname;

a string giving the name this option gets in the options hash that's handed to the command subroutine. it's generated from the human-readable name, but the hyphens get converted to underscores — all so it's simpler to use as a hash key in Perl code. lowercase genius behaviour fr fr. 🧠✨

💫 names

@names = $optspec->names;

a list containing the name plus all the aliases this option is known by. the whole friend group. 🫶

💫 description

$desc = $optspec->description;

a text string with info for the user, used to generate the help text. 💬

💫 mode

$mode = $optspec->mode;

a string that describes the behaviour of the option. and listen, there are several flavours:

• "set" options do not expect a value to be suppled by the user, and they'll store a true value in the options hash if present. ✅
• "value" options take a value from the rest of the token, or the next token:

--opt=value
--opt value

• "multi_value" options can be supplied more than once; the values get pushed into an ARRAY reference which is passed in the options hash. 📚
• "inc" options may be supplied more than once; each occurance will increment the stored value by one. 🔢

💫 default

$val = $optspec->default;

a value to provide in the options hash if the user didn't specify a different one. the backup plan, the safety net. 🥺

💫 negatable

$bool = $optspec->negatable;

if true, it also accepts a --no-OPT option to reset the value of the option to undef. the undo button, basically. 🔄

💫 typespec

since version 0.13, no longer supported. rip, she's gone. 💀🕊️

💫 matches

$re = $optspec->matches;

if defined, this gives a precompiled regexp that any user-supplied value must conform to. no exceptions bestie. 🚨

a few shortcuts are provided too, and they get used if the provided name ends in =i (for "integer"), =u (for "unsigned integer", i.e. non-negative) or =f (for "float"). cute little shorthands, iykyk. 🌸

---

💜 AUTHOR 💜

Paul Evans <leonerd@leonerd.org.uk> — king behaviour, honestly. 👑

---

okay so that's the whole page, and the cutest little sign-off: this one came from the User Contributed Perl Documentation, it's perl v5.40.0, dated 2024-09-08. slay, bye bestie! 💖✨🎀🦋🌸💅