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

NAME

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

USE THESE INSTEAD

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

SYNOPSIS

20           use Net::IRC;
21
22           $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

DESCRIPTION

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
35       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
41       There are 4 component modules which make up Net::IRC:
42
43       •   Net::IRC
44
45           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
52       •   Net::IRC::Connection
53
54           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
62       •   Net::IRC::Event
63
64           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
71       •   Net::IRC::DCC
72
73           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
79       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
86       •   Default handlers
87
88           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
95       •   User-definable global handlers
96
97           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
102       •   User-definable per-connection handlers
103
104           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
108       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

GETTING STARTED

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
121           use Net::IRC;
122
123           $irc = new Net::IRC;
124
125           $conn = $irc->newconn(Nick    => 'some_nick',
126                                 Server  => 'some.irc.server.com');
127
128       ...or something similar. Acceptable parameters to newconn() are:
129
130       •   Nick
131
132           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
137       •   Server
138
139           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
145       •   Port
146
147           The port to connect to this server on. By custom, the default is
148           6667.
149
150       •   Username
151
152           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
156       •   Ircname
157
158           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
162       •   Password
163
164           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
168       •   SSL
169
170           If you wish to connect to an irc server which is using SSL, set
171           this to a true value.  Ie: ""SSL =" 1>".
172
173   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
179           # What to do when the bot successfully connects.
180           sub on_connect {
181               my $self = shift;
182
183               print "Joining #IRC.pm...";
184               $self->join("#IRC.pm");
185               $self->privmsg("#IRC.pm", "Hi there.");
186           }
187
188       The arguments to a handler function are always the same:
189
190       $_[0]:
191           The Connection object that's calling it.
192
193       $_[1]:
194           An Event object (see below) that describes what the handler is
195           responding to.
196
197       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
204           $self->add_global_handler('376', \&on_connect);     # global
205           $self->add_handler('msg', \&on_msg);                # local
206
207       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
214   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
219           $irc->start;
220
221       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
225       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

METHOD DESCRIPTIONS

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
239       By the way, expect Net::IRC to use AutoLoader sometime in the future,
240       once it becomes a little more stable.
241
242addconn()
243
244           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
249           Takes at least 1 arg:
250
251           0.  An object whose socket needs to be added to the select loop
252
253           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
257addfh()
258
259           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
264           Takes at least 2 args:
265
266           0.  A socket or filehandle to monitor
267
268           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
273           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
279                   $irc->addfh( $fh, \&callback, "rw" );
280
281do_one_loop()
282
283           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
287new()
288
289           A fairly vanilla constructor which creates and returns a new
290           Net::IRC object.
291
292newconn()
293
294           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
299removeconn()
300
301           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
306           Takes 1 arg:
307
308           0.  An object whose socket or filehandle needs to be removed from
309               the select loop
310
311removefh()
312
313           This method removes a given filehandle from do_one_loop()'s list of
314           selectable filehandles.
315
316           Takes 1 arg:
317
318           0.  A socket or filehandle to remove
319
320start()
321
322           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
326timeout()
327
328           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
332           Takes 1 optional arg:
333
334           0.  Optional: A new value for the select() timeout for this IRC
335               object.
336
337flush_output_queue()
338
339           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

AUTHORS

344       •   Conceived and initially developed by Greg Bacon <gbacon@adtran.com>
345           and Dennis Taylor <dennis@funkplanet.com>.
346
347       •   Ideas and large amounts of code donated by Nat "King" Torkington
348           <gnat@frii.com>.
349
350       •   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

URL

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

SEE ALSO

359perl(1).
360
361       •   RFC 1459: The Internet Relay Chat Protocol
362
363http://www.irchelp.org/, home of fine IRC resources.
364

POD ERRORS

366       Hey! The above document had some coding errors, which are explained
367       below:
368
369       Around line 576:
370           Expected text after =item, not a number
371
372       Around line 600:
373           Expected text after =item, not a number
374
375       Around line 606:
376           Expected text after =item, not a number
377
378       Around line 712:
379           You forgot a '=back' before '=head1'
380
381
382
383perl v5.38.0                      2023-07-21                            IRC(3)
Impressum