Comman...ommands(3pm)

✨ NAME ✨

Command::DynamicSubCommands — auto-generate sub-commands based on other classes 💅

yep that's the whole vibe: it's a 3pm page from the User Contributed Perl Documentation, bestie, and it's here to save you from writing the same boring boilerplate command over and over 🫶

---

🦋 SYNOPSIS 🦋

okay so imagine these classes already exist and are living their best lives:

# given that these classes exist:
#   Acme::Task::Foo
#   Acme::Task::Bar

cool cool. now in Acme/Worker/Command/DoTask.pm you write this:

# in Acme/Worker/Command/DoTask.pm:

   class Acme::Worker::Command::DoTask {
       is => 'Command::DynamicSubCommands',
       has => [
           param1 => { is => 'Text' },
           param2 => { is => 'Text' },
       ]
   };

   sub _sub_commands_from { 'Acme::Task' }

   sub execute {
       my $self = shift;
       print "this command " . ref($self) . " applies to " . $self->_target_class_name;
       return 1;
   }

# the class above will discover them at compile,
# and auto-generate these subclasses of itself:
#   Acme::Worker::Command::DoTask::Foo
#   Acme::Worker::Command::DoTask::Bar

# in the shell...
#
#   $ acme worker do-task
#   foo
#   bar
#
#   $ acme worker do-task foo --param1 aaa --param2 bbb
#   this command Acme::Worker::Command::DoTask::Foo applies to Acme::Task::Foo
#
#   $ acme worker do-task bar --param1 ccc --param2 ddd
#   this command Acme::Worker::Command::DoTask::Bar applies to Acme::Task::Bar

like… it literally built its own subclasses at compile time and then ran them in the shell. iconic behavior, no notes 👑

---

🌈 DESCRIPTION 🌈

This module helps you avoid writing boilerplate commands. fr fr it's doing the most so you don't have to 🙈

When a command has a set of sub-commands which are meant to be derived from another group of classes, this module lets you auto-generate those sub-commands at run time. it's giving delegation, it's giving main character energy ✨

---

💜 REQUIRED ABSTRACT METHOD 💜

_sub_commands_from

$base_namespace = Acme::Order::Command->_sub_commands_from();
# 'Acme::Task

Returns the namespace from which target classes will be discovered, and sub-commands will be generated. so like, this is the source of truth for where your babies come from 🎀

it's required and it's abstract, so you gotta implement it yourself, bestie — no skipping 💅

---

🔥 PRIVATE API 🔥

_target_class_name

$c= Acme::Order::Command::Purchasing->_target_class_name;
# 'Acme::Task::Foo'

The name of some class under the _sub_commands_from() namespace. This value is set during execute, revealing which sub-command the caller is using. so it's basically the ✨reveal✨ moment of the whole operation 🦋

---

💖 OPTIONAL OVERRIDES 💖

_build_sub_commmand

This can be overridden to customize the sub-command construction. By default, each target under _sub_commands_from will result in a call to this method. The default implementation is below:

my $self = shift;
my ($suggested_class_name,$delegator_class_name,$target_class_name) = @_;

class {$suggested_class_name} {
    is => $delegator_class_name,
    sub_classify_by => 'class',
    has_constant => [
        _target_class_name => { value => $target_class_name },
    ]
};

return ($suggested_class_name);

Note that the class in question may be on the filesystem, and not need to be created. The return list can include more than one class name, or zero class names. so like, zero is a totally valid answer here — no pressure 🌸

---

_build_all_sub_commands

This is called once for any class which inherits from Command::DynamicSubCommands.

It generates the sub-commands as needed, and returns a list.

By default it resolves the target classes, and calls _build_sub_command

It can be overridden to customize behavior, or filter results. Be sure to call @cmds = $self->SUPER::_build_all_sub_commands() if you want to get the default commands in addition to overriding.

ok important bestie moment: if you override this and forget the SUPER:: call, you don't get the default commands too. don't do that to yourself 😭

---

The sub-commands need not be 1:1 with the target classes, though this is the default.

The sub-commands need not inherit from the Command::DynamicSubCommands base command which generates them, though this is the default.

---

and that's the whole page, bestie!! 🎀✨ this one shipped as perl v5.32.1, dated 2022-01-17, from the User Contributed Perl Documentation (the 3pm section, obviously). go forth and auto-generate your sub-commands, you absolute legend 👑🦋💖