Protoc...essage(3pm)

💖 Protocol::IRC::Message 💖

okay bestie, so Protocol::IRC::Message is the whole vibe here — it wraps up one single IRC message all cute and cosy in an object. That's it, that's the whole thing. It's Protocol::IRC::Message, part of the User Contributed Perl Documentation, and it's genuinely iconic, no cap. 🎀

---

✨ SYNOPSIS ✨

use Protocol::IRC::Message;

my $hello = Protocol::IRC::Message->new(
   "PRIVMSG",
   undef,
   "World",
   "Hello, world!"
);

printf "The command is %s and the final argument is %s\n",
   $hello->command, $hello->arg( -1 );

---

🌸 DESCRIPTION 🌸

so like. every object in this class is literally one (1) IRC message — either one you got from the server or one you're about to send to the server. Once you build one of these, it's immutable, periodt. You can't go changing it. But don't worry bestie, it hands you a whole lil toolkit of methods to peek at everything inside it. 💅

also, this class understands IRCv3 message tags. slay.

---

🦋 CONSTRUCTOR 🦋

new_from_line

$message = Protocol::IRC::Message->new_from_line( $line )

gives you back a fresh new Protocol::IRC::Message object, made by parsing the IRC line you hand it. this is the one you reach for most of the time when you wanna represent a message that just arrived from the server. 🫶

new

$message = Protocol::IRC::Message->new( $command, $prefix, @args )

gives you a new Protocol::IRC::Message object, initialised from the components you pass in. this is the one you'll usually use to build a message you're about to send to the server with stream_to_line. heads up tho — this message will contain no IRCv3 tags. 😌

new_from_named_args

$message = Protocol::IRC::Message->new_from_named_args( $command, %args )

returns a new Protocol::IRC::Message object, initialised from the named arguments you give it. important: the argument names must match the ones required by the given command. no improvising, bestie. 💀

new_with_tags

$mesage = Protocol::IRC::Message->new_with_tags( $command, \%tags, $prefix, @args )

returns a new Protocol::IRC::Message object, exactly like new — except this one also carries the IRCv3 tags you gave it. ✨

---

👑 METHODS 👑

STRING

$str = $message->STRING

$str = "$message"

returns a string representing the message — perfect for a debug message or whatever. note: this is not the same as the IRC wire form you'd send to the IRC server; for that, go look at stream_to_line. 👀

command

$command = $message->command

returns the command name or numeric that's stored in the message object.

command_name

$name = $message->command_name

for named commands, it returns the command name straight up. for server numeric replies, it returns the name of the numeric.

tags

$tags = $message->tags

returns a HASH reference holding the IRCv3 message tags. ⚠️ careful tho — this is a reference to the hash the object stores directly, so please don't go modifying it. that's the object's hash, not yours.

prefix

$prefix = $message->prefix

returns the line prefix stored in the object, or the empty string if none was supplied.

prefix_split

( $nick, $ident, $host ) = $message->prefix_split

splits the prefix into its nick, ident and host components. if the prefix contains only a hostname (like the server name does), the first two components come back as undef. 🙈

arg

$arg = $message->arg( $index )

returns the argument at the given index. it's just normal perl array indexing, so negative indices work exactly how you'd expect. 💅

args

@args = $message->args

returns a list containing all the message arguments. every last one.

stream_to_line

$line = $message->stream_to_line

returns a string suitable for sending the message to the IRC server. this is the wire form, bestie. 🌈

arg_names

$names = $message->arg_names

returns a HASH reference giving the details on how to parse named arguments for the command in this message.

it's a hash where the keys are the names of the arguments, and the values tell you how that argument gets derived from the plain positional arguments.

normally this method only gets called internally by the named_args method — but it's documented here for completeness, and in case extension modules wanna define parsing for new message types. iykyk.

each value should be one of these:

• String literal "pn" — the value is a string: the nickname given in the message prefix.
• NUMBER..NUMBER — the value is an ARRAY ref containing a list of all the numbered arguments between the given limits (inclusive). either or both limits may be negative, in which case they count backwards from the end.
• NUMBER — the value is the argument at that numeric index. can be negative to count backwards from the end.
• NUMBER@ — the value is the argument at that numeric index, same as NUMBER, except the result gets split on spaces and stored in an ARRAY ref.

arg_names (class method)

$names = Protocol::IRC::Message->arg_names( $command )

you can also call this as a class method by passing in the command name or numeric. that lets you inspect what arguments would be required or returned before a message object even exists. so useful honestly. ⭐

named_args

$args = $message->named_args

parses the arguments in the message according to the spec given by the arg_names method, and returns a hash of parsed arguments.

TODO: More complete documentation on the exact arg names/values per message type. (yes, that's straight from the source, bestie — it's on the list 💀)

gate_disposition

$disp = $message->gate_disposition

returns the "gating disposition" of the message. this defines how a reply message from the server combines with other messages in response to a command sent by the client.

the disposition is either undef, or a string made of a type symbol and a gate name. if it's defined, the symbol tells you what effect it has on the gate name:

• -GATE — adds more information to the response for that gate, but doesn't complete it yet.
• +GATE — completes the gate with a successful result.
• *GATE — completes the gate with a successful result, but only if the nick in the message prefix relates to the connection it's received on.
• !GATE — completes the gate with a failure result. 😭

---

💜 AUTHOR 💜

Paul Evans <leonerd@leonerd.org.uk>

---

and that's the whole page, bestie!! 🎀 this was Protocol::IRC::Message from the User Contributed Perl Documentation, perl v5.36.0, dated 2022-10-22 — go forth and slay those IRC messages, you absolute icon. 💖✨🦋👑