Command::V1(3pm)

💖 Command — the manual, but make it cute 💖

okay so bestie, this is Command::V1 from the Perl manual pages (section 3pm, user-contributed Perl docs, iykyk) and it's genuinely such a serve. it's a base class for modules that implement the command pattern. that's the whole vibe. let's get into it 🫶

---

✨ NAME ✨

Command — bestie, it's the base class for modules that implement the command pattern. periodt.

---

🦋 SYNOPSIS 🦋

no cap, here's the whole thing, verbatim, don't touch it:

use TopLevelNamespace;

class TopLevelNamespace::SomeObj::Command {
  is => 'Command',
  has => [
      someobj => { is => 'TopLevelNamespace::SomeObj', id_by => 'some_obj_id' },
      verbose => { is => 'Boolean', is_optional => 1 },
  ],
};

sub execute {
    my $self = shift;
    if ($self->verbose) {
        print "Working on id ",$self->some_obj_id,"\n";
    }
    my $result = $someobj->do_something();
    if ($self->verbose) {
        print "Result was $result\n";
    }
    return $result;
}

sub help_brief {
    return 'Call do_something on a SomeObj instance';
}
sub help_synopsis {
    return 'cmd --some_obj_id 123 --verbose';
}
sub help_detail {
    return 'This command performs a FooBarBaz transform on a SomObj object instance by calling its do_something method.';
}

# Another part of the code

my $cmd = TopLevelNamespace::SomeObj::Command->create(some_obj_id => $some_obj->id);
$cmd->execute();

like. look at it. that's the whole workflow right there 💅

---

🌸 DESCRIPTION 🌸

okay so the tea: Command is a base class you use to build other command modules that implement the Command Pattern. these modules are lowkey so reusable — you can drop them into applications, or you can load them and run them dynamically inside a command-line program. iconic behaviour honestly.

every Command subclass = one reusable work unit. and the bulk of the code in any given one is probably gonna live in the execute() method. execute() will usually take just a single argument — an instance of the Command subclass. that's it. that's the whole signature. simple, clean, slay.

👑 Command-line use 👑

so here's where it gets good. make a top-level Command module — call it, say, TopLevelNamespace::Command — and a script called tln_cmd that looks like this:

#!/usr/bin/perl
use TopLevelNamespace;
TopLevelNamespace::Command->execute_with_shell_params_and_exit();

and boom 💥 you have an instant command-line tool that acts as an interface to the whole hierarchy of command modules under TopLevelNamespace::Command. literally free. main character energy.

for example:

> tln_cmd foo bar --baz 1 --qux

what does that do? okay so it will:

• create an instance of TopLevelNamespace::Command::Foo::Bar — if that class exists, mind you 🙈
• with params baz => 1 and qux => 1, assuming qux is a boolean property
• call execute() on it
• and translate the return value from execute() into the appropriate notion of a shell return value

which means: if execute() returns true in the Perl sense, then the script returns 0 — true in the shell sense. opposite-coded, but we respect it.

the infrastructure handles turning your command line parameters into parameters for create(). params marked is_optional are, of course, optional 🎀 and non-optional params that are missing? yeah, that generates an error. no skipping homework around here.

--help is an implicit param that applies to all Command modules. it generates some hopefully-useful text based on:

• the documentation in the class definition — those 'doc' attributes you can attach to a class and to properties
• the strings returned by help_detail(), help_brief(), and help_synopsis()

so write your help strings, bestie, they're going somewhere 💜

---

🎀 TODO 🎀

ngl, this documentation needs to be fleshed out more. there's a lot of special things you can do with Command modules that isn't mentioned here yet. so like... consider this the trailer, not the full movie. 😭

---

💖 that's the page!! no cap, every flag, every param, every method, all accounted for. you're welcome. 🫶

with love, your fave — perl v5.32.1, dated 2022-01-17, from the Command::V1(3pm) girlies. bye bestie, go write an execute() method 🌈✨💅