NAME

Net::IRC - Perl interface to the Internet Relay Chat protocol

SYNOPSIS

use Net::IRC;

$irc = new Net::IRC;
$conn = $irc->newconn(Nick    => 'some_nick',
                      Server  => 'irc.ais.net',
                      Port    =>  6667,
                      Ircname => "The horses just don't gossip anymore.");
$irc->start;

DESCRIPTION

Welcome to Net::IRC, a work in progress. First intended to be a quick tool for writing an IRC script in Perl, Net::IRC has grown into a comprehensive Perl implementation of the IRC protocol (RFC 1459), supported and developed by several members of the EFnet IRC channel #perl.

SUMMARY

There are 4 component modules which make up Net::IRC:

• Net::IRC

  The wrapper for everything else, containing methods to generate Connection objects (see below) and a connection manager which does an event loop, reads available data from all currently open connections, and passes it off to the appropriate parser in a separate package. It's written and working, but still a bit unpolished.

• Net::IRC::Connection

  The big time sink on this project. Each Connection instance is a single connection to an IRC server. The module itself contains methods for every single IRC command available to users (Net::IRC isn't designed for writing servers, for obvious reasons), methods to set, retrieve, and call handler functions which the user can set (more on this later), and too many cute comments. Hey, what can I say, I was bored.

• Net::IRC::Event

  Kind of a struct-like object for storing info about things that the IRC server tells you (server responses, channel talk, joins and parts, et cetera). It records who initiated the event, who it affects, the event type, and any other arguments provided for that event. Incidentally, the only argument passed to a handler function.

• Net::IRC::DCC

  The analogous object to Connection.pm for connecting, sending and retrieving with the DCC protocol. This part, tirelessly written and tested by borys <borys@guistenal.newaygo.mi.us> is still under heavy construction. Wear your hard hat.

The central concept that Net::IRC is built around is that of handlers (or hooks, or callbacks, or whatever the hell you wanna call them). We tried to make it a completely event-driven model, a la Tk -- for every conceivable type of event that your client might see on IRC, you can give your program a custom subroutine to call. But wait, there's more! There are 3 levels of handler precedence:

• Default handlers

  Considering that they're hardwired into Net::IRC, these won't do much more than the bare minimum needed to keep the client listening on the server, with an option to print (nicely formatted, of course) what it hears to whatever filehandles you specify (STDOUT by default). These get called only when the user hasn't defined any of his own handlers for this event.

• User-definable global handlers

  The user can set up his own subroutines to replace the default actions for every IRC connection managed by your program. These only get invoked if the user hasn't set up a per-connection handler for the same event.

• User-definable per-connection handlers

  Simple: this tells a single connection what to do if it gets an event of this type. Supersedes global handlers if any are defined for this event.

And even better, you can choose to call your custom handlers before or after the default handlers instead of replacing them, if you wish. In short, it's not perfect, but it's about as good as you can get and still be documentable, given the sometimes horrendous complexity of the IRC protocol.

AUTHOR

• Conceived and initially developed by Greg Bacon <gbacon@adtran.com> and Dennis Taylor <corbeau@execpc.com>.

• Ideas and large amounts of code donated by Nat "King" Torkington <gnat@frii.com>.

• Currently being hacked on, hacked up, and worked over by the members of the Net::IRC developers mailing list. For details, see http://www.execpc.com/~corbeau/irc/list.html .

URL

The following identical pages contain up-to-date source and information about the Net::IRC project:

• http://www.execpc.com/~corbeau/irc/

• http://betterbox.net/fimmtiu/irc/

SEE ALSO

• perl(1).

• RFC 1459: The Internet Relay Chat Protocol

• http://www.irchelp.org/, home of fine IRC resources.