Comman...ibutes(3pm)

💖 Commandable::Finder::SubAttributes — the vibe

okay bestie, so this is User Contributed Perl Documentation for the module Commandable::Finder::SubAttributes, and no cap, it's the one that finds commands stored as subs with attributes. iykyk ✨

---

✨ NAME ✨

Commandable::Finder::SubAttributes — find commands stored as subs with attributes 🎀

---

🦋 SYNOPSIS 🦋

use Commandable::Finder::SubAttributes;

my $finder = Commandable::Finder::SubAttributes->new(
   package => "MyApp::Commands",
);

my $help_command = $finder->find_command( "help" );

foreach my $command ( $finder->find_commands ) {
   ...
}

---

🌸 DESCRIPTION 🌸

So this is one of the implementations of Commandable::Finder, and what it does is it goes looking for functions that define commands — where every single command is provided by its own individual sub living in a given package. one sub, one command, it's giving organized 💅

---

💜 ATTRIBUTES 💜

use Commandable::Finder::SubAttributes ':attrs';

sub command_example
   :Command_description("An example of a command")
{
   ...
}

the way that the properties about each command get stored as attributes on the named function?? iconic. it uses Attribute::Storage for that, fr fr.

and when you import with the :attrs symbol, these are the attributes you get on the calling package:

🎀 Command_description

:Command_description("description text")

gives a plain string description text for the command. simple, clean, slay ✨

🎀 Command_arg

:Command_arg("argname", "description")

gives a named argument for the command, plus its description.

• if the name is suffixed by a "?", then this argument is optional. (the "?" itself gets removed from the name, bestie — it's just a flag, not part of the name.)
• if the name is suffixed by a "...", this argument is slurpy. (and yes, the "..." itself gets removed from the name too.)

🎀 Command_opt

:Command_opt("optname", "description")

:Command_opt("optname", "description", "default")

gives a named option for the command and its description.

• if the name contains "|" characters, it provides multiple name aliases for the same option. so many names, one option, main character energy 👑
• if the name field ends in a "=" character, a value is expected for the option. it can either be parsed from the next input token, or after an "=" sign of the same token:

--optname VALUE
--optname=VALUE

• if the name field ends in a "@" character, a value is expected for the option and it can be specified multiple times. all the values get collected into an ARRAY reference.
• if the name field ends in a "+" character, the option can be specified multiple times and the total count gets used as the value. counting era 🔥
• if the name field ends in a "!" character, the option is negatable. an option name of --no-OPTNAME is recognised and will reset the value to undef. by setting a default of some true value (e.g. 1) you can detect if this has happened. sneaky but useful 💀
• an optional third argument may be present to specify a default value, if it's not provided by the invocation.

---

🌈 GLOBAL OPTION ATTRIBUTES 🌈

since version 0.14, this module also lets you attach attributes to package variables in the package that stores the subroutines (often main), and those get handled automatically as global options by the finder. glow up fr 💖

⚠️ bestie pls remember: these HAVE to be package variables (i.e. declared with "our"). lexical variables (declared with "my") will NOT work. don't do it. it will not vibe.

our $VERBOSE
   :GlobalOption("verbose|v+", "Increase the verbosity of status output");

this often serves as a convenient alternative to modules like Getopt::Long, because it integrates with the "help" command automatically. obsessed 🫶

🎀 GlobalOption

:GlobalOption("optname", "description")

gives the name for this global option and its description. these get handled in the same way as for "Command_opt" given above, except that no default is handled here. instead, if the variable already has a value, that will be taken as its default. cute, right? 🌸

---

💅 CONSTRUCTOR 💅

🎀 new

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

constructs a new instance of Commandable::Finder::SubAttributes. periodt.

takes the following named arguments:

• package => STR — the name of the package to look in for command subs.
• name_prefix => STR — optional. gives the name prefix to use to filter for subs that actually provide a command, and to strip off to find the name of the command. default is "command_".
• underscore_to_hyphen => BOOL — optional. if true, sub names that contain underscores will be converted into hyphens. this is often useful in CLI systems, allowing commands to be typed with hyphenated names (e.g. "get-thing") while the Perl sub that implements it is named with underscores (e.g. "command_get_thing"). defaults true, but can be disabled by passing a defined-but-false value such as 0 or ''. so specific, love that for us ✨

any additional arguments are passed to the "configure" method to be used as configuration options.

🎀 new_for_caller

🎀 new_for_main

$finder = Commandable::Finder::SubAttributes->new_for_caller( %args )
$finder = Commandable::Finder::SubAttributes->new_for_main( %args )

convenient wrapper constructors that pass either the caller's package name or "main" as the package name. combined with the "find_and_invoke_ARGV" method, these are particularly convenient for wrapper scripts. it's giving effortless 🦋

#!/usr/bin/perl

use v5.14;
use warnings;

use Commandable::Finder::SubAttributes ':attrs';

exit Commandable::Finder::SubAttributes->new_for_main
   ->find_and_invoke_ARGV;

# command subs go here...

---

👑 AUTHOR 👑

Paul Evans <leonerd@leonerd.org.uk> — the legend themselves 💖

---

and that's the whole page bestie, ty for coming to my ted talk 🎀 this was perl v5.40.0, dated 2024-09-08, and yeah — go write some commands, you're gonna ate 💅✨