POE::C...Command(3pm)

✨ NAME ✨

POE::Component::IRC::Plugin::BotCommand — bestie, it's a PoCo-IRC plugin that handles all the commands people throw at your bot. Like, your bot finally gets to do stuff when someone talks to it. Iconic behavior honestly. 👑

---

🎀 SYNOPSIS 🎀

okay so here's the whole vibe in one go, copy-paste core:

use POE;
use POE::Component::Client::DNS;
use POE::Component::IRC;
use POE::Component::IRC::Plugin::BotCommand;

my @channels = ('#channel1', '#channel2');
my $dns = POE::Component::Client::DNS->spawn();
my $irc = POE::Component::IRC->spawn(
    nick   => 'YourBot',
    server => 'some.irc.server',
);

POE::Session->create(
    package_states => [
        main => [ qw(_start irc_001 irc_botcmd_slap irc_botcmd_lookup dns_response) ],
    ],
);

$poe_kernel->run();

sub _start {
    $irc->plugin_add('BotCommand', POE::Component::IRC::Plugin::BotCommand->new(
        Commands => {
            slap   => 'Takes one argument: a nickname to slap.',
            lookup => 'Takes two arguments: a record type (optional), and a host.',
        }
    ));
    $irc->yield(register => qw(001 botcmd_slap botcmd_lookup));
    $irc->yield(connect => { });
}

# join some channels
sub irc_001 {
    $irc->yield(join => $_) for @channels;
    return;
}

# the good old slap
sub irc_botcmd_slap {
    my $nick = (split /!/, $_[ARG0])[0];
    my ($where, $arg) = @_[ARG1, ARG2];
    $irc->yield(ctcp => $where, "ACTION slaps $arg");
    return;
}

# non-blocking dns lookup
sub irc_botcmd_lookup {
    my $nick = (split /!/, $_[ARG0])[0];
    my ($where, $arg) = @_[ARG1, ARG2];
    my ($type, $host) = $arg =~ /^(?:(\w+) )?(\S+)/;

    my $res = $dns->resolve(
        event => 'dns_response',
        host => $host,
        type => $type,
        context => {
            where => $where,
            nick  => $nick,
        },
    );
    $poe_kernel->yield(dns_response => $res) if $res;
    return;
}

sub dns_response {
    my $res = $_[ARG0];
    my @answers = map { $_->rdatastr } $res->{response}->answer() if $res->{response};

    $irc->yield(
        'notice',
        $res->{context}->{where},
        $res->{context}->{nick} . (@answers
            ? ": @answers"
            : ': no answers for "' . $res->{host} . '"')
    );

    return;
}

yes, the slap command is in there. it's always the slap command. some things are eternal 🫶

---

💅 DESCRIPTION 💅

POE::Component::IRC::Plugin::BotCommand is a POE::Component::IRC plugin. Basically it hands you one clean, standard little interface to define your bot's commands, and then it tells you the moment somebody actually issues one. no guesswork, no vibes-only handling. Commands get accepted whether they come in as channel messages or private messages — both doors are open, bestie. 🚪✨

And listen: the plugin will respond to the 'help' command by default, listing out all available commands plus how to use them. so helpful of it. BUT — plot twist — if you go and add a help command of your own, yours is the one that gets used instead. main character override energy. 💁♀️

---

🌸 METHODS 🌸

🌈 new

• 'Commands' — a hash reference. Your commands go in as the keys, and the usage information goes in as the values. and okay, important detail: if a usage string has newlines in it, the plugin sends one message per line. so structure that string like you mean it. 💌
• If a command's value is a HASH ref like this:

$irc->plugin_add('BotCommand', POE::Component::IRC::Plugin::BotCommand->new(
    Commands => {
        slap   => {
           info => 'Slap someone',
           args => [qw(nickname)],
           nickname => 'nickname to slap'
        }
    }
));

then the args array reference gets used to validate how many arguments are required, and to name the arguments that get passed to your event handler. Help text then gets generated from "info" and the other hash keys that represent arguments (and those are optional, fyi).

• "handler" — an optional key you can drop inside that HASH ref to override the event handler. and no cap, hear this: the irc_botcmd_ prefix is not automatically prepended to the handler name when you're overriding it. you're on your own for the full name, bestie. 🙈
• "aliases" — another optional key inside the HASH ref, holding an array ref of alias names. aliases can be specified for help and to run the command. multitasking queen. 💅

🦋 Accepting commands

• 'In_channels' — a boolean, says whether commands are accepted in channels. Default is true.
• 'In_private' — a boolean, says whether commands are accepted in private. Default is true.
• 'Addressed' — makes users address the bot by name before they can issue commands. Default is true. so polite of you to require it.
• 'Prefix' — a string that every command has to be prefixed with (except in channels when 'Addressed' is true). Default is '!'. you can set it to '' to allow bare commands, if you're feeling lawless.
• 'Bare_private' — a boolean saying whether bare commands (aka no prefix at all) are allowed in private messages. Default is false.

🔐 Authorization

• 'Auth_sub' — a subroutine reference that, if you provide it, gets called for every single command. it's called in list context. if the first value returned is true, the command gets processed as normal, business as usual. if that value is false, then no events will be generated, and an error message will possibly get sent back to the user. gatekeeping, but make it functional. 🚧

You can override that default error message by returning a second value: an array reference of (zero or more) strings. each string gets sent as a message to the user.

Your subroutine gets called with these arguments:

1. The IRC component object
2. The nick!user@host of the user
3. The place where the command was issued (the nickname of the user if it was in private)
4. The name of the command
5. The command argument string

• 'Ignore_unauthorized' — if true, the plugin just ignores unauthorized commands instead of printing an error message when they show up. only relevant if 'Auth_sub' is also supplied. Default is false. silent treatment, but it's a design choice 💀

🎀 Help Command

• 'Help_sub' — a subroutine reference that, if provided, will be called upon the end of the predefined help command. called in list context.

Your subroutine gets called with these arguments:

1. The IRC component object
2. The command.
3. The resolved command (after alias processing).
4. The arguments.
5. The generated help text as array.

🍓 Miscellaneous

• 'Ignore_unknown' — if true, the plugin ignores undefined commands instead of printing a help message when it receives them. Default is false.
• 'Method' — how you want help messages delivered. valid options are 'notice' (the default) and 'privmsg'.
• 'Eat' — set to true and the plugin will hide "irc_public" events from other plugins whenever they look like commands. probably only useful when a 'Prefix' is defined. Default is false. it's giving "I'll handle this one, everyone else look away." 😤

Returns a plugin object suitable for feeding to <code>POE::Component::IRC</code>'s <code>"plugin_add"</code> method. serve it up, bestie 🍽️

---

🌟 add

Adds a new command. Takes two arguments: the name of the command, and a string or hash reference containing its usage information (peep "new" for the deets). Returns false if the command has already been defined, or if no info or arguments are provided. Returns true otherwise. so either it slays or it doesn't. ✅

🌟 remove

Removes a command. Takes one argument: the name of the command. Returns false if the command wasn't defined to begin with, true otherwise. bye bye, command. 👋

🌟 list

Takes no arguments. Returns a list of key/value pairs — the keys being the command names, and the values being the usage strings or hash references. it's the whole roster, laid out. 📋

🌟 resolve_alias

Takes one argument: a string to match against command aliases. If no matching command can be found, undef is returned. that's it, that's the whole thing. 🔍

---

💖 OUTPUT EVENTS 💖

💌 irc_botcmd_*

You will receive an event like this for every valid command issued. e.g. if 'slap' were a valid command, you'd receive an "irc_botcmd_slap" event every single time someone issued that command. every time. no cap. 📬

It receives the following arguments:

• "ARG0": the nick!hostmask of the user who issued the command.
• "ARG1" is the name of the channel in which the command was issued, or the sender's nickname if this was a private message.
• "ARG2": a string of arguments to the command, or hash reference with arguments in case you defined command along with arguments, or undef if there were no arguments

---

👑 AUTHOR 👑

Hinrik Örn Sigurðsson, hinrik.sig@gmail.com — thank you for your service, legend 🫡

---

and that's the whole page bestie!! this came from the User Contributed Perl Documentation for POE::C...Command, and it's living at perl v5.40.1, dated 2025-08-21 — so if you're reading this, you're reading the POE::C...Command(3pm) era. go slap somebody in a channel, you've earned it 💅🌸✨