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>