/ 
Net-IRC-0.45
River stage zero No dependents
/ Net::IRC

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  => 'some.irc.server.com',
	                  Port    =>  6667,
			  Ircname => 'Some witty comment.');
    $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.

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.

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

GETTING STARTED

Initialization

To start a Net::IRC script, you need two things: a Net::IRC object, and a Net::IRC::Connection object. The Connection object does the dirty work of connecting to the server; the IRC object handles the input and output for it. To that end, say something like this:

use Net::IRC;

$irc = new Net::IRC;

$conn = $irc->newconn(Nick    => 'some_nick',
                      Server  => 'some.irc.server.com');

...or something similar. Acceptable parameters to newconn() are:

  • Nick

    The nickname you'll be known by on IRC, often limited to a maximum of 9 letters. Acceptable characters for a nickname are [\w{}[]\`^|-]. If you don't specify a nick, it defaults to your username.

  • Server

    The IRC server to connect to. There are dozens of them across several widely-used IRC networks, but the oldest and most popular is EFNet (Eris Free Net), home to #perl. See http://www.irchelp.org/ for lists of popular servers, or ask a friend.

  • Port

    The port to connect to this server on. By custom, the default is 6667.

  • Username

    On systems not running identd, you can set the username for your user@host to anything you wish. Note that some IRC servers won't allow connections from clients which don't run identd.

  • Ircname

    A short (maybe 50 or 60 chars) piece of text, originally intended to display your real name, which people often use for pithy quotes and URLs. Defaults to the contents of your GECOS field.

Handlers

Once that's over and done with, you need to set up some handlers if you want your bot to do anything more than sit on a connection and waste resources. Handlers are references to subroutines which get called when a specific event occurs. Here's a sample handler sub:

# What to do when the bot successfully connects.
sub on_connect {
    my $self = shift;

    $self->print("Joining #IRC.pm...");
    $self->join("#IRC.pm");
    $self->privmsg("#IRC.pm", "Hi there.");
}

The arguments to a handler function are always the same:

$_[0]:

The Connection object that's calling it.

$_[1]:

An Event object (see below) that describes what the handler is responding to.

Got it? If not, see the examples in the irctest script that came with this distribution. Anyhow, once you've defined your handler subroutines, you need to add them to the list of handlers as either a global handler (affects all Connection objects) or a local handler (affects only a single Connection). To do so, say something along these lines:

$self->add_global_handler('376', \&on_connect);     # global
$self->add_handler('msg', \&on_msg);                # local

376, incidentally, is the server number for "end of MOTD", which is an event that the server sends to you after you're connected. See Event.pm for a list of all possible numeric codes. The 'msg' event gets called whenever someone else on IRC sends your client a private message. For a big list of possible events, see the Event List section in the documentation for Net::IRC::Event.

Getting Connected

When you've set up all your handlers, the following command will put your program in an infinite loop, grabbing input from all open connections and passing it off to the proper handlers:

$irc->start;

Note that new connections can be added and old ones dropped from within your handlers even after you call this. Just don't expect any code below the call to start() to ever get executed.

If you're tying Net::IRC into another event-based module, such as perl/Tk, there's a nifty do_one_loop() method provided for your convenience. Calling $irc->do_one_loop() runs through the IRC.pm event loop once, reads from all ready filehandles, and dispatches their events, then returns control to your program. Currently, performance on this is a little slow, but we're working on it.

METHOD DESCRIPTIONS

This section contains only the methods in IRC.pm itself. Lists of the methods in Net::IRC::Connection, Net::IRC::Event, or Net::IRC::DCC are in their respective modules' documentation; just perldoc Net::IRC::Connection (or Event or DCC or whatever) to read them. Functions take no arguments unless otherwise specified in their description.

By the way, expect Net::IRC to use Autoloader sometime in the future, once it becomes a little more stable.

  • addconn()

    Adds the specified socket or filehandle to the list of readable connections and notifies do_one_loop().

    Takes 1 arg:

    0.

    a socket or filehandle to add to the select loop

  • changed()

    Sets a flag which tells do_one_loop() that the current list of readable connections needs to be rebuilt. It's not likely that many users will need this... just use addconn() and removeconn() instead.

  • debug()

    This doesn't yet even pretend to be functional. It may be in the future; wait and see.

  • do_one_loop()

    select()s on all open sockets and passes any information it finds to the appropriate parse() method in a separate package for handling. Also responsible for executing scheduled events from Net::IRC::Connection->schedule() on time.

  • new()

    A fairly vanilla constructor which creates and returns a new Net::IRC object.

  • newconn()

    Creates and returns a new Connection object. All arguments are passed straight to Net::IRC::Connection->new(); examples of common arguments can be found in the Synopsis or Getting Started sections.

  • removeconn()

    Removes the specified socket or filehandle from the list of readable filehandles and notifies do_one_loop() of the change.

    Takes 1 arg:

    0.

    a socket or filehandle to remove from the select loop

  • start()

    Starts an infinite event loop which repeatedly calls do_one_loop() to read new events from all open connections and pass them off to any applicable handlers.

AUTHORS

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