A highlevel irc connection
use AnyEvent;
use AnyEvent::IRC::Client;
my $c = AnyEvent->condvar;
my $timer;
my $con = new AnyEvent::IRC::Client;
$con->reg_cb (connect => sub {
my ($con, $err) = @_;
if (defined $err) {
warn "connect error: $err\n";
return;
}
});
$con->reg_cb (registered => sub { print "I'm in!\n"; });
$con->reg_cb (disconnect => sub { print "I'm out!\n"; $c->broadcast });
$con->reg_cb (
sent => sub {
my ($con) = @_;
if ($_[2] eq 'PRIVMSG') {
print "Sent message!\n";
$timer = AnyEvent->timer (
after => 1,
cb => sub {
undef $timer;
$con->disconnect ('done')
}
);
}
}
);
$con->send_srv (
PRIVMSG => 'elmex',
"Hello there I'm the cool AnyEvent::IRC test script!"
);
$con->connect ("localhost", 6667, { nick => 'testbot' });
$c->wait;
$con->disconnect;
AnyEvent::IRC::Client is a (nearly) highlevel client connection, that manages all the stuff that noone wants to implement again and again when handling with \s-1IRC\s0. For example it PONGs the server or keeps track of the users on a channel.
This module also implements the \s-1ISUPPORT\s0 (command 005) extension of the \s-1IRC\s0 protocol (see http://www.irc.org/tech_docs/005.html) and will enable the \s-1NAMESX\s0 and \s-1UHNAMES\s0 extensions when supported by the server.
Also \s-1CTCP\s0 support is implemented, all \s-1CTCP\s0 messages will be decoded and events for them will be generated. You can configure auto-replies to certain \s-1CTCP\s0 commands with the \*(C`ctcp_auto_reply\*(C' method, or you can generate the replies yourself.
The case insensitivity of channel names and nicknames can lead to headaches when dealing with \s-1IRC\s0 in an automated client which tracks channels and nicknames.
I tried to preserve the case in all channel and nicknames AnyEvent::IRC::Client passes to his user. But in the internal structures I'm using lower case for the channel names.
The returned hash from \*(C`channel_list\*(C' for example has the lower case of the joined channels as keys.
But I tried to preserve the case in all events that are emitted. Please keep this in mind when handling the events.
For example a user might joins #TeSt and parts #test later.
The following events are emitted by AnyEvent::IRC::Client. Use \*(C`reg_cb\*(C' as described in Object::Event to register to such an event.
Emitted when the connection got successfully registered and the end of the \s-1MOTD\s0 (\s-1IRC\s0 command 376 or 422 (No \s-1MOTD\s0 file found)) was seen, so you can start sending commands and all \s-1ISUPPORT/PROTOCTL\s0 handshaking has been done. Emitted when @nicks are added to the channel $channel, this happens for example when someone JOINs a channel or when you get a \s-1RPL_NAMREPLY\s0 (see \s-1RFC1459\s0). $msg is the \s-1IRC\s0 message hash that as returned by \*(C`parse_irc_msg\*(C'. Emitted when @nicks are removed from the channel $channel, happens for example when they \s-1PART\s0, \s-1QUIT\s0 or get KICKed. $msg is the \s-1IRC\s0 message hash that as returned by \*(C`parse_irc_msg\*(C' or undef if the reason for the removal was a disconnect on our end. Emitted when a nickname on a channel changes. This is emitted when a \s-1NICK\s0 change occurs from $old_nick to $new_nick give the application a chance to quickly analyze what channels were affected. $is_myself is true when yourself was the one who changed the nick. This event is emitted when the (user) mode (eg. op status) of an occupant of a channel changes. $dest is the nickname on the $channel who's mode was updated. This is emitted when the topic for a channel is discovered. $channel is the channel for which $topic is the current topic now. Which is set by $who. $who might be undefined when it's not known who set the channel topic. Whenever the user and host of $nick has been determined or a change happened this event is emitted. Emitted when $nick enters the channel $channel by JOINing. $is_myself is true if yourself are the one who JOINs. Emitted when $nick PARTs the channel $channel. $is_myself is true if yourself are the one who PARTs. $msg is the \s-1PART\s0 message. Emitted when $kicked_nick is KICKed from the channel $channel by $kicker_nick. $is_myself is true if yourself are the one who got KICKed. $msg is the \s-1KICK\s0 message. Emitted when $old_nick is renamed to $new_nick. $is_myself is true when yourself was the one who changed the nick. Emitted whenever a presence/away status change for you was detected. $bool is true if you are now away, or false/undef if you are not away anymore. You can change your away status by emitting the \*(C`AWAY\*(C' \s-1IRC\s0 command: $cl->send_srv (AWAY => "I'm not here right now"); Or reset it: $cl->send_srv ('AWAY'); Emitted when a \s-1CTCP\s0 message was found in either a \s-1NOTICE\s0 or \s-1PRIVMSG\s0 message. $tag is the \s-1CTCP\s0 message tag. (eg. \*(L"\s-1PING\s0\*(R", \*(L"\s-1VERSION\s0\*(R", ...). $msg is the \s-1CTCP\s0 message and $type is either \*(L"\s-1NOTICE\s0\*(R" or \*(L"\s-1PRIVMSG\s0\*(R". $src is the source nick the message came from. $target is the target nickname (yours) or the channel the ctcp was sent on. Emitted when a \s-1CTCP\s0 message was found in either a \s-1NOTICE\s0 or \s-1PRIVMSG\s0 message. $tag is the \s-1CTCP\s0 message tag (in lower case). (eg. \*(L"ping\*(R", \*(L"version\*(R", ...). $msg is the \s-1CTCP\s0 message and $type is either \*(L"\s-1NOTICE\s0\*(R" or \*(L"\s-1PRIVMSG\s0\*(R". $src is the source nick the message came from. $target is the target nickname (yours) or the channel the ctcp was sent on. Whenever a locally initiated \s-1DCC\s0 request is made this event is emitted after the listening socket has been setup. $id is the \s-1DCC\s0 connection \s-1ID\s0. $dest and $type are the destination and type of the \s-1DCC\s0 request. $local_ip is the $local_ip argument passed to \*(C`start_dcc\*(C' or the \s-1IP\s0 the socket is bound to. $local_port is the \s-1TCP\s0 port is the socket is listening on. Whenever we receive a \s-1DCC\s0 offer from someone else this event is emitted. $id is the \s-1DCC\s0 connection \s-1ID\s0, $src is his nickname, $type is the \s-1DCC\s0 type in lower cases (eg. 'chat'). $arg is the \s-1DCC\s0 type argument. $addr is the \s-1IP\s0 address we can reach him at in \s-1ASCII\s0 encoded human readable form (eg. something like \*(L"127.0.0.1\*(R"). And $port is the \s-1TCP\s0 port we have to connect to. To answer to his request you can just call \*(C`dcc_accept\*(C' with the $id. When the locally listening \s-1DCC\s0 socket has received a connection this event is emitted. $id and $type are the \s-1DCC\s0 connection \s-1ID\s0 and type of the \s-1DCC\s0 request. $hdl is a pre-configured AnyEvent::Handle object, which you only need to care about in case you want to implement your own \s-1DCC\s0 protocol. (This event has the on_error and on_eof events pre-configured to cleanup the data structures in this connection). Whenever we accepted a \s-1DCC\s0 offer and connected by using \*(C`dcc_accept\*(C' this event is emitted. $id is the \s-1DCC\s0 connection \s-1ID\s0. $type is the dcc type in lower case. $hdl is the AnyEvent::Handle object of the connection (see also \*(C`dcc_accepted\*(C' above). This event is emitted whenever a \s-1DCC\s0 connection is terminated. $id and $type are the \s-1DCC\s0 connection \s-1ID\s0 and type of the \s-1DCC\s0 request. $reason is a human readable string indicating the reason for the end of the \s-1DCC\s0 request. This event is emitted for a \s-1DCC\s0 \s-1CHAT\s0 message. $id is the \s-1DCC\s0 connection \s-1ID\s0 we received the message on. And $msg is the message he sent us. Emitted when the nickname $nick QUITs with the message $msg. Emitted for \s-1NOTICE\s0 and \s-1PRIVMSG\s0 where the target $channel is a channel. $ircmsg is the original \s-1IRC\s0 message hash like it is returned by \*(C`parse_irc_msg\*(C'. The last parameter of the $ircmsg will have all \s-1CTCP\s0 messages stripped off. Emitted for \s-1NOTICE\s0 and \s-1PRIVMSG\s0 where the target $nick (most of the time you) is a nick. $ircmsg is the original \s-1IRC\s0 message hash like it is returned by \*(C`parse_irc_msg\*(C'. The last parameter of the $ircmsg will have all \s-1CTCP\s0 messages stripped off. Emitted when any error occurs. $code is the 3 digit error id string from \s-1RFC\s0 1459 or the string '\s-1ERROR\s0'. $message is a description of the error. $ircmsg is the complete error irc message. You may use AnyEvent::IRC::Util::rfc_code_to_name to convert $code to the error name from the \s-1RFC\s0 2812. eg.: rfc_code_to_name ('471') => 'ERR_CHANNELISFULL' \s-1NOTE:\s0 This event is also emitted when a '\s-1ERROR\s0' message is received. Is emitted everytime some command is sent. Is emitted everytime some command was received.
This is the constructor of a AnyEvent::IRC::Client object, which stands logically for a client connected to \s-1ONE\s0 \s-1IRC\s0 server. You can reuse it and call \*(C`connect\*(C' once it disconnected. \s-1NOTE:\s0 You are free to use the hash member \*(C`heap\*(C' to store any associated data with this object. For example retry timers or anything else. %args may contain these options:
If this option is enabled an initial \*(C`WHOIS\*(C' command is sent to your own \s-1NICKNAME\s0 to determine your own ident. See also the method \*(C`nick_ident\*(C'. This is necessary to ensure that the information about your own nickname is available as early as possible for the \*(C`send_long_message\*(C' method. $bool is \*(C`false\*(C' by default.
This method does the same as the \*(C`connect\*(C' method of AnyEvent::Connection, but if the $info parameter is passed it will automatically register with the \s-1IRC\s0 server upon connect for you, and you won't have to call the \*(C`register\*(C' method yourself. If $info only contains the timeout value it will not automatically connect, this way you can pass a custom connect timeout value without having to register. The keys of the hash reference you can pass in $info are: nick - the nickname you want to register as user - your username real - your realname password - the server password timeout - the TCP connect timeout All keys, except \*(C`nick\*(C' are optional. Sends the \s-1IRC\s0 registration commands \s-1NICK\s0 and \s-1USER\s0. If $server_pass is passed also a \s-1PASS\s0 command is generated. \s-1NOTE:\s0 If you passed the nick, user, etc. already to the \*(C`connect\*(C' method you won't need to call this method, as AnyEvent::IRC::Client will do that for you. This method lets you modify the nickname renaming mechanism when registering the connection. $callback is called with the current nickname as first argument when a \s-1ERR_NICKNAMEINUSE\s0 or \s-1ERR_UNAVAILRESOURCE\s0 error occurs on login. The return value of $callback will then be used to change the nickname. If $callback is not defined the default nick change callback will be used again. The default callback appends '_' to the end of the nickname supplied in the \*(C`register\*(C' routine. If the callback returns the same nickname that was given it the connection will be terminated. Returns the current nickname, under which this connection is registered at the \s-1IRC\s0 server. It might be different from the one that was passed to \*(C`register\*(C' as a nick-collision might happened on login. This returns true if $string is the nick of ourself. Returns a true value when the connection has been registered successful and you can send commands. Without $channel parameter: This returns a hash reference. The keys are the currently joined channels in lower case. The values are hash references which contain the joined nicks as key (\s-1NOT\s0 in lower case!) and the nick modes as values (as returned from \*(C`nick_modes ()\*(C'). If the $channel parameter is given it returns the hash reference of the channel occupants or undef if the channel does not exist. This returns the mode map of the $nick on $channel. Returns undef if the channel isn't joined or the user is not on it. Returns a hash reference with the modes the user has as keys and 1's as values. See also AnyEvent::IRC::Connection. This function sends an \s-1IRC\s0 message that is constructed by \*(C`mk_msg (undef, $command, @params)\*(C' (see AnyEvent::IRC::Util). If the \*(C`registered\*(C' event has \s-1NOT\s0 yet been emitted the messages are queued until that event is emitted, and then sent to the server. \s-1NOTE:\s0 If you stop the registered event (with \*(C`stop_event\*(C', see Object::Event) in a callback registered to the \*(C`before_registered\*(C' event, the \*(C`send_srv\*(C' queue will \s-1NOT\s0 be flushed and \s-1NOT\s0 sent to the server! This allows you to simply write this: my $cl = AnyEvent::IRC::Client->new; $cl->connect ('irc.freenode.net', 6667, { nick => 'testbot' }); $cl->send_srv (PRIVMSG => 'elmex', 'Hi there!'); Instead of: my $cl = AnyEvent::IRC::Client->new; $cl->reg_cb ( registered => sub { $cl->send_msg (PRIVMSG => 'elmex', 'Hi there!'); } ); $cl->connect ('irc.freenode.net', 6667, { nick => 'testbot' }); Clears the server send queue. This function sends a message (constructed by \*(C`mk_msg (undef, $command, @params)\*(C' to the server, like \*(C`send_srv\*(C' only that it will queue the messages if it hasn't joined the channel $channel yet. The queued messages will be send once the connection successfully JOINed the $channel. $channel will be lowercased so that any case that comes from the server matches. (Yes, \s-1IRC\s0 handles upper and lower case as equal :-( Be careful with this, there are chances you might not join the channel you wanted to join. You may wanted to join #bla and the server redirects that and sends you that you joined #blubb. You may use \*(C`clear_chan_queue\*(C' to remove the queue after some timeout after joining, so that you don't end up with a memory leak. Clears the channel queue of the channel $channel. As \s-1IRC\s0 only allows 512 byte blocks of messages and sometimes your messages might get longer, you have a problem. This method will solve your problem: This method can be used to split up long messages into multiple commands. $cmd and @params are the \s-1IRC\s0 command and it's first parameters, except the last one: the $msg. $msg can be a Unicode string, which will be encoded in $encoding before sending. If you want to send a \s-1CTCP\s0 message you can encode it in the $cmd by appending the \s-1CTCP\s0 command with a "\001". For example if you want to send a \s-1CTCP\s0 \s-1ACTION\s0 you have to give this $cmd: $cl->send_long_message (undef, 0, "PRIVMSG\001ACTION", "#test", "rofls"); $encoding can be undef if you don't need any recoding of $msg. But in case you want to send Unicode it is necessary to determine where to split a message exactly, to not break the encoding. Please also note that the \*(C`nick_ident\*(C' for your own nick is necessary to compute this. To ensure best performance as possible use the \*(C`send_initial_whois\*(C' option if you want to use this method. But note that this method might not work 100% correct and you might still get at least partially chopped off lines if you use \*(C`send_long_message\*(C' before the \*(C`WHOIS\*(C' reply to \*(C`send_initial_whois\*(C' arrived. To be on the safest side you might want to wait until that initial \*(C`WHOIS\*(C' reply arrived. The return value of this method is the list of the actually sent lines (but without encoding applied). This method enables a periodical ping to the server with an interval of $interval seconds. If no \s-1PONG\s0 was received from the server until the next interval the connection will be terminated or the callback in $cb will be called. ($cb will have the connection object as it's first argument.) Make sure you call this method after the connection has been established. (eg. in the callback for the \*(C`registered\*(C' event). Converts the given string to lowercase according to \s-1CASEMAPPING\s0 setting given by the \s-1IRC\s0 server. If none was sent, the default - rfc1459 - will be used. This function compares two strings, whether they are describing the same \s-1IRC\s0 entity. They are lower cased by the networks case rules and compared then. Provides access to the \s-1ISUPPORT\s0 variables sent by the \s-1IRC\s0 server. If $key is given this method will return its value only, otherwise a hashref with all values is returned This method splits the $prefix_nick (eg. '+elmex') up into the mode of the user and the nickname. This method returns 2 values: the mode map and the nickname. The mode map is a hash reference with the keys being the modes the nick has set and the values being 1. \s-1NOTE:\s0 If you feed in a prefixed ident ('@[email protected]') you get 3 values out actually: the mode map, the nickname and the ident, otherwise the 3rd value is undef. Maps the nick prefix (eg. '@') to the corresponding mode (eg. 'o'). Returns undef if no such prefix exists (on the connected server). Maps the nick mode (eg. 'o') to the corresponding prefix (eg. '@'). Returns undef if no such mode exists (on the connected server). Returns a list of possible modes on this \s-1IRC\s0 server. (eg. 'o' for op). This return true if $string is a channel name. It analyzes the prefix of the string (eg. if it is '#') and returns true if it finds a channel prefix. Those prefixes might be server specific, so \s-1ISUPPORT\s0 is checked for that too. This method returns the whole ident of the $nick if the information is available. If the nick's ident hasn't been seen yet, undef is returned. \s-1NOTE:\s0 If you want to rely on the \*(C`nick_ident\*(C' of your own nick you should make sure to enable the \*(C`send_initial_whois\*(C' option in the constructor. Returns a true value if you are away or undef if you are not away. This method installs an auto-reply for the reception of the $ctcp_command via \s-1PRIVMSG\s0, @msg will be used as argument to the \*(C`encode_ctcp\*(C' function of the AnyEvent::IRC::Util package. The replies will be sent with the \s-1NOTICE\s0 \s-1IRC\s0 command. If $coderef was given and is a code reference, it will called each time a $ctcp_command is received, this is useful for eg. \s-1CTCP\s0 \s-1PING\s0 reply generation. The arguments will be the same arguments that the \*(C`ctcp\*(C' event callbacks get. (See also \*(C`ctcp\*(C' event description above). The return value of the called subroutine should be a list of arguments for \*(C`encode_ctcp\*(C'. Currently you can only configure one auto-reply per $ctcp_command. Example: $cl->ctcp_auto_reply ('VERSION', ['VERSION', 'ScriptBla:0.1:Perl']);
$cl->ctcp_auto_reply ('PING', sub { my ($cl, $src, $target, $tag, $msg, $type) = @_; ['PING', $msg] }); This function will initiate a \s-1DCC\s0 \s-1TCP\s0 connection to $dest of type $type. It will setup a listening \s-1TCP\s0 socket on $local_port, or a random port if $local_port is undefined. $local_ip is the \s-1IP\s0 that is being sent to the receiver of the \s-1DCC\s0 connection. If it is undef the local socket will be bound to 0 (or \*(L"::\*(R" in case of IPv6) and $local_ip will probably be something like \*(L"0.0.0.0\*(R". It is always advisable to set $local_ip to a (from the \*(L"outside\*(R", what ever that might be) reachable \s-1IP\s0 Address. $timeout is the time in seconds after which the listening socket will be closed if the receiver didn't connect yet. The default is 300 (5 minutes). When the local listening socket has been setup the \*(C`dcc_ready\*(C' event is emitted. When the receiver connects to the socket the \*(C`dcc_accepted\*(C' event is emitted. And whenever a dcc connection is closed the \*(C`dcc_close\*(C' event is emitted. For canceling the \s-1DCC\s0 offer or closing the connection see \*(C`dcc_disconnect\*(C' below. The return value of this function will be the \s-1ID\s0 of the initiated \s-1DCC\s0 connection, which can be used for functions such as \*(C`dcc_disconnect\*(C', \*(C`send_dcc_chat\*(C' or \*(C`dcc_handle\*(C'. In case you want to withdraw a \s-1DCC\s0 offer sent by \*(C`start_dcc\*(C' or close a \s-1DCC\s0 connection you call this function. $id is the \s-1DCC\s0 connection \s-1ID\s0. $reason should be a human readable reason why you ended the dcc offer, but it's only used for local logging purposes (see \*(C`dcc_close\*(C' event). This will accept an incoming \s-1DCC\s0 request as received by the \*(C`dcc_request\*(C' event. The \*(C`dcc_connected\*(C' event will be emitted when we successfully connected. And the \*(C`dcc_close\*(C' event when the connection was disconnected. $timeout is the connection try timeout in seconds. The default is 300 (5 minutes).
See samples/anyeventirccl and other samples in samples/ for some examples on how to use AnyEvent::IRC::Client.
Robin Redeker, \*(C`<[email protected]>\*(C'
AnyEvent::IRC::Connection
\s-1RFC\s0 1459 - Internet Relay Chat: Client Protocol
Copyright 2006-2009 Robin Redeker, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.