AnyEvent::IRC::Client(3pm) User Contributed Perl Documentation AnyEvent::IRC::Client(3pm)
NAME
AnyEvent::IRC::Client - A highlevel IRC connection
SYNOPSIS
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
";
return;
}
});
$con->reg_cb (registered => sub { print "I'm in!
"; });
$con->reg_cb (disconnect => sub { print "I'm out!
"; $c->broadcast });
$con->reg_cb (
sent => sub {
my ($con) = @_;
if ($_[2] eq 'PRIVMSG') {
print "Sent message!
";
$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;
DESCRIPTION
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 IRC. For example it PONGs the server or keeps track of the users on a channel.
This module also implements the ISUPPORT (command 005) extension of the IRC protocol (see http://www.irc.org/tech_docs/005.html) and will
enable the NAMESX and UHNAMES extensions when supported by the server.
Also CTCP support is implemented, all CTCP messages will be decoded and events for them will be generated. You can configure auto-replies
to certain CTCP commands with the "ctcp_auto_reply" method, or you can generate the replies yourself.
A NOTE TO CASE MANAGEMENT
The case insensitivity of channel names and nicknames can lead to headaches when dealing with IRC 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 "channel_list" 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.
EVENTS
The following events are emitted by AnyEvent::IRC::Client. Use "reg_cb" as described in Object::Event to register to such an event.
registered
Emitted when the connection got successfully registered and the end of the MOTD (IRC command 376 or 422 (No MOTD file found)) was seen,
so you can start sending commands and all ISUPPORT/PROTOCTL handshaking has been done.
channel_add => $msg, $channel, @nicks
Emitted when @nicks are added to the channel $channel, this happens for example when someone JOINs a channel or when you get a
RPL_NAMREPLY (see RFC1459).
$msg is the IRC message hash that as returned by "parse_irc_msg".
channel_remove => $msg, $channel, @nicks
Emitted when @nicks are removed from the channel $channel, happens for example when they PART, QUIT or get KICKed.
$msg is the IRC message hash that as returned by "parse_irc_msg" or undef if the reason for the removal was a disconnect on our end.
channel_change => $msg, $channel, $old_nick, $new_nick, $is_myself
Emitted when a nickname on a channel changes. This is emitted when a NICK 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.
channel_nickmode_update => $channel, $dest
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.
channel_topic => $channel, $topic, $who
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.
ident_change => $nick, $ident
Whenever the user and host of $nick has been determined or a change happened this event is emitted.
join => $nick, $channel, $is_myself
Emitted when $nick enters the channel $channel by JOINing. $is_myself is true if yourself are the one who JOINs.
part => $nick, $channel, $is_myself, $msg
Emitted when $nick PARTs the channel $channel. $is_myself is true if yourself are the one who PARTs. $msg is the PART message.
kick => $kicked_nick, $channel, $is_myself, $msg, $kicker_nick
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 KICK message.
nick_change => $old_nick, $new_nick, $is_myself
Emitted when $old_nick is renamed to $new_nick. $is_myself is true when yourself was the one who changed the nick.
away_status_change => $bool
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 "AWAY" IRC command:
$cl->send_srv (AWAY => "I'm not here right now");
Or reset it:
$cl->send_srv ('AWAY');
ctcp => $src, $target, $tag, $msg, $type
Emitted when a CTCP message was found in either a NOTICE or PRIVMSG message. $tag is the CTCP message tag. (eg. "PING", "VERSION",
...). $msg is the CTCP message and $type is either "NOTICE" or "PRIVMSG".
$src is the source nick the message came from. $target is the target nickname (yours) or the channel the ctcp was sent on.
"ctcp_$tag", => $src, $target, $msg, $type
Emitted when a CTCP message was found in either a NOTICE or PRIVMSG message. $tag is the CTCP message tag (in lower case). (eg. "ping",
"version", ...). $msg is the CTCP message and $type is either "NOTICE" or "PRIVMSG".
$src is the source nick the message came from. $target is the target nickname (yours) or the channel the ctcp was sent on.
dcc_ready => $id, $dest, $type, $local_ip, $local_port
Whenever a locally initiated DCC request is made this event is emitted after the listening socket has been setup.
$id is the DCC connection ID.
$dest and $type are the destination and type of the DCC request.
$local_ip is the $local_ip argument passed to "start_dcc" or the IP the socket is bound to.
$local_port is the TCP port is the socket is listening on.
dcc_request => $id, $src, $type, $arg, $addr, $port
Whenever we receive a DCC offer from someone else this event is emitted. $id is the DCC connection ID, $src is his nickname, $type is
the DCC type in lower cases (eg. 'chat'). $arg is the DCC type argument. $addr is the IP address we can reach him at in ASCII encoded
human readable form (eg. something like "127.0.0.1"). And $port is the TCP port we have to connect to.
To answer to his request you can just call "dcc_accept" with the $id.
dcc_accepted => $id, $type, $hdl
When the locally listening DCC socket has received a connection this event is emitted.
$id and $type are the DCC connection ID and type of the DCC request.
$hdl is a pre-configured AnyEvent::Handle object, which you only need to care about in case you want to implement your own DCC
protocol. (This event has the on_error and on_eof events pre-configured to cleanup the data structures in this connection).
dcc_connected => $id, $type, $hdl
Whenever we accepted a DCC offer and connected by using "dcc_accept" this event is emitted. $id is the DCC connection ID. $type is the
dcc type in lower case. $hdl is the AnyEvent::Handle object of the connection (see also "dcc_accepted" above).
dcc_close => $id, $type, $reason
This event is emitted whenever a DCC connection is terminated.
$id and $type are the DCC connection ID and type of the DCC request.
$reason is a human readable string indicating the reason for the end of the DCC request.
dcc_chat_msg => $id, $msg
This event is emitted for a DCC CHAT message. $id is the DCC connection ID we received the message on. And $msg is the message he sent
us.
quit => $nick, $msg
Emitted when the nickname $nick QUITs with the message $msg.
publicmsg => $channel, $ircmsg
Emitted for NOTICE and PRIVMSG where the target $channel is a channel. $ircmsg is the original IRC message hash like it is returned by
"parse_irc_msg".
The last parameter of the $ircmsg will have all CTCP messages stripped off.
privatemsg => $nick, $ircmsg
Emitted for NOTICE and PRIVMSG where the target $nick (most of the time you) is a nick. $ircmsg is the original IRC message hash like
it is returned by "parse_irc_msg".
The last parameter of the $ircmsg will have all CTCP messages stripped off.
error => $code, $message, $ircmsg
Emitted when any error occurs. $code is the 3 digit error id string from RFC 1459 or the string 'ERROR'. $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 RFC 2812. eg.:
rfc_code_to_name ('471') => 'ERR_CHANNELISFULL'
NOTE: This event is also emitted when a 'ERROR' message is received.
debug_send => $command, @params
Is emitted everytime some command is sent.
debug_recv => $ircmsg
Is emitted everytime some command was received.
METHODS
$cl = AnyEvent::IRC::Client->new (%args)
This is the constructor of a AnyEvent::IRC::Client object, which stands logically for a client connected to ONE IRC server. You can
reuse it and call "connect" once it disconnected.
NOTE: You are free to use the hash member "heap" to store any associated data with this object. For example retry timers or anything
else.
%args may contain these options:
send_initial_whois => $bool
If this option is enabled an initial "WHOIS" command is sent to your own NICKNAME to determine your own ident. See also the method
"nick_ident". This is necessary to ensure that the information about your own nickname is available as early as possible for the
"send_long_message" method.
$bool is "false" by default.
$cl->connect ($host, $port)
$cl->connect ($host, $port, $info)
This method does the same as the "connect" method of AnyEvent::Connection, but if the $info parameter is passed it will automatically
register with the IRC server upon connect for you, and you won't have to call the "register" method yourself.
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 "nick" are optional.
$cl->register ($nick, $user, $real, $server_pass)
Sends the IRC registration commands NICK and USER. If $server_pass is passed also a PASS command is generated.
NOTE: If you passed the nick, user, etc. already to the "connect" method you won't need to call this method, as AnyEvent::IRC::Client
will do that for you.
$cl->set_nick_change_cb ($callback)
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 ERR_NICKNAMEINUSE or ERR_UNAVAILRESOURCE 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 "register" routine.
If the callback returns the same nickname that was given it the connection will be terminated.
$cl->nick ()
Returns the current nickname, under which this connection is registered at the IRC server. It might be different from the one that was
passed to "register" as a nick-collision might happened on login.
$cl->is_my_nick ($string)
This returns true if $string is the nick of ourself.
$cl->registered ()
Returns a true value when the connection has been registered successful and you can send commands.
$cl->channel_list ()
$cl->channel_list ($channel)
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 (NOT in lower case!) and the nick modes as values (as returned from "nick_modes
()").
If the $channel parameter is given it returns the hash reference of the channel occupants or undef if the channel does not exist.
$cl->nick_modes ($channel, $nick)
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.
$cl->send_msg (...)
See also AnyEvent::IRC::Connection.
$cl->send_srv ($command, @params)
This function sends an IRC message that is constructed by "mk_msg (undef, $command, @params)" (see AnyEvent::IRC::Util). If the
"registered" event has NOT yet been emitted the messages are queued until that event is emitted, and then sent to the server.
NOTE: If you stop the registered event (with "stop_event", see Object::Event) in a callback registered to the "before_registered"
event, the "send_srv" queue will NOT be flushed and NOT 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' });
$cl->clear_srv_queue ()
Clears the server send queue.
$cl->send_chan ($channel, $command, @params)
This function sends a message (constructed by "mk_msg (undef, $command, @params)" to the server, like "send_srv" 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, IRC 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 "clear_chan_queue" to remove the queue after some timeout after
joining, so that you don't end up with a memory leak.
$cl->clear_chan_queue ($channel)
Clears the channel queue of the channel $channel.
my (@lines) = $cl->send_long_message ($encoding, $overhead, $cmd, @params, $msg)
As IRC 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 IRC 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 CTCP message you can encode it in the $cmd by appending the CTCP command with a "