Net::Async::IRC - Asynchronous IRC client
Net::Async::IRC
TODO
This object class implements an asynchronous IRC client, for use in programs based on IO::Async.
This documentation is very much still in a state of TODO; it is being released now in the hope it is currently somewhat useful, with the intention of putting more work into both the code and its documentation at some near point in the future.
Returns a new instance of a Net::Async::IRC object. This object represents a connection to a single IRC server. As it is a subclass of IO::Async::Stream its constructor takes any arguments for that class, in addition to the parameters named below.
IO::Async::Stream
The following named parameters may be passed to new or configure:
new
configure
A CODE reference to the generic message handler; see MESSAGE HANDLING below.
MESSAGE HANDLING
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.
on_message_
Amount of quiet time, in seconds, after a message is received from the server, until a PING will be sent to check it is still alive.
PING
Timeout, in seconds, after sending a PING message, to wait for a PONG response.
PONG
A CODE reference to invoke if the server fails to respond to a PING message within the given timeout.
$on_ping_timeout->( $irc )
A CODE reference to invoke when the server successfully sends a PONG in response of a PING message.
$on_pong_reply->( $irc, $lag )
Where $lag is the response time in (fractional) seconds.
$lag
Connection details. See also connect, login.
connect
login
If user is not supplied, it will default to either $ENV{LOGNAME} or the current user's name as supplied by getpwuid().
user
$ENV{LOGNAME}
getpwuid()
If unconnected, changing these properties will set the default values to use when logging in.
If logged in, changing the nick property is equivalent to calling set_nick. Changing the other properties will not take effect until the next login.
nick
set_nick
If supplied, sets an encoding to use to encode outgoing messages and decode incoming messages.
Returns true if a connection to the server is established. Note that even after a successful connection, the server may not yet logged in to. See also the is_loggedin method.
is_loggedin
Returns true if the server has been logged in to.
Connects to the IRC server. This method does not perform the complete IRC login sequence; for that see instead the login method.
Hostname of the IRC server.
Optional. Port number or service name of the IRC server. Defaults to 6667.
Continuation to invoke once the connection has been established. Usually used by the login method to perform the actual login sequence.
$on_connected->( $irc )
Continuation to invoke in the case of an error preventing the connection from taking place.
$on_error->( $errormsg )
Any other arguments are passed into the underlying IO::Async::Loop connect method.
IO::Async::Loop
Logs in to the IRC network, connecting first using the connect method if required. Takes the following named arguments:
IRC connection details. Defaults can be set with the new or configure methods.
Server password to connect with.
A continuation to invoke once login is successful.
$on_login->( $irc )
Any other arguments that are passed, are forwarded to the connect method if it is required; i.e. if login is invoked when not yet connected to the server.
Sends a message to the server from the given Net::Async::IRC::Message object.
Net::Async::IRC::Message
Sends a message to the server directly from the given arguments.
Shortcut to sending a CTCP message. Sends a PRIVMSG to the given target, containing the given verb and argument string.
Shortcut to sending a CTCP reply. As send_ctcp but using a NOTICE instead.
send_ctcp
Returns true if the given nick refers to that in use by the connection.
Returns an item of information from the server's 004 line. $key should one of
004
$key
host
version
usermodes
channelmodes
Returns an item of information from the server's 005 ISUPPORT lines. Traditionally IRC servers use all-capital names for keys.
005 ISUPPORT
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.
sort()
Similar to cmp_prefix_flags, but compares channel occupant MODE command flags.
cmp_prefix_flags
MODE
Converts a channel occupant MODE flag (such as o) into a name prefix flag (such as @).
o
@
The inverse of prefix_mode2flag.
prefix_mode2flag
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.
$name
CASEMAPPING
ISUPPORT
eq
Useful for use in hash keys or similar.
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.
channel
CHANTYPES
Returns the current nick in use by the connection.
Returns the current nick in use by the connection, folded by casefold_name for convenience.
casefold_name
Requests to change the nick. If unconnected, the change happens immediately to the stored defaults. If logged in, sends a NICK command to the server, which may suceed or fail at a later point.
NICK
Every incoming message from the IRC server 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:
COMMAND
A CODE ref in a parameter called on_message_COMMAND
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
$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 class itself. These may cause other hints hash keys to be created, or to invoke other handler methods. These are documented below.
The following keys will be present in any message hint hash:
Initially false. Will be set to true the first time a handler returns a true value.
Values split from the message prefix; see the Net::Async::IRC::Message prefix_split method.
prefix_split
Usually the prefix nick, or the hostname in case the nick isn't defined (usually on server messages).
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.
named_args
If the message type defines a target_name:
target_name
target_type => STRING
Either channel or user, as returned by classify_name.
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..
_nick
_name
_folded
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 Net::Async::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.
synthesized
If any handler of the synthesized message returns true, then this marks the primary message handled as well.
These message 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:
type
The mode relates to a list; bans, invites, etc..
The mode sets a value about the channel
The mode is a simple boolean flag about the channel
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 -.
mode
sense
+
-
For list and value types, the value key gives the actual list entry or value being set.
list
value
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.
occupant
flag
nick_folded
boolean types do not create any extra keys.
boolean
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.
NOTICE
PRIVMSG
text
ctcp
ctcpreply
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.
is_notice
target_name_folded
target_type
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.
target_is_me
For the channel target type, it will contain a restriction key containing the channel message restriction, if present.
restriction
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.
ctcp_verb
ctcp_args
VERB
CTCP
A CODE ref in a parameter called on_message_CTCP_VERB
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
$on_message_CTCP->( $irc, 'VERB', $message, \%hints )
A method called on_message_CTCP
$irc->on_message_CTCP( 'VERB', $message, \%hintss )
$on_message->( $irc, 'CTCP VERB', $message, \%hints )
$irc->on_message( 'CTCP VERB', $message, \%hints )
These messages will be collected up, per channel, and formed into a single synthesized event called who.
who
Its 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:
These messages will be collected up, per channel, and formed into a single synthesized event called names.
names
Its 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:
These messages will be collected up, per channel, and formed into a single synthesized event called bans.
bans
Its 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:
User mask of the ban
Nickname of the user who set the ban
UNIX timestamp the ban was created
These messages will be collected up into a synthesized event called motd.
motd
Its hints hash will contain an extra key, motd, which will be an ARRAY ref containing the lines of the MOTD.
http://tools.ietf.org/html/rfc2812 - Internet Relay Chat: Client Protocol
Paul Evans <leonerd@leonerd.org.uk>
To install Net::Async::IRC, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::Async::IRC
CPAN shell
perl -MCPAN -e shell install Net::Async::IRC
For more information on module installation, please visit the detailed CPAN module installation guide.