Net::A...rotocol(3pm)

💖 Net::Async::IRC::Protocol — the perl manpage but make it slay 💖

okay so bestie, this is Net::Async::IRC::Protocol(3pm) from the User Contributed Perl Documentation, and it's literally the group chat layer for IRC. let's get into it 🫶

---

✨ NAME ✨

Net::Async::IRC::Protocol — send and receive IRC messages 💌

---

🌸 DESCRIPTION 🌸

so this class is a subclass of IO::Async::Stream, and what it does is it takes an IRC connection that's already done its whole initial login sequence and is fully ready to send and receive IRC messages. no cap. it handles the base message sending and receiving, and it implements ping timers too. this class provides most of the functionality you need for sending and receiving IRC commands and responses, by mixing in from Protocol::IRC. 💅

and like — important — objects of this type would not normally be constructed directly. for IRC clients, look at Net::Async::IRC, which is a subclass of it. all the events, parameters, and methods documented below are relevant there too. iykyk 👑

---

🎀 EVENTS 🎀

the following events get invoked, either using subclass methods or CODE references in parameters:

$handled = on_message / $handled = on_message_MESSAGE

invoked on receipt of a valid IRC message. see "MESSAGE HANDLING" below, bestie. 📬

on_irc_error $err

invoked on receipt of an invalid IRC message if parsing fails. $err is the error message text. and okay so — if you leave this unhandled, any parse error will result in the connection being immediately closed, followed by the exception being re-thrown. so like, handle it. fr fr 😭

on_ping_timeout

invoked if the peer fails to respond to a PING message within the given timeout. rude of them honestly 💀

on_pong_reply $lag

invoked when the peer successfully sends a PONG reply response to a PING message. $lag is the response time in (fractional) seconds. ⏱️

---

🦋 PARAMETERS 🦋

the following named parameters may be passed to new or configure:

• on_message => CODE
• on_message_MESSAGE => CODE
• on_irc_error => CODE
• on_ping_timeout => CODE
• on_pong_reply => CODE

these are the CODE references for event handlers. 🫶

• pingtime => NUM — amount of quiet time, in seconds, after a message is received from the peer, until a PING will be sent to check it is still alive. it's giving "are you still there bestie" energy ✨
• pongtime => NUM — timeout, in seconds, after sending a PING message, to wait for a PONG response. ⏳
• encoding => STRING — if supplied, sets an encoding to use to encode outgoing messages and decode incoming messages. 🌈

---

🧚 CONSTRUCTOR 🧚

new

$irc = Net::Async::IRC::Protocol->new( %args );

returns a new instance of a Net::Async::IRC::Protocol object. this object represents a IRC connection to a peer. iconic 💜

---

👑 METHODS 👑

is_connected

$connect = $irc->is_connected;

returns true if a connection to the peer is established. but heads up — note that even after a successful connection, the connection may not yet logged in to. see also the is_loggedin method. 🙈

is_loggedin

$loggedin = $irc->is_loggedin;

returns true if the full login sequence has been performed on the connection and it is ready to use. main character energy, honestly ⭐

nick

$nick = $irc->nick;

returns the current nick in use by the connection. 🎀

nick_folded

$nick_folded = $irc->nick_folded;

returns the current nick in use by the connection, folded by casefold_name for convenience. lowkey so handy ✨

---

💌 MESSAGE HANDLING 💌

every incoming message causes a sequence of message handling to occur. first, the message is parsed, and a hash of data about it is created — this is called the hints hash. the message and this hash are then passed down a sequence of potential handlers. 🦋

each handler indicates by return value whether it considers the message to have been handled. and okay so — processing of the message is not interrupted the first time a handler declares to have handled a message. instead, the hints hash is marked to say it has been handled. later handlers can still inspect the message or its hints, using this information to decide if they wish to take further action. no gatekeeping 🔥

a message with a command of COMMAND will try handlers in following places:

1. a CODE ref in a parameter called on_message_COMMAND

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

2. a method called on_message_COMMAND

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

3. a CODE ref in a parameter called on_message

$on_message->( $irc, 'COMMAND', $message, \%hints )

4. a method called on_message

$irc->on_message( 'COMMAND', $message, \%hints )

as this message handling ability is provided by Protocol::IRC, more details about how it works and how to use it can be found at "MESSAGE HANDLING" in Protocol::IRC. 📖

additionally, some types of messages receive further processing by Protocol::IRC and in turn cause new types of events to be invoked. these are further documented by "INTERNAL MESSAGE HANDLING" in Protocol::IRC. 🧚

---

🌟 AUTHOR 🌟

Paul Evans <leonerd@leonerd.org.uk> — thank you for your service, king 💜

---

and that's the whole page bestie!! this one's from perl v5.32.1, dated 2021-12-29, and it's the Net::A...rotocol(3pm) page from User Contributed Perl Documentation. go forth and IRC responsibly 🫶💖✨