NAME

Net::Async::IRC::Protocol - send and receive IRC messages

DESCRIPTION

This subclass of IO::Async::Protocol::LineStream implements an established IRC connection that has already completed its inital login sequence and is ready to send and receive IRC messages. It handles base message sending and receiving, and implements ping timers.

Objects of this type would not normally be constructed directly. For IRC clients, see Net::Async::IRC which is a subclass of it. All the events, parameters, and methods documented below are relevant there.

CONSTRUCTOR

$irc = Net::Async::IRC::Protocol->new( %args )

Returns a new instance of a Net::Async::IRC::Protocol object. This object represents a IRC connection to a peer. As it is a subclass of IO::Async::Protocol::LineStream its constructor takes any arguments for that class, in addition to the parameters named below.

PARAMETERS

The following named parameters may be passed to new or configure:

on_message => CODE

A CODE reference to the generic message handler; see MESSAGE HANDLING below.

on_message_* => CODE

Any parameter whose name starts with on_message_ can be installed as a handler for a specific message, in preference to the generic handler. See MESSAGE HANDLING.

pingtime => NUM

Amount of quiet time, in seconds, after a message is received from the peer, until a PING will be sent to check it is still alive.

pongtime => NUM

Timeout, in seconds, after sending a PING message, to wait for a PONG response.

on_ping_timeout => CODE

A CODE reference to invoke if the peer fails to respond to a PING message within the given timeout.

 $on_ping_timeout->( $irc )

on_pong_reply => CODE

A CODE reference to invoke when the peer successfully sends a PONG in response of a PING message.

 $on_pong_reply->( $irc, $lag )

Where $lag is the response time in (fractional) seconds.

encoding => STRING

If supplied, sets an encoding to use to encode outgoing messages and decode incoming messages.

METHODS

$connect = $irc->is_connected

Returns true if a connection to the peer is established. Note that even after a successful connection, the connection may not yet logged in to. See also the is_loggedin method.

$loggedin = $irc->is_loggedin

Returns true if the full login sequence has been performed on the connection and it is ready to use.

$irc->send_message( $message )

Sends a message to the peer from the given Protocol::IRC::Message object.

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

Sends a message to the peer directly from the given arguments.

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

$irc->send_ctcprely( $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.

As well as the actual ISUPPORT values set by the server, a number of derived values are also calculated. Their names are all lowercase and contain underscores, to distinguish them from the uppercase names without underscores that the server usually sets.

prefix_modes => STRING

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

prefix_flags => STRING

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

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 ]

casemap_1459 => BOOLEAN

True if the CASEMAPPING parameter is not ascii; i.e. it is some form of RFC 1459 mapping

casemap_1459_strict => BOOLEAN

True if the CASEMAPPING parameter is exactly strict-rfc1459

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

$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 = $irc->cmp_prefix_modes( $lhs, $rhs )

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

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

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

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

The inverse of prefix_mode2flag.

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

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

$nick = $irc->nick

Returns the current nick in use by the connection.

$nick_folded = $irc->nick_folded

Returns the current nick in use by the connection, folded by casefold_name for convenience.

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

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

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:

A CODE ref in a parameter called on_message_COMMAND

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

A method called on_message_COMMAND

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

A CODE ref in a parameter called on_message

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

A method called on_message

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

Certain commands are handled internally by methods on the base Net::Async::IRC::Protocol class itself. These may cause other hints hash keys to be created, or to invoke other handler methods. These are documented below.

Message Hints

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.

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

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.

A CODE ref in a parameter called on_message_CTCP_VERB

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

A method called on_message_CTCP_VERB

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

A CODE ref in a parameter called on_message_CTCP

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

A method called on_message_CTCP

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