/ 
AnyEvent-IRC-0.7
River stage one • 7 direct dependents • 8 total dependents
/ AnyEvent::IRC::Client

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\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;

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.

part $kicked_nick $channel $is_myself $msg

Emitted when $kicked_nick is KICKed from the channel $channel. $is_myself is true if yourself are the one who got KICKed. $msg is the PART 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.

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.

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 $prefix $command @params

Is emitted everytime some command is sent.

debug_recv $ircmsg

Is emitted everytime some command was received.

METHODS

new

This constructor takes no arguments.

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

All keys, except nick are optional.

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.

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.

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.

is_my_nick ($string)

This returns true if $string is the nick of ourself.

registered ()

Returns a true value when the connection has been registered successful and you can send commands.

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

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.

send_msg (...)

See also AnyEvent::IRC::Connection.

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' });
clear_srv_queue

Clears the server send queue.

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.

clear_chan_queue ($channel)

Clears the channel queue of the channel $channel.

enable_ping ($interval, $cb)

This method enables a periodical ping to the server with an interval of $interval seconds. If no PONG 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 registered event).

lower_case ($str)

Converts the given string to lowercase according to CASEMAPPING setting given by the IRC server. If none was sent, the default - rfc1459 - will be used.

eq_str ($str1, $str2)

This function compares two strings, whether they are describing the same IRC entity. They are lower cased by the networks case rules and compared then.

isupport ([$key])

Provides access to the ISUPPORT variables sent by the IRC server. If $key is given this method will return its value only, otherwise a hashref with all values is returned

split_nick_mode ($prefixed_nick)

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.

NOTE: If you feed in a prefixed ident ('@elmex!elmex@fofofof.de') you get 3 values out actually: the mode map, the nickname and the ident, otherwise the 3rd value is undef.

map_prefix_to_mode ($prefix)

Maps the nick prefix (eg. '@') to the corresponding mode (eg. 'o'). Returns undef if no such prefix exists (on the connected server).

map_mode_to_prefix ($mode)

Maps the nick mode (eg. 'o') to the corresponding prefix (eg. '@'). Returns undef if no such mode exists (on the connected server).

available_nick_modes ()

Returns a list of possible modes on this IRC server. (eg. 'o' for op).

is_channel_name ($string)

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 ISUPPORT is checked for that too.

nick_ident ($nick)

This method returns the whole ident of the $nick if the informations is available. If the nick's ident hasn't been seen yet, undef is returned.

ctcp_auto_reply ($ctcp_command, @msg) =item ctcp_auto_reply ($ctcp_command, $coderef)

This method installs an auto-reply for the reception of the $ctcp_command via PRIVMSG, @msg will be used as argument to the encode_ctcp function of the AnyEvent::IRC::Util package. The replies will be sent with the NOTICE IRC 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. CTCP PING reply generation. The arguments will be the same arguments that the ctcp event callbacks get. (See also ctcp event description above). The return value of the called subroutine should be a list of arguments for encode_ctcp.

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]
});

EXAMPLES

See samples/anyeventirccl and other samples in samples/ for some examples on how to use AnyEvent::IRC::Client.

AUTHOR

Robin Redeker, <elmex@ta-sa.org>

SEE ALSO

AnyEvent::IRC::Connection

RFC 1459 - Internet Relay Chat: Client Protocol

COPYRIGHT & LICENSE

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