NAME

    Protocol::IRC - IRC protocol handling

DESCRIPTION

    This mix-in class provides a base layer of IRC message handling logic.
    It allows reading of IRC messages from a string buffer and dispatching
    them to handler methods on its instance.

    Protocol::IRC::Client provides an extension to this logic that may be
    more convenient for IRC client implementations. Much of the code
    provided here is still useful in client applications, so the reader
    should be familiar with both modules.

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. 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.

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

      1. A method called on_message_COMMAND

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

      2. A method called on_message

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

    For server numeric replies, if the numeric reply has a known name, it
    will be attempted first at its known name, before falling back to the
    numeric if it was not handled. Unrecognised numerics will be attempted
    only at their numeric value.

    Because of the wide variety of messages in IRC involving various types
    of data the message handling specific cases for certain types of
    message, including adding extra hints hash items, or invoking extra
    message handler stages. These details are noted here.

    Many of these messages create new events; called synthesized messages.
    These are messages created by the Protocol::IRC object itself, to
    better represent some of the details derived from the primary ones from
    the server. These events all take lower-case command names, rather than
    capitals, and will have a synthesized key in the hints hash, set to a
    true value. These are dispatched and handled identically to regular
    primary events, detailed above.

    If any handler of the synthesized message returns true, then this marks
    the primary message handled as well.

    If a message is received that has a gating disposition, extra
    processing is applied to it before the processing above. The effect on
    its gate is given as a string (one of more, done, fail) to handlers in
    the following places:

      1. A method called on_message_gate_EFFECT_GATE

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

      2. A method called on_message_gate_EFFECT

       $irc->on_message_gate_EFFECT( 'GATE', $message, \%hints )

      3. A method called on_message_gate

       $irc->on_message_gate( 'EFFECT', 'GATE', $message, \%hints )

 Message Hints

    When messages arrive they are passed to the appropriate message
    handling method, which the implementation may define. As well as the
    message, a hash of extra information derived from or relating to the
    message is also given.

    The following keys will be present in any message hint hash:

    handled => BOOL

      Initially false. Will be set to true the first time a handler returns
      a true value.

    prefix_nick => STRING

    prefix_user => STRING

    prefix_host => STRING

      Values split from the message prefix; see the Protocol::IRC::Message
      prefix_split method.

    prefix_name => STRING

      Usually the prefix nick, or the hostname in case the nick isn't
      defined (usually on server messages).

    prefix_is_me => BOOL

      True if the nick mentioned in the prefix refers to this connection.

    Added to this set, will be all the values returned by the message's
    named_args method. Some of these values may cause yet more values to be
    generated.

    If the message type defines a target_name:

      * target_type => STRING

      Either channel or user, as returned by classify_name.

      * target_is_me => BOOL

      True if the target name is a user and refers to this connection.

    Any key whose name ends in _nick or _name will have a corresponding key
    added with _folded suffixed on its name, containing the value
    casefolded using casefold_name. This is for the convenience of string
    comparisons, hash keys, etc..

    Any of these keys that are not the prefix_name will additionally have a
    corresponding key with _is_me replacing the _nick or _name, containing
    the boolean result of calling the is_nick_me method on that name. This
    makes it simpler to detect commands or results affecting the user the
    connection represents.

METHODS

 on_read

       $irc->on_read( $buffer )

    Informs the protocol implementation that more bytes have been read from
    the peer. This method will modify the $buffer directly, and remove from
    it the prefix of bytes it has consumed. Any bytes remaining should be
    stored by the caller for next time.

    Any messages found in the buffer will be passed, in sequence, to the
    incoming_message method.

 incoming_message

       $irc->incoming_message( $message )

    Invoked by the on_read method for every incoming IRC message. This
    method implements the actual dispatch into various handler methods as
    described in the "MESSAGE HANDLING" section above.

    This method is exposed so that subclasses can override it, primarily to
    wrap extra logic before or after the main dispatch (e.g. for logging or
    other processing).

 send_message

    This method takes arguments in three different forms, depending on
    their number and type.

    If the first argument is a reference then it must contain a
    Protocol::IRC::Message instance which will be sent directly:

       $irc->send_message( $message )

    Otherwise, the first argument must be a plain string that gives the
    command name. If the second argument is a hash, it provides named
    arguments in a form similar to "new_from_named_args" in
    Protocol::IRC::Message, otherwise the remaining arguments must be the
    prefix string and other positional arguments, as plain strings:

       $irc->send_message( $command, { %args } )
    
       $irc->send_message( $command, $prefix, @args )

  Named Argument Mangling

    For symmetry with incoming message processing, this method applies some
    adjustment of named arguments for convenience of callers.

      * Callers may define a named argument of target; it will be renamed
      to target_name.

      * If a named argument of text is defined and an "encoder" exists, the
      argument value will be encoded using this encoder.

 send_ctcp

       $irc->send_ctcp( $prefix, $target, $verb, $argstr )

    Shortcut to sending a CTCP message. Sends a PRIVMSG to the given
    target, containing the given verb and argument string.

 send_ctcpreply

       $irc->send_ctcpreply( $prefix, $target, $verb, $argstr )

    Shortcut to sending a CTCP reply. As send_ctcp but using a NOTICE
    instead.

ISUPPORT-DRIVEN UTILITIES

    The following methods are controlled by the server information given in
    the ISUPPORT settings. They use the isupport required method to query
    the information required.

 casefold_name

       $name_folded = $irc->casefold_name( $name )

    Returns the $name, folded in case according to the server's CASEMAPPING
    ISUPPORT. Such a folded name will compare using eq according to whether
    the server would consider it the same name.

    Useful for use in hash keys or similar.

 cmp_prefix_flags

       $cmp = $irc->cmp_prefix_flags( $lhs, $rhs )

    Compares two channel occupant prefix flags, and returns a signed
    integer to indicate which of them has higher priviledge, according to
    the server's ISUPPORT declaration. Suitable for use in a sort()
    function or similar.

 cmp_prefix_modes

       $cmp = $irc->cmp_prefix_modes( $lhs, $rhs )

    Similar to cmp_prefix_flags, but compares channel occupant MODE command
    flags.

 prefix_mode2flag

       $flag = $irc->prefix_mode2flag( $mode )

    Converts a channel occupant MODE flag (such as o) into a name prefix
    flag (such as @).

 prefix_flag2mode

       $mode = $irc->prefix_flag2mode( $flag )

    The inverse of prefix_mode2flag.

 classify_name

       $classification = $irc->classify_name( $name )

    Returns channel if the given name matches the pattern of names allowed
    for channels according to the server's CHANTYPES ISUPPORT. Returns user
    if not.

 is_nick_me

       $me = $irc->is_nick_me( $nick )

    Returns true if the given nick refers to that in use by the connection.

INTERNAL MESSAGE HANDLING

    The following messages are handled internally by Protocol::IRC.

 PING

    PING messages are automatically replied to with PONG.

 NOTICE and PRIVMSG

    Because NOTICE and PRIVMSG are so similar, they are handled together by
    synthesized events called text, ctcp and ctcpreply. Depending on the
    contents of the text, and whether it was supplied in a PRIVMSG or a
    NOTICE, one of these three events will be created.

    In all cases, the hints hash will contain a is_notice key being true or
    false, depending on whether the original messages was a NOTICE or a
    PRIVMSG, a target_name key containing the message target name, a
    case-folded version of the name in a target_name_folded key, and a
    classification of the target type in a target_type key.

    For the user target type, it will contain a boolean in target_is_me to
    indicate if the target of the message is the user represented by this
    connection.

    For the channel target type, it will contain a restriction key
    containing the channel message restriction, if present.

    For normal text messages, it will contain a key text containing the
    actual message text.

    For either CTCP message type, it will contain keys ctcp_verb and
    ctcp_args with the parsed message. The ctcp_verb will contain the first
    space-separated token, and ctcp_args will be a string containing the
    rest of the line, otherwise unmodified. This type of message is also
    subject to a special stage of handler dispatch, involving the CTCP verb
    string. For messages with VERB as the verb, the following are tried.
    CTCP may stand for either ctcp or ctcpreply.

      1. A method called on_message_CTCP_VERB

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

      2. A method called on_message_CTCP

       $irc->on_message_CTCP( 'VERB', $message, \%hintss )

      3. A method called on_message

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

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.

 write

       $irc->write( $string )

    Requests the byte string to be sent to the peer

 encoder

       $encoder = $irc->encoder

    Optional. If supplied, returns an Encode object used to encode or
    decode the bytes appearing in a text field of a message. If set, all
    text strings will be returned, and should be given, as Unicode strings.
    They will be encoded or decoded using this object.

 invoke

       $result = $irc->invoke( $name, @args )

    Optional. If provided, invokes the message handling routine called
    $name with the given arguments. A default implementation is provided
    which simply attempts to invoke a method of the given name, or return
    false if no method of that name exists.

    If an implementation does override this method, care should be taken to
    ensure that methods are tested for and invoked if present, in addition
    to any other work the method wishes to perform, as this is the basis by
    which derived message handling works.

 isupport

       $value = $irc->isupport( $field )

    Should return the value of the given ISUPPORT field.

    As well as the all-capitals server-supplied fields, the following
    fields may be requested. Their names are all lowercase and contain
    underscores, to distinguish them from server-supplied fields.

    prefix_modes => STRING

      The mode characters from PREFIX (e.g. ohv)

    prefix_flags => STRING

      The flag characters from PREFIX (e.g. @%+)

    prefixflag_re => Regexp

      A precompiled regexp that matches any of the prefix flags

    prefix_map_m2f => HASH

      A map from mode characters to flag characters

    prefix_map_f2m => HASH

      A map from flag characters to mode characters

    chanmodes_list => ARRAY

      A 4-element array containing the split portions of CHANMODES;

       [ $listmodes, $argmodes, $argsetmodes, $boolmodes ]

    channame_re => Regexp

      A precompiled regexp that matches any string beginning with a channel
      prefix character in CHANTYPES.

 nick

       $nick = $irc->nick

    Should return the current nick in use by the connection.

 nick_folded

       $nick_folded = $irc->nick_folded

    Optional. If supplied, should return the current nick as case-folded by
    the casefold_name method. If not provided, this will be performed by
    case-folding the result from nick.

AUTHOR

    Paul Evans <leonerd@leonerd.org.uk>