Net::IRC(3pm)

1IRC(3)                User Contributed Perl Documentation               IRC(3)
2
3
4

NAME

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

SYNOPSIS

9           use Net::IRC;
10
11           $irc = new Net::IRC;
12           $conn = $irc->newconn(Nick    => 'some_nick',
13                                 Server  => 'some.irc.server.com',
14                                 Port    =>  6667,
15                                 Ircname => 'Some witty comment.');
16           $irc->start;
17

DESCRIPTION

19       Welcome to Net::IRC, a work in progress. First intended to be a quick
20       tool for writing an IRC script in Perl, Net::IRC has grown into a
21       comprehensive Perl implementation of the IRC protocol (RFC 1459),
22       developed by several members of the EFnet IRC channel #perl, and
23       maintained in channel #net-irc.
24
25       There are 4 component modules which make up Net::IRC:
26
27       ·   Net::IRC
28
29           The wrapper for everything else, containing methods to generate
30           Connection objects (see below) and a connection manager which does
31           an event loop on all available filehandles. Sockets or files which
32           are readable (or writable, or whatever you want it to select() for)
33           get passed to user-supplied handler subroutines in other packages
34           or in user code.
35
36       ·   Net::IRC::Connection
37
38           The big time sink on this project. Each Connection instance is a
39           single connection to an IRC server. The module itself contains
40           methods for every single IRC command available to users (Net::IRC
41           isn't designed for writing servers, for obvious reasons), methods
42           to set, retrieve, and call handler functions which the user can set
43           (more on this later), and too many cute comments. Hey, what can I
44           say, we were bored.
45
46       ·   Net::IRC::Event
47
48           Kind of a struct-like object for storing info about things that the
49           IRC server tells you (server responses, channel talk, joins and
50           parts, et cetera). It records who initiated the event, who it
51           affects, the event type, and any other arguments provided for that
52           event. Incidentally, the only argument passed to a handler
53           function.
54
55       ·   Net::IRC::DCC
56
57           The analogous object to Connection.pm for connecting, sending and
58           retrieving with the DCC protocol. Instances of DCC.pm are invoked
59           from "Connection->new_{send,get,chat}" in the same way that
60           "IRC->newconn" invokes "Connection->new". This will make more sense
61           later, we promise.
62
63       The central concept that Net::IRC is built around is that of handlers
64       (or hooks, or callbacks, or whatever the heck you feel like calling
65       them).  We tried to make it a completely event-driven model, a la Tk --
66       for every conceivable type of event that your client might see on IRC,
67       you can give your program a custom subroutine to call. But wait,
68       there's more! There are 3 levels of handler precedence:
69
70       ·   Default handlers
71
72           Considering that they're hardwired into Net::IRC, these won't do
73           much more than the bare minimum needed to keep the client listening
74           on the server, with an option to print (nicely formatted, of
75           course) what it hears to whatever filehandles you specify (STDOUT
76           by default). These get called only when the user hasn't defined any
77           of his own handlers for this event.
78
79       ·   User-definable global handlers
80
81           The user can set up his own subroutines to replace the default
82           actions for every IRC connection managed by your program. These
83           only get invoked if the user hasn't set up a per-connection handler
84           for the same event.
85
86       ·   User-definable per-connection handlers
87
88           Simple: this tells a single connection what to do if it gets an
89           event of this type. Supersedes global handlers if any are defined
90           for this event.
91
92       And even better, you can choose to call your custom handlers before or
93       after the default handlers instead of replacing them, if you wish. In
94       short, it's not perfect, but it's about as good as you can get and
95       still be documentable, given the sometimes horrendous complexity of the
96       IRC protocol.
97

GETTING STARTED

99   Initialization
100       To start a Net::IRC script, you need two things: a Net::IRC object, and
101       a Net::IRC::Connection object. The Connection object does the dirty
102       work of connecting to the server; the IRC object handles the input and
103       output for it.  To that end, say something like this:
104
105           use Net::IRC;
106
107           $irc = new Net::IRC;
108
109           $conn = $irc->newconn(Nick    => 'some_nick',
110                                 Server  => 'some.irc.server.com');
111
112       ...or something similar. Acceptable parameters to newconn() are:
113
114       ·   Nick
115
116           The nickname you'll be known by on IRC, often limited to a maximum
117           of 9 letters. Acceptable characters for a nickname are
118           "[\w{}[]\`^|-]". If you don't specify a nick, it defaults to your
119           username.
120
121       ·   Server
122
123           The IRC server to connect to. There are dozens of them across
124           several widely-used IRC networks, but the oldest and most popular
125           is EFNet (Eris Free Net), home to #perl. See
126           http://www.irchelp.org/ for lists of popular servers, or ask a
127           friend.
128
129       ·   Port
130
131           The port to connect to this server on. By custom, the default is
132           6667.
133
134       ·   Username
135
136           On systems not running identd, you can set the username for your
137           user@host to anything you wish. Note that some IRC servers won't
138           allow connections from clients which don't run identd.
139
140       ·   Ircname
141
142           A short (maybe 60 or so chars) piece of text, originally intended
143           to display your real name, which people often use for pithy quotes
144           and URLs. Defaults to the contents of your GECOS field.
145
146       ·   Password
147
148           If the IRC server you're trying to write a bot for is password-
149           protected, no problem. Just say ""Password =" 'foo'>" and you're
150           set.
151
152       ·   SSL
153
154           If you wish to connect to an irc server which is using SSL, set
155           this to a true value.  Ie: ""SSL =" 1>".
156
157   Handlers
158       Once that's over and done with, you need to set up some handlers if you
159       want your bot to do anything more than sit on a connection and waste
160       resources.  Handlers are references to subroutines which get called
161       when a specific event occurs. Here's a sample handler sub:
162
163           # What to do when the bot successfully connects.
164           sub on_connect {
165               my $self = shift;
166
167               print "Joining #IRC.pm...";
168               $self->join("#IRC.pm");
169               $self->privmsg("#IRC.pm", "Hi there.");
170           }
171
172       The arguments to a handler function are always the same:
173
174       $_[0]:
175           The Connection object that's calling it.
176
177       $_[1]:
178           An Event object (see below) that describes what the handler is
179           responding to.
180
181       Got it? If not, see the examples in the irctest script that came with
182       this distribution. Anyhow, once you've defined your handler
183       subroutines, you need to add them to the list of handlers as either a
184       global handler (affects all Connection objects) or a local handler
185       (affects only a single Connection). To do so, say something along these
186       lines:
187
188           $self->add_global_handler('376', \&on_connect);     # global
189           $self->add_handler('msg', \&on_msg);                # local
190
191       376, incidentally, is the server number for "end of MOTD", which is an
192       event that the server sends to you after you're connected. See Event.pm
193       for a list of all possible numeric codes. The 'msg' event gets called
194       whenever someone else on IRC sends your client a private message. For a
195       big list of possible events, see the Event List section in the
196       documentation for Net::IRC::Event.
197
198   Getting Connected
199       When you've set up all your handlers, the following command will put
200       your program in an infinite loop, grabbing input from all open
201       connections and passing it off to the proper handlers:
202
203           $irc->start;
204
205       Note that new connections can be added and old ones dropped from within
206       your handlers even after you call this. Just don't expect any code
207       below the call to "start()" to ever get executed.
208
209       If you're tying Net::IRC into another event-based module, such as
210       perl/Tk, there's a nifty "do_one_loop()" method provided for your
211       convenience. Calling "$irc->do_one_loop()" runs through the IRC.pm
212       event loop once, hands all ready filehandles over to the appropriate
213       handler subs, then returns control to your program.
214

METHOD DESCRIPTIONS

216       This section contains only the methods in IRC.pm itself. Lists of the
217       methods in Net::IRC::Connection, Net::IRC::Event, or Net::IRC::DCC are
218       in their respective modules' documentation; just "perldoc
219       Net::IRC::Connection" (or Event or DCC or whatever) to read them.
220       Functions take no arguments unless otherwise specified in their
221       description.
222
223       By the way, expect Net::IRC to use AutoLoader sometime in the future,
224       once it becomes a little more stable.
225
226       ·   addconn()
227
228           Adds the specified object's socket to the select loop in
229           "do_one_loop()".  This is mostly for the use of Connection and DCC
230           objects (and for pre-0.5 compatibility)... for most (read: all)
231           purposes, you can just use "addfh()", described below.
232
233           Takes at least 1 arg:
234
235           0.  An object whose socket needs to be added to the select loop
236
237           1.  Optional: A string consisting of one or more of the letters r,
238               w, and e.  Passed directly to "addfh()"... see the description
239               below for more info.
240
241       ·   addfh()
242
243           This sub takes a user's socket or filehandle and a sub to handle it
244           with and merges it into "do_one_loop()"'s list of select()able
245           filehandles. This makes integration with other event-based systems
246           (Tk, for instance) a good deal easier than in previous releases.
247
248           Takes at least 2 args:
249
250           0.  A socket or filehandle to monitor
251
252           1.  A reference to a subroutine. When "select()" determines that
253               the filehandle is ready, it passes the filehandle to this
254               (presumably user-supplied) sub, where you can read from it,
255               write to it, etc. as your script sees fit.
256
257           2.  Optional: A string containing any combination of the letters r,
258               w or e (standing for read, write, and error, respectively)
259               which determines what conditions you're expecting on that
260               filehandle. For example, this line select()s $fh (a filehandle,
261               of course) for both reading and writing:
262
263                   $irc->addfh( $fh, \&callback, "rw" );
264
265       ·   do_one_loop()
266
267           "select()"s on all open filehandles and passes any ready ones to
268           the appropriate handler subroutines. Also responsible for executing
269           scheduled events from "Net::IRC::Connection->schedule()" on time.
270
271       ·   new()
272
273           A fairly vanilla constructor which creates and returns a new
274           Net::IRC object.
275
276       ·   newconn()
277
278           Creates and returns a new Connection object. All arguments are
279           passed straight to "Net::IRC::Connection->new()"; examples of
280           common arguments can be found in the Synopsis or Getting Started
281           sections.
282
283       ·   removeconn()
284
285           Removes the specified object's socket from "do_one_loop()"'s list
286           of select()able filehandles. This is mostly for the use of
287           Connection and DCC objects (and for pre-0.5 compatibility)... for
288           most (read: all) purposes, you can just use "removefh()", described
289           below.
290
291           Takes 1 arg:
292
293           0.  An object whose socket or filehandle needs to be removed from
294               the select loop
295
296       ·   removefh()
297
298           This method removes a given filehandle from "do_one_loop()"'s list
299           of selectable filehandles.
300
301           Takes 1 arg:
302
303           0.  A socket or filehandle to remove
304
305       ·   start()
306
307           Starts an infinite event loop which repeatedly calls
308           "do_one_loop()" to read new events from all open connections and
309           pass them off to any applicable handlers.
310
311       ·   timeout()
312
313           Sets or returns the current "select()" timeout for the main event
314           loop, in seconds (fractional amounts allowed). See the
315           documentation for the "select()" function for more info.
316
317           Takes 1 optional arg:
318
319           0.  Optional: A new value for the "select()" timeout for this IRC
320               object.
321
322       ·   flush_output_queue()
323
324           Flushes any waiting messages in the output queue if pacing is
325           enabled. This method will not return until the output queue is
326           empty.
327

AUTHORS

329       ·   Conceived and initially developed by Greg Bacon <gbacon@adtran.com>
330           and Dennis Taylor <dennis@funkplanet.com>.
331
332       ·   Ideas and large amounts of code donated by Nat "King" Torkington
333           <gnat@frii.com>.
334
335       ·   Currently being hacked on, hacked up, and worked over by the
336           members of the Net::IRC developers mailing list. For details, see
337           http://www.execpc.com/~corbeau/irc/list.html .
338

URL

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

POD ERRORS

351       Hey! The above document had some coding errors, which are explained
352       below:
353
354       Around line 697:
355           You forgot a '=back' before '=head1'
356
357
358
359perl v5.12.0                      2004-04-30                            IRC(3)