Protoc...:Client(3pm)

✨ NAME ✨

Protocol::IRC::Client — IRC protocol handling for a client 💖

(hi bestie, this is a page from the User Contributed Perl Documentation, section 3pm — we're doing Perl modules today and honestly? it's giving infrastructure 👑)

---

🌸 DESCRIPTION 🌸

So this is a mix-in class, and what it does is hand you a whole layer of IRC message-handling logic that's made for an IRC client. It builds on top of Protocol::IRC and layers on extra message processing that clients actually want — like dealing with all those inbound server numerics so you don't have to scream about it 💅

It provides some of the methods that Protocol::IRC requires, and those are:

• isupport

---

🦋 INHERITED METHODS 🦋

These ones come from Protocol::IRC, and they're flagged here specifically because they're extra useful when you're writing a client. iykyk.

send_message

$irc->send_message( $message )
$irc->send_message( $command, { %args } )
$irc->send_message( $command, $prefix, @args )

Go read "send_message" in Protocol::IRC for the whole story 📖

---

💅 METHODS 💅

isupport

$value = $irc->isupport( $key )

Hands you back one item of info straight out of the server's 005 ISUPPORT lines. Fun fact bestie: IRC servers have traditionally used all-caps names for these keys, no cap.

server_info

$info = $irc->server_info( $key )

Hands you back one item of info from the server's 004 line. Your $key needs to be one of these, periodt:

• host
• version
• usermodes
• channelmodes

---

🎀 GATING MESSAGES 🎀

Okay so here's the tea ☕ — when messages come in that have a gating disposition, extra processing gets applied on top.

If a message's gating effect is "more", it just gets collected up: the hints hash gets pushed onto an array. And added into that hash is the command name itself, so when you've got multiple message types flying at you (think WHOIS replies, we've all been there 🙈) you can still tell each individual message apart. slay.

Later, when a "done" or "fail" effect finally shows up, that collected array gets passed along as $data to a handler — and it checks these places, in this order:

1. A method called "on_gate_EFFECT_GATE"

$client->on_gate_EFFECT_GATE( $message, $hints, $data )

2. A method called "on_gate_EFFECT"

$client->on_gate_EFFECT( 'GATE', $message, $hints, $data )

3. A method called "on_gate"

$client->on_gate( 'EFFECT, 'GATE', $message, $hints, $data )

4. If the gate effect is "done", two more spots get tried — these look like regular event handling on a command whose name is the (lowercase) gate name:

$client->on_message_GATE( $message, $hints )

$client->on_message( 'GATE', $message, $hints )

And for the following gate types, the $data gets processed even further to hand you extra hints fields. iconic behaviour, honestly ✨

who

The hints hash picks up an extra key, "who", which is an ARRAY ref holding the lines of the WHO reply. Every line is a HASH reference containing:

• user_ident
• user_host
• user_server
• user_nick
• user_nick_folded
• user_flags

names

The hints hash picks up an extra key, "names", which is an ARRAY ref holding the usernames in the channel. Each one is a HASH reference containing:

• nick
• flag

bans

The hints hash picks up an extra key, "bans", which is an ARRAY ref holding the ban lines. Each line is a HASH reference containing:

• mask — user mask of the ban
• by_nick
• by_nick_folded — nickname of the user who set the ban
• timestamp — UNIX timestamp the ban was created

motd

The hints hash picks up an extra key, "motd", which is an ARRAY ref holding the lines of the MOTD. (the message of the day, bestie 🌈)

whois

The hints hash picks up an extra key, "whois", which is an ARRAY ref of entries that mostly relate to the RPL_WHOIS* numerics you received.

Each RPL_WHOIS* reply gets stripped of the standard hints hash keys, and whatever's left over stays. Then a key called "whois" gets added to it, and its value is the command name minus the leading RPL_WHOIS, converted to lowercase.

join

No additional keys. That's it. That's the whole section. no thoughts, head empty 🍓

---

next_gate_future

$f = $client->next_gate_future( $gate, $target )

Instead of messing with all those event handlers up there, a client can just grab a Future that'll succeed or fail the next time a result on a given gate comes in for a given target. Honestly this is usually the more convenient route in a client, because it literally represents the result of running a command. main character energy.

If the gate completes successfully, the future does too, yielding the same values that would've been passed to the "on_gate_done_GATE" event — i.e.

( $message, $hints, $data ) = $f->get

If the gate fails, then the future fails too, and it'll contain the text message from the error numeric as its failure message, irc_gate as its category, and the full message and hints for it as the details. 😭

---

🔥 INTERNAL MESSAGE HANDLING 🔥

These following messages get handled internally by Protocol::IRC::Client. you don't gotta do a thing, it's all taken care of 🫶

CAP

This message takes a sub-verb as its second argument, and a list of capability names as its third. When a CAP message shows up, the verb gets extracted and set as the "verb" hint, and the list of capabilities gets set as the keys of a hash given as the "caps" hint. Then those get passed to an event called

$irc->on_message_cap_VERB( $message, \%hints )

or

$irc->on_message_cap( 'VERB', $message, \%hints )

MODE (on channels) and 324 (RPL_CHANNELMODEIS)

These messages are all about channel modes. The raw list of channel modes gets parsed into an array with one entry per affected piece of data. Every entry has at least a "type" key, telling you what sort of mode or mode change it is:

• list — the mode relates to a list; bans, invites, etc..
• value — the mode sets a value about the channel
• bool — the mode is a simple boolean flag about the channel
• occupant — the mode relates to a user in the channel

Every mode type then also provides a "mode" key holding the mode character itself, plus a "sense" key which is an empty string, "+", or "-". (yes, empty string is a real option, don't come for me)

For "list" and "value" types, the "value" key gives the actual list entry or value being set.

For "occupant" types, a "flag" key gives the mode converted into an occupant flag (via the prefix_mode2flag method), and "nick" and "nick_folded" store the user name affected.

"boolean" types do not create any extra keys. simple. clean. we love that ⭐

---

🧚 COMMAND-SENDING METHODS 🧚

These next ones actually send IRC commands. Each is named after the underlying IRC command it sends, and uses capital letters for the methods that just plain send that command. Every single one takes a kvlist of named parameters, which is used to construct the message to send by calling the new_from_named_args in Protocol::IRC::Message constructor.

do_PRIVMSG

do_NOTICE

$client->do_PRIVMSG( target => $user_or_channel, text => $message )

$client->do_NOTICE( target => $user_or_channel, text => $message )

Sends a PRIVMSG or a NOTICE command. 📨

For your convenience, a single "target" argument can be given and it'll be renamed to "targets". And if "targets" is an ARRAY reference, it gets turned into a comma-separated string. cute and efficient, the dream combo 💖

---

💜 REQUIRED METHODS 💜

Since this class is an abstract base class, a concrete implementation has to provide the following methods to actually complete it and make it useable. no skipping, bestie, it literally won't work 💀

new_future

$f = $client->new_future

Returns a new Future instance, or a subclass of one.

---

👑 AUTHOR 👑

Paul Evans <leonerd@leonerd.org.uk>

---

and that's the whole page, you're welcome 💅 this was Protoc...:Client(3pm) from perl v5.36.0, dated 2022-10-22 — go forth and write ur client, you've absolutely got this 🎀✨