Ubuntu Manpage: Net::IRC - DEAD SINCE 2004 Perl interface to the Internet Relay Chat protocol

NAME

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

USE THESE INSTEAD

       This module has been abandoned and is no longer developed. This release serves only to warn current and
       future users about this and to direct them to supported and actively-developed libraries for connecting
       Perl to IRC. Most new users will want to use Bot::BasicBot, whereas more advanced users will appreciate
       the flexibility offered by POE::Component::IRC. We understand that porting code to a new framework can be
       difficult. Please stop by #perl on irc.freenode.net and we'll be happy to help you out with bringing your
       bots into the modern era.

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

This module has been abandoned and deprecated since 2004. The original authors have moved onto
POE::Component::IRC and more modern techniques. This distribution is not maintained and only uploaded to
present successively louder "don't use this" warnings to those unaware.

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.

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  60 or so 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.

       •   Password

           If the IRC server you're trying to write a bot  for  is  password-protected,  no  problem.  Just  say
           ""Password =" 'foo'>" and you're set.

       •   SSL

           If  you  wish to connect to an irc server which is using SSL, set this to a true value.  Ie: ""SSL ="
           1>".

   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;

               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, hands all ready filehandles over to the appropriate handler  subs,  then  returns
       control to your program.

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 object's socket to the select loop in "do_one_loop()".  This is mostly for the use
           of  Connection  and DCC objects (and for pre-0.5 compatibility)... for most (read: all) purposes, you
           can just use "addfh()", described below.

           Takes at least 1 arg:

           1.  An object whose socket needs to be added to the select loop

           2.  Optional: A string consisting of one or more of the letters r, w,  and  e.   Passed  directly  to
               "addfh()"... see the description below for more info.

       •   addfh()

           This  sub  takes  a  user's  socket  or  filehandle  and  a  sub to handle it with and merges it into
           "do_one_loop()"'s list of select()able filehandles. This makes  integration  with  other  event-based
           systems (Tk, for instance) a good deal easier than in previous releases.

           Takes at least 2 args:

           1.  A socket or filehandle to monitor

           2.  A  reference  to a subroutine. When "select()" determines that the filehandle is ready, it passes
               the filehandle to this (presumably user-supplied) sub, where you can read from it, write  to  it,
               etc. as your script sees fit.

           3.  Optional: A string containing any combination of the letters r, w or e (standing for read, write,
               and  error,  respectively)  which determines what conditions you're expecting on that filehandle.
               For example, this line select()s $fh (a filehandle, of course) for both reading and writing:

                   $irc->addfh( $fh, \&callback, "rw" );

       •   do_one_loop()

           "select()"s on all open filehandles and passes any ready ones to the appropriate handler subroutines.
           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 object's socket from "do_one_loop()"'s list of select()able  filehandles.  This
           is  mostly  for  the  use  of  Connection and DCC objects (and for pre-0.5 compatibility)... for most
           (read: all) purposes, you can just use "removefh()", described below.

           Takes 1 arg:

           1.  An object whose socket or filehandle needs to be removed from the select loop

       •   removefh()

           This method removes a given filehandle from "do_one_loop()"'s list of selectable filehandles.

           Takes 1 arg:

           1.  A socket or filehandle to remove

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

       •   timeout()

           Sets or returns the current "select()" timeout for  the  main  event  loop,  in  seconds  (fractional
           amounts allowed). See the documentation for the "select()" function for more info.

           Takes 1 optional arg:

           1.  Optional: A new value for the "select()" timeout for this IRC object.

       •   flush_output_queue()

           Flushes  any  waiting  messages in the output queue if pacing is enabled. This method will not return
           until the output queue is empty.

AUTHORS

       •   Conceived  and  initially  developed  by   Greg   Bacon   <gbacon@adtran.com>   and   Dennis   Taylor
           <dennis@funkplanet.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

       Up-to-date   source   and   information   about    the    Net::IRC    project    can    be    found    at
       http://www.sourceforge.net/projects/net-irc/ .