/ 
Protocol-IRC-0.13
River stage one • 1 direct dependent • 3 total dependents
/ Protocol::IRC::Client

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>