oracular (3) Protocol::IRC::Client.3pm.gz
NAME
"Protocol::IRC::Client" - IRC protocol handling for a client
DESCRIPTION
This mix-in class provides a layer of IRC message handling logic suitable for an IRC client. It builds
upon Protocol::IRC to provide extra message processing useful to IRC clients, such as handling inbound
server numerics.
It provides some of the methods required by "Protocol::IRC":
• isupport
INHERITED METHODS
The following methods, inherited from Protocol::IRC, are notable here as being particularly useful for a
client.
send_message
$irc->send_message( $message )
$irc->send_message( $command, { %args } )
$irc->send_message( $command, $prefix, @args )
See "send_message" in Protocol::IRC
METHODS
isupport
$value = $irc->isupport( $key )
Returns an item of information from the server's "005 ISUPPORT" lines. Traditionally IRC servers use
all-capital names for keys.
server_info
$info = $irc->server_info( $key )
Returns an item of information from the server's 004 line. $key should one of
• host
• version
• usermodes
• channelmodes
GATING MESSAGES
If messages with a gating disposition are received, extra processing is applied. Messages whose gating
effect is "more" are simply collected up by pushing the hints hash to an array. Added to this hash is the
command name itself, so that in the case of multiple message types (for example "WHOIS" replies) the
individual messages can still be identified.
When the effect of "done" or "fail" is eventually received, this collected array is passed as $data to a
handler in one of the following places:
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 places are tried; looking 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 )
For the following types of gate, the $data is further processed in the following way to provide extra
hints fields.
who
The hints hash will contain an extra key, "who", which will be an ARRAY ref containing the lines of the
WHO reply. Each line will be a HASH reference containing:
user_ident
user_host
user_server
user_nick
user_nick_folded
user_flags
names
The hints hash will contain an extra key, "names", which will be an ARRAY ref containing the usernames in
the channel. Each will be a HASH reference containing:
nick
flag
bans
The hints hash will contain an extra key, "bans", which will be an ARRAY ref containing the ban lines.
Each line will be 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 will contain an extra key, "motd", which will be an ARRAY ref containing the lines of the
MOTD.
whois
The hints hash will contain an extra key, "whois", which will be an ARRAY ref of entries that mostly
relate to the received "RPL_WHOIS*" numerics.
Each "RPL_WHOIS*" reply will be stripped of the standard hints hash keys, leaving whatever remains. Added
to this will be a key called "whois", whose value will be the command name, minus the leading
"RPL_WHOIS", and converted to lowercase.
join
No additional keys.
next_gate_future
$f = $client->next_gate_future( $gate, $target )
As an alternative to using the event handlers above, a client can instead obtain a Future that will
succeed or fail the next time a result on a given gate is received for a given target. This is often more
convenient to use in a client, as it represents the result of running a command.
If the gate completes successfully, then so will the future, yielding the same values as would be passed
to the "on_gate_done_GATE" event; namely that
( $message, $hints, $data ) = $f->get
If the gate fails, then so will the future, containing 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
The following messages are handled internally by "Protocol::IRC::Client".
CAP
This message takes a sub-verb as its second argument, and a list of capability names as its third. On
receipt of a "CAP" message, the verb is extracted and set as the "verb" hint, and the list capabilities
set as the keys of a hash given as the "caps" hint. These are then 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 involve channel modes. The raw list of channel modes is parsed into an array containing
one entry per affected piece of data. Each entry will contain at least a "type" key, indicating 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 provides a "mode" key, containing the mode character itself, and a "sense" key which
is an empty string, "+", or "-".
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 (by the
"prefix_mode2flag" method), "nick" and "nick_folded" store the user name affected.
"boolean" types do not create any extra keys.
COMMAND-SENDING METHODS
The following methods actually send IRC commands. Each is named after the underlying IRC command it
sends, using capital letters for methods that simply send that command. They all take 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 "NOTICE" command.
For convenience, a single "target" argument may be provided which will be renamed to "targets". If
"targets" is an ARRAY reference, it will be turned into a comma-separated string.
REQUIRED METHODS
As this class is an abstract base class, a concrete implementation must provide the following methods to
complete it and make it useable.
new_future
$f = $client->new_future
Returns a new Future instance or subclass thereof.
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>