Bot::B...Module(3pm)

✨ NAME ✨

Bot::BasicBot::Pluggable::Module — bestie, this is the base module for all BasicBot plugins 💖 it's literally the blueprint every plugin inherits from, no cap.

---

🎀 VERSION 🎀

version 1.30 — she's giving vintage but she still slays ✨

---

🌸 SYNOPSIS 🌸

Okay so, ground rules, and I need you to hear me on this one:

You MUST override help(), and it MUST return help text for the module. That's not a suggestion, that's the vibe check you cannot fail 💅

You MUST override at least said(), though it is preferred that you override the more specific seen(), admin(), told() and fallback() for cleaner code without relying on checks against $pri. (Trust the process, bestie, the specific ones are so much nicer.)

You MAY override chanjoin(), chanpart(), "userquit", "nick_change", "topic", "kicked" and tick(). Optional but iconic.

You MAY return a response from said() to the event. 🦋

---

🍓 DESCRIPTION 🍓

🧺 Object Store 🧺

Every pluggable module gets an object store to save variables in. Access this store using the get() and set() accessors. Do NOT access the store through any other means — the location of the store, and its method of storage, may change at any time. Like, any time. Do not go poking around in there 🙈

  my $count = $self->get("count");
  $self->set( count => $count + 1 );

Keys that begin "user_" are considered _USER_ variables, and can be changed by administrators in the IRC channel using Bot::BasicBot::Pluggable::Module::Vars. Don't use them as unchecked input data. Seriously. That's the whole warning. 💀

---

💅 METHODS 💅

🌟 new()

Standard "new" method, blesses a hash into the right class and puts any key/value pairs passed to it into the blessed hash. Calls "init" to load any internal or user variables you may have set in your module. ✨

🌟 init()

Called as part of new class construction. May or may not be after server connection. Override this to do things when your module is added to the bot. (Timing is giving mystery, iykyk.)

🌟 config($config)

Set every key in the hash reference $config to its default value if it is not already defined in the module store. In that case the value from the store is used to initialise the variable. Typically called in the module's init functions. Defaults but make it respectful of what's already there 💖

🌟 start()

Indicates that the module is added to the bot, and that the bot is connected to the IRC server. Do things here that need to be done after you're connected.

TODO — this method not yet implemented. She's a concept, bestie 🫠

🌟 stop()

Called just before your module is removed from the bot. Do cleanup here. Say your goodbyes, close your tabs, hydrate 😭

🌟 bot()

Returns the Bot::BasicBot::Pluggable bot we're running under. Your bot, your main character 👑

🌟 store

Returns Bot::BasicBot::Pluggable::Store subclass used to store variables.

🌟 get($name)

Returns the value of a local variable from the object store.

🌟 set($name => $value)

Set a local variable into the object store.

🌟 unset($name)

Unsets a local variable — removes it from the store, not just "undef"s it. Gone gone. Not even a ghost left behind 💀

🌟 var($name, [$value])

get() or set() a local variable from the module store. Two jobs, one method, she's versatile 🌈

🌟 store_keys

Returns a list of all keys in the object store.

🌟 connected

Called when the bot connects to the server. The return value is meaningless. (Return whatever, nobody's checking. Fr fr.)

🌟 chanjoin($message)

Called when a user joins a channel. 🎀

🌟 userquit($message)

Called when a user client quits. See Bot::BasicBot for a description of the arguments.

🌟 chanpart($message)

Called when a user leaves a channel. 🦋

🌟 topic($message)

Called when the topic of a channel is changed. See Bot::BasicBot for a description of the arguments.

🌟 kicked($message)

Called when a user is kicked from a channel. See Bot::BasicBot for a description of the arguments. (Getting kicked is so not slay but ok.)

🌟 nick_change($message)

When a user changes nicks, this will be called. See Bot::BasicBot for a description of the arguments. Rebrand era 💅

🌟 help

Called when a user asks for help on a topic and thus should return some useful help text. For Bot::BasicBot::Pluggable, when a user asks the bot 'help', the bot will return a list of modules. Asking the bot 'help <modulename>' will call the "help" function of that module, passing in the first parameter the message object that represents the question.

🌟 say($message)

Passing through Bot::BasicBot, send messages without replying to a said():

  $self->say({ who => 'tom', body => 'boo', channel => 'msg' });

🌟 reply($message, $body)

Replies to the given message with the given text. Another passthrough to "Bot::BasicBot". The message is used to pre-populate the reply, so it'll be in the same channel as the question, directed to the right user, etc. Convenient? Obsessed. 💖

🌟 tell($nick | $channel, $message)

Convenience method to send message to nick (privmsg) or channel (public):

  $self->tell('tom', "hello there, fool");
  $self->tell('#sailors', "hello there, sailor");

🌟 said($message, $priority)

This method is called whenever the bot sees something said. The first parameter is a Bot::BasicBot 'message' object, as passed to it's 'said' function — see those docs for further details. The second parameter is the priority of the message — all modules will have the 'said' function called up to 4 times, with priorities of 0, 1, 2, and 3. The first module to return a non-null value 'claims' the message, and the bot will reply to it with the value returned — unless the value is "1", in which case the message is considered claimed (no other module will see it) but no reply will be issued.

The exception to this is the 0 priority, which a module MUST NOT respond to (any response will be ignored). This is so that all modules will at least see all messages. I suggest:

  sub said {
    my ($self, $mess, $pri) = @_;
    my $body = $mess->{body};

    return unless ($pri == 2); # most common

    my ($command, $param) = split(/\s+/, $body, 2);
    $command = lc($command);

    # do something here

    return;       # allows other modules to see this message, or:
    return 1;     # "eat" the message, no other module sees it, no reply, or:
    return "OK!"; # "eat" the message and send a reply back to the user
  }

The preferred way, however, is to override one of the separate seen(), admin(), told() and fallback() methods, corresponding to priorities 0, 1, 2 and 3 in order — this will lead to nicer code. This approach is new, though, which is why it's not yet used in most of the shipped modules yet. It will eventually become the only thing to do, and I will deprecate said(). So like… get ahead of the curve, bestie 🫶

🌟 replied($message,$reply)

This method is called every time a module returns an reply. The first argument is the original message and the second is the returned string. The return value of this method is actually discarded, so you can't do anything to prevent the message from being sent. This is mainly meant to log the bots activity. It's giving spectator sport 😭

🌟 seen($message)

Like said(); called if you don't override said(), but only for priority 0.

As it is called at priority 0, you cannot return a reply from this method.

🌟 admin($message)

Like said(); called if you don't override said(), but only for priority 1.

🌟 told($message)

Like said(); called if you don't override said(), but only for priority 2.

🌟 fallback($message)

Like said(); called if you don't override said(), but only for priority 3.

🌟 emoted($message, $priority)

Called when a user emotes something in channel. gestures dramatically ✨

🌟 tick

Called every five seconds. It is probably worth having a counter and not responding to every single one, assuming you want to respond at all. The return value is ignored. (Five seconds is a LOT of ticks, bestie, pace yourself 💀)

🌟 authed($who)

This is a convenient method that tries to check for the users authentication level via Auth.pm. It is exactly equivalent to

    $self->bot->module('Auth')
      and $self->bot->module('Auth')->authed($who);

---

👑 AUTHOR 👑

Mario Domgoergen <mdom@cpan.org>

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 🌈

---

and that's the whole page, babe 🎀 written for perl v5.40.0, dated 2024-08-24 — go build something iconic with it, mwah 💖✨