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), 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:
- 0.
- An object whose socket needs to be added to the select
loop
- 1.
- 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:
- 0.
- A socket or filehandle to monitor
- 1.
- 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.
- 2.
- 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:
- 0.
- 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:
- 0.
- 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:
- 0.
- 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/ .
SEE ALSO¶
- •
- perl(1).
- •
- RFC 1459: The Internet Relay Chat Protocol
- •
- http://www.irchelp.org/, home of fine IRC resources.