1IRC(3) User Contributed Perl Documentation IRC(3)
2
6 Net::IRC - DEAD SINCE 2004 Perl interface to the Internet Relay Chat
7 protocol
8
10 This module has been abandoned and is no longer developed. This release
11 serves only to warn current and future users about this and to direct
12 them to supported and actively-developed libraries for connecting Perl
13 to IRC. Most new users will want to use Bot::BasicBot, whereas more
14 advanced users will appreciate the flexibility offered by
15 POE::Component::IRC. We understand that porting code to a new framework
16 can be difficult. Please stop by #perl on irc.freenode.net and we'll be
17 happy to help you out with bringing your bots into the modern era.
18
20 use Net::IRC;
21 $irc = new Net::IRC;
23 $conn = $irc->newconn(Nick => 'some_nick',
24 Server => 'some.irc.server.com',
25 Port => 6667,
26 Ircname => 'Some witty comment.');
27 $irc->start;
28
30 This module has been abandoned and deprecated since 2004. The original
31 authors have moved onto POE::Component::IRC and more modern techniques.
32 This distribution is not maintained and only uploaded to present
33 successively louder "don't use this" warnings to those unaware.
34 Welcome to Net::IRC, a work in progress. First intended to be a quick
36 tool for writing an IRC script in Perl, Net::IRC has grown into a
37 comprehensive Perl implementation of the IRC protocol (RFC 1459),
38 developed by several members of the EFnet IRC channel #perl, and
39 maintained in channel #net-irc.
40 There are 4 component modules which make up Net::IRC:
42 • Net::IRC
44 The wrapper for everything else, containing methods to generate
46 Connection objects (see below) and a connection manager which does
47 an event loop on all available filehandles. Sockets or files which
48 are readable (or writable, or whatever you want it to select() for)
49 get passed to user-supplied handler subroutines in other packages
50 or in user code.
51 • Net::IRC::Connection
53 The big time sink on this project. Each Connection instance is a
55 single connection to an IRC server. The module itself contains
56 methods for every single IRC command available to users (Net::IRC
57 isn't designed for writing servers, for obvious reasons), methods
58 to set, retrieve, and call handler functions which the user can set
59 (more on this later), and too many cute comments. Hey, what can I
60 say, we were bored.
61 • Net::IRC::Event
63 Kind of a struct-like object for storing info about things that the
65 IRC server tells you (server responses, channel talk, joins and
66 parts, et cetera). It records who initiated the event, who it
67 affects, the event type, and any other arguments provided for that
68 event. Incidentally, the only argument passed to a handler
69 function.
70 • Net::IRC::DCC
72 The analogous object to Connection.pm for connecting, sending and
74 retrieving with the DCC protocol. Instances of DCC.pm are invoked
75 from "Connection->new_{send,get,chat}" in the same way that
76 "IRC->newconn" invokes "Connection->new". This will make more sense
77 later, we promise.
78 The central concept that Net::IRC is built around is that of handlers
80 (or hooks, or callbacks, or whatever the heck you feel like calling
81 them). We tried to make it a completely event-driven model, a la Tk --
82 for every conceivable type of event that your client might see on IRC,
83 you can give your program a custom subroutine to call. But wait,
84 there's more! There are 3 levels of handler precedence:
85 • Default handlers
87 Considering that they're hardwired into Net::IRC, these won't do
89 much more than the bare minimum needed to keep the client listening
90 on the server, with an option to print (nicely formatted, of
91 course) what it hears to whatever filehandles you specify (STDOUT
92 by default). These get called only when the user hasn't defined any
93 of his own handlers for this event.
94 • User-definable global handlers
96 The user can set up his own subroutines to replace the default
98 actions for every IRC connection managed by your program. These
99 only get invoked if the user hasn't set up a per-connection handler
100 for the same event.
101 • User-definable per-connection handlers
103 Simple: this tells a single connection what to do if it gets an
105 event of this type. Supersedes global handlers if any are defined
106 for this event.
107 And even better, you can choose to call your custom handlers before or
109 after the default handlers instead of replacing them, if you wish. In
110 short, it's not perfect, but it's about as good as you can get and
111 still be documentable, given the sometimes horrendous complexity of the
112 IRC protocol.
113
115 Initialization
116 To start a Net::IRC script, you need two things: a Net::IRC object, and
117 a Net::IRC::Connection object. The Connection object does the dirty
118 work of connecting to the server; the IRC object handles the input and
119 output for it. To that end, say something like this:
120 use Net::IRC;
122 $irc = new Net::IRC;
124 $conn = $irc->newconn(Nick => 'some_nick',
126 Server => 'some.irc.server.com');
127 ...or something similar. Acceptable parameters to newconn() are:
129 • Nick
131 The nickname you'll be known by on IRC, often limited to a maximum
133 of 9 letters. Acceptable characters for a nickname are
134 "[\w{}[]\`^|-]". If you don't specify a nick, it defaults to your
135 username.
136 • Server
138 The IRC server to connect to. There are dozens of them across
140 several widely-used IRC networks, but the oldest and most popular
141 is EFNet (Eris Free Net), home to #perl. See
142 http://www.irchelp.org/ for lists of popular servers, or ask a
143 friend.
144 • Port
146 The port to connect to this server on. By custom, the default is
148 6667.
149 • Username
151 On systems not running identd, you can set the username for your
153 user@host to anything you wish. Note that some IRC servers won't
154 allow connections from clients which don't run identd.
155 • Ircname
157 A short (maybe 60 or so chars) piece of text, originally intended
159 to display your real name, which people often use for pithy quotes
160 and URLs. Defaults to the contents of your GECOS field.
161 • Password
163 If the IRC server you're trying to write a bot for is password-
165 protected, no problem. Just say ""Password =" 'foo'>" and you're
166 set.
167 • SSL
169 If you wish to connect to an irc server which is using SSL, set
171 this to a true value. Ie: ""SSL =" 1>".
172 Handlers
174 Once that's over and done with, you need to set up some handlers if you
175 want your bot to do anything more than sit on a connection and waste
176 resources. Handlers are references to subroutines which get called
177 when a specific event occurs. Here's a sample handler sub:
178 # What to do when the bot successfully connects.
180 sub on_connect {
181 my $self = shift;
182 print "Joining #IRC.pm...";
184 $self->join("#IRC.pm");
185 $self->privmsg("#IRC.pm", "Hi there.");
186 }
187 The arguments to a handler function are always the same:
189 $_[0]:
191 The Connection object that's calling it.
192 $_[1]:
194 An Event object (see below) that describes what the handler is
195 responding to.
196 Got it? If not, see the examples in the irctest script that came with
198 this distribution. Anyhow, once you've defined your handler
199 subroutines, you need to add them to the list of handlers as either a
200 global handler (affects all Connection objects) or a local handler
201 (affects only a single Connection). To do so, say something along these
202 lines:
203 $self->add_global_handler('376', \&on_connect); # global
205 $self->add_handler('msg', \&on_msg); # local
206 376, incidentally, is the server number for "end of MOTD", which is an
208 event that the server sends to you after you're connected. See Event.pm
209 for a list of all possible numeric codes. The 'msg' event gets called
210 whenever someone else on IRC sends your client a private message. For a
211 big list of possible events, see the Event List section in the
212 documentation for Net::IRC::Event.
213 Getting Connected
215 When you've set up all your handlers, the following command will put
216 your program in an infinite loop, grabbing input from all open
217 connections and passing it off to the proper handlers:
218 $irc->start;
220 Note that new connections can be added and old ones dropped from within
222 your handlers even after you call this. Just don't expect any code
223 below the call to start() to ever get executed.
224 If you're tying Net::IRC into another event-based module, such as
226 perl/Tk, there's a nifty do_one_loop() method provided for your
227 convenience. Calling "$irc->do_one_loop()" runs through the IRC.pm
228 event loop once, hands all ready filehandles over to the appropriate
229 handler subs, then returns control to your program.
230
232 This section contains only the methods in IRC.pm itself. Lists of the
233 methods in Net::IRC::Connection, Net::IRC::Event, or Net::IRC::DCC are
234 in their respective modules' documentation; just "perldoc
235 Net::IRC::Connection" (or Event or DCC or whatever) to read them.
236 Functions take no arguments unless otherwise specified in their
237 description.
238 By the way, expect Net::IRC to use AutoLoader sometime in the future,
240 once it becomes a little more stable.
241 • addconn()
243 Adds the specified object's socket to the select loop in
245 do_one_loop(). This is mostly for the use of Connection and DCC
246 objects (and for pre-0.5 compatibility)... for most (read: all)
247 purposes, you can just use addfh(), described below.
248 Takes at least 1 arg:
250 0. An object whose socket needs to be added to the select loop
252 1. Optional: A string consisting of one or more of the letters r,
254 w, and e. Passed directly to addfh()... see the description
255 below for more info.
256 • addfh()
258 This sub takes a user's socket or filehandle and a sub to handle it
260 with and merges it into do_one_loop()'s list of select()able
261 filehandles. This makes integration with other event-based systems
262 (Tk, for instance) a good deal easier than in previous releases.
263 Takes at least 2 args:
265 0. A socket or filehandle to monitor
267 1. A reference to a subroutine. When select() determines that the
269 filehandle is ready, it passes the filehandle to this
270 (presumably user-supplied) sub, where you can read from it,
271 write to it, etc. as your script sees fit.
272 2. Optional: A string containing any combination of the letters r,
274 w or e (standing for read, write, and error, respectively)
275 which determines what conditions you're expecting on that
276 filehandle. For example, this line select()s $fh (a filehandle,
277 of course) for both reading and writing:
278 $irc->addfh( $fh, \&callback, "rw" );
280 • do_one_loop()
282 select()s on all open filehandles and passes any ready ones to the
284 appropriate handler subroutines. Also responsible for executing
285 scheduled events from "Net::IRC::Connection->schedule()" on time.
286 • new()
288 A fairly vanilla constructor which creates and returns a new
290 Net::IRC object.
291 • newconn()
293 Creates and returns a new Connection object. All arguments are
295 passed straight to "Net::IRC::Connection->new()"; examples of
296 common arguments can be found in the Synopsis or Getting Started
297 sections.
298 • removeconn()
300 Removes the specified object's socket from do_one_loop()'s list of
302 select()able filehandles. This is mostly for the use of Connection
303 and DCC objects (and for pre-0.5 compatibility)... for most (read:
304 all) purposes, you can just use removefh(), described below.
305 Takes 1 arg:
307 0. An object whose socket or filehandle needs to be removed from
309 the select loop
310 • removefh()
312 This method removes a given filehandle from do_one_loop()'s list of
314 selectable filehandles.
315 Takes 1 arg:
317 0. A socket or filehandle to remove
319 • start()
321 Starts an infinite event loop which repeatedly calls do_one_loop()
323 to read new events from all open connections and pass them off to
324 any applicable handlers.
325 • timeout()
327 Sets or returns the current select() timeout for the main event
329 loop, in seconds (fractional amounts allowed). See the
330 documentation for the select() function for more info.
331 Takes 1 optional arg:
333 0. Optional: A new value for the select() timeout for this IRC
335 object.
336 • flush_output_queue()
338 Flushes any waiting messages in the output queue if pacing is
340 enabled. This method will not return until the output queue is
341 empty.
342
344 • Conceived and initially developed by Greg Bacon <gbacon@adtran.com>
345 and Dennis Taylor <dennis@funkplanet.com>.
346 • Ideas and large amounts of code donated by Nat "King" Torkington
348 <gnat@frii.com>.
349 • Currently being hacked on, hacked up, and worked over by the
351 members of the Net::IRC developers mailing list. For details, see
352 http://www.execpc.com/~corbeau/irc/list.html .
353
355 Up-to-date source and information about the Net::IRC project can be
356 found at http://www.sourceforge.net/projects/net-irc/ .
357
359 • perl(1).
360 • RFC 1459: The Internet Relay Chat Protocol
362 • http://www.irchelp.org/, home of fine IRC resources.
364
366 Hey! The above document had some coding errors, which are explained
367 below:
368 Around line 576:
370 Expected text after =item, not a number
371 Around line 600:
373 Expected text after =item, not a number
374 Around line 606:
376 Expected text after =item, not a number
377 Around line 712:
379 You forgot a '=back' before '=head1'
380perl v5.38.0 2023-07-21 IRC(3)