Quote:
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), developed by several members of the EFnet IRC channel #perl, and maintained in channel #net-irc.
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 on all available filehandles. Sockets or files which are readable (or writable, or whatever you want it to select() for) get passed to user-supplied handler subroutines in other packages or in user code.
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, we were 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. Instances of DCC.pm are invoked from Connection->new_{send,get,chat} in the same way that IRC->newconn invokes Connection->new. This will make more sense later, we promise.
The central concept that Net::IRC is built around is that of handlers (or hooks, or callbacks, or whatever the heck you feel like calling 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.
i can post some example scripts if you'd like- of course you can always google it yourself ;)