1IRC(3) User Contributed Perl Documentation IRC(3)
2
3
4
6 Net::IRC - Perl interface to the Internet Relay Chat protocol
7
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
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 com‐
21 prehensive Perl implementation of the IRC protocol (RFC 1459), devel‐
22 oped by several members of the EFnet IRC channel #perl, and maintained
23 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 func‐
53 tion.
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
99 Initialization
100
101 To start a Net::IRC script, you need two things: a Net::IRC object, and
102 a Net::IRC::Connection object. The Connection object does the dirty
103 work of connecting to the server; the IRC object handles the input and
104 output for it. To that end, say something like this:
105
106 use Net::IRC;
107
108 $irc = new Net::IRC;
109
110 $conn = $irc->newconn(Nick => 'some_nick',
111 Server => 'some.irc.server.com');
112
113 ...or something similar. Acceptable parameters to newconn() are:
114
115 · Nick
116
117 The nickname you'll be known by on IRC, often limited to a maximum
118 of 9 letters. Acceptable characters for a nickname are
119 "[\w{}[]\`^⎪-]". If you don't specify a nick, it defaults to your
120 username.
121
122 · Server
123
124 The IRC server to connect to. There are dozens of them across sev‐
125 eral widely-used IRC networks, but the oldest and most popular is
126 EFNet (Eris Free Net), home to #perl. See http://www.irchelp.org/
127 for lists of popular servers, or ask a 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-pro‐
149 tected, no problem. Just say ""Password =" 'foo'>" and you're set.
150
151 · SSL
152
153 If you wish to connect to an irc server which is using SSL, set
154 this to a true value. Ie: ""SSL =" 1>".
155
156 Handlers
157
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 subrou‐
183 tines, you need to add them to the list of handlers as either a global
184 handler (affects all Connection objects) or a local handler (affects
185 only a single Connection). To do so, say something along these lines:
186
187 $self->add_global_handler('376', \&on_connect); # global
188 $self->add_handler('msg', \&on_msg); # local
189
190 376, incidentally, is the server number for "end of MOTD", which is an
191 event that the server sends to you after you're connected. See Event.pm
192 for a list of all possible numeric codes. The 'msg' event gets called
193 whenever someone else on IRC sends your client a private message. For a
194 big list of possible events, see the Event List section in the documen‐
195 tation for Net::IRC::Event.
196
197 Getting Connected
198
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 connec‐
201 tions 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 con‐
211 venience. Calling "$irc->do_one_loop()" runs through the IRC.pm event
212 loop once, hands all ready filehandles over to the appropriate handler
213 subs, then returns control to your program.
214
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. Func‐
220 tions take no arguments unless otherwise specified in their descrip‐
221 tion.
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 (pre‐
254 sumably user-supplied) sub, where you can read from it, write
255 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 file‐
260 handle. For example, this line select()s $fh (a filehandle, of
261 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 com‐
280 mon arguments can be found in the Synopsis or Getting Started sec‐
281 tions.
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 Connec‐
287 tion and DCC objects (and for pre-0.5 compatibility)... for most
288 (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 documenta‐
315 tion 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
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 mem‐
336 bers of the Net::IRC developers mailing list. For details, see
337 http://www.execpc.com/~corbeau/irc/list.html .
338
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
344 · perl(1).
345
346 · RFC 1459: The Internet Relay Chat Protocol
347
348 · http://www.irchelp.org/, home of fine IRC resources.
349
350
351
352perl v5.8.8 2004-04-30 IRC(3)