1POE::Component::IRC(3)User Contributed Perl DocumentationPOE::Component::IRC(3)
2
6 POE::Component::IRC - A fully event-driven IRC client module
7
9 # A simple Rot13 'encryption' bot
10 use strict;
12 use warnings;
13 use POE qw(Component::IRC);
14 my $nickname = 'Flibble' . $$;
16 my $ircname = 'Flibble the Sailor Bot';
17 my $server = 'irc.blahblahblah.irc';
18 my @channels = ('#Blah', '#Foo', '#Bar');
20 # We create a new PoCo-IRC object
22 my $irc = POE::Component::IRC->spawn(
23 nick => $nickname,
24 ircname => $ircname,
25 server => $server,
26 ) or die "Oh noooo! $!";
27 POE::Session->create(
29 package_states => [
30 main => [ qw(_default _start irc_001 irc_public) ],
31 ],
32 heap => { irc => $irc },
33 );
34 $poe_kernel->run();
36 sub _start {
38 my $heap = $_[HEAP];
39 # retrieve our component's object from the heap where we stashed it
41 my $irc = $heap->{irc};
42 $irc->yield( register => 'all' );
44 $irc->yield( connect => { } );
45 return;
46 }
47 sub irc_001 {
49 my $sender = $_[SENDER];
50 # Since this is an irc_* event, we can get the component's object by
52 # accessing the heap of the sender. Then we register and connect to the
53 # specified server.
54 my $irc = $sender->get_heap();
55 print "Connected to ", $irc->server_name(), "\n";
57 # we join our channels
59 $irc->yield( join => $_ ) for @channels;
60 return;
61 }
62 sub irc_public {
64 my ($sender, $who, $where, $what) = @_[SENDER, ARG0 .. ARG2];
65 my $nick = ( split /!/, $who )[0];
66 my $channel = $where->[0];
67 if ( my ($rot13) = $what =~ /^rot13 (.+)/ ) {
69 $rot13 =~ tr[a-zA-Z][n-za-mN-ZA-M];
70 $irc->yield( privmsg => $channel => "$nick: $rot13" );
71 }
72 return;
73 }
74 # We registered for all events, this will produce some debug info.
76 sub _default {
77 my ($event, $args) = @_[ARG0 .. $#_];
78 my @output = ( "$event: " );
79 for my $arg (@$args) {
81 if ( ref $arg eq 'ARRAY' ) {
82 push( @output, '[' . join(', ', @$arg ) . ']' );
83 }
84 else {
85 push ( @output, "'$arg'" );
86 }
87 }
88 print join ' ', @output, "\n";
89 return 0;
90 }
91
93 POE::Component::IRC is a POE component (who'd have guessed?) which acts
94 as an easily controllable IRC client for your other POE components and
95 sessions. You create an IRC component and tell it what events your
96 session cares about and where to connect to, and it sends back
97 interesting IRC events when they happen. You make the client do things
98 by sending it events. That's all there is to it. Cool, no?
99 [Note that using this module requires some familiarity with the details
101 of the IRC protocol. I'd advise you to read up on the gory details of
102 RFC 1459 (<http://www.faqs.org/rfcs/rfc1459.html>) before you get
103 started. Keep the list of server numeric codes handy while you program.
104 Needless to say, you'll also need a good working knowledge of POE, or
105 this document will be of very little use to you.]
106 The POE::Component::IRC distribution has a docs/ folder with a
108 collection of salient documentation including the pertinent RFCs.
109 POE::Component::IRC consists of a POE::Session that manages the IRC
111 connection and dispatches "irc_" prefixed events to interested sessions
112 and an object that can be used to access additional information using
113 methods.
114 Sessions register their interest in receiving "irc_" events by sending
116 "register" to the component. One would usually do this in your "_start"
117 handler. Your session will continue to receive events until you
118 "unregister". The component will continue to stay around until you tell
119 it not to with "shutdown".
120 The SYNOPSIS demonstrates a fairly basic bot.
122 See POE::Component::IRC::Cookbook for more examples.
124 Useful subclasses
126 Included with POE::Component::IRC are a number of useful subclasses. As
127 they are subclasses they support all the methods, etc. documented here
128 and have additional methods and quirks which are documented separately:
129 POE::Component::IRC::State
131 POE::Component::IRC::State provides all the functionality of
132 POE::Component::IRC but also tracks IRC state entities such as
133 nicks and channels.
134 POE::Component::IRC::Qnet
136 POE::Component::IRC::Qnet is POE::Component::IRC tweaked for use on
137 Quakenet IRC network.
138 POE::Component::IRC::Qnet::State
140 POE::Component::IRC::Qnet::State is a tweaked version of
141 POE::Component::IRC::State for use on the Quakenet IRC network.
142 The Plugin system
144 As of 3.7, PoCo-IRC sports a plugin system. The documentation for it
145 can be read by looking at POE::Component::IRC::Plugin. That is not a
146 subclass, just a placeholder for documentation!
147 A number of useful plugins have made their way into the core
149 distribution:
150 POE::Component::IRC::Plugin::DCC
152 Provides DCC support. Loaded by default.
153 POE::Component::IRC::Plugin::AutoJoin
155 Keeps you on your favorite channels throughout reconnects and even
156 kicks.
157 POE::Component::IRC::Plugin::Connector
159 Glues an irc bot to an IRC network, i.e. deals with maintaining
160 ircd connections.
161 POE::Component::IRC::Plugin::BotTraffic
163 Under normal circumstances irc bots do not normal the msgs and
164 public msgs that they generate themselves. This plugin enables you
165 to handle those events.
166 POE::Component::IRC::Plugin::BotAddressed
168 Generates "irc_bot_addressed" / "irc_bot_mentioned" /
169 "irc_bot_mentioned_action" events whenever your bot's name comes up
170 in channel discussion.
171 POE::Component::IRC::Plugin::BotCommand
173 Provides an easy way to handle commands issued to your bot.
174 POE::Component::IRC::Plugin::Console
176 See inside the component. See what events are being sent. Generate
177 irc commands manually. A TCP based console.
178 POE::Component::IRC::Plugin::FollowTail
180 Follow the tail of an ever-growing file.
181 POE::Component::IRC::Plugin::Logger
183 Log public and private messages to disk.
184 POE::Component::IRC::Plugin::NickServID
186 Identify with FreeNode's NickServ when needed.
187 POE::Component::IRC::Plugin::Proxy
189 A lightweight IRC proxy/bouncer.
190 POE::Component::IRC::Plugin::CTCP
192 Automagically generates replies to ctcp version, time and userinfo
193 queries.
194 POE::Component::IRC::Plugin::PlugMan
196 An experimental Plugin Manager plugin.
197 POE::Component::IRC::Plugin::NickReclaim
199 Automagically deals with your nickname being in use and reclaiming
200 it.
201 POE::Component::IRC::Plugin::CycleEmpty
203 Cycles (parts and rejoins) channels if they become empty and
204 opless, in order to gain ops.
205
207 Both constructors return an object. The object is also available within
208 'irc_' event handlers by using "$_[SENDER]->get_heap()". See also
209 "register" and "irc_registered".
210 "spawn"
212 Takes a number of arguments, all of which are optional. All the options
213 below may be supplied to the "connect" input event as well, except for
214 'alias', 'options', 'NoDNS', 'debug', and 'plugin_debug'.
215 'alias', a name (kernel alias) that this instance will be known by;
217 'options', a hashref containing POE::Session options;
219 'Server', the server name;
221 'Port', the remote port number;
223 'Password', an optional password for restricted servers;
225 'Nick', your client's IRC nickname;
227 'Username', your client's username;
229 'Ircname', some cute comment or something.
231 'UseSSL', set to some true value if you want to connect using SSL.
233 'Raw', set to some true value to enable the component to send "irc_raw"
235 and "irc_raw_out" events.
236 'LocalAddr', which local IP address on a multihomed box to connect as;
238 'LocalPort', the local TCP port to open your socket on;
240 'NoDNS', set this to 1 to disable DNS lookups using PoCo-Client-DNS.
242 (See note below).
243 'Flood', set this to 1 to get quickly disconnected and klined from an
245 ircd >;]
246 'Proxy', IP address or server name of a proxy server to use.
248 'ProxyPort', which tcp port on the proxy to connect to.
250 'NATAddr', what other clients see as your IP address.
252 'DCCPorts', an arrayref containing tcp ports that can be used for DCC
254 sends.
255 'Resolver', provide a POE::Component::Client::DNS object for the
257 component to use.
258 'msg_length', the maximum length of IRC messages, in bytes. Default is
260 450. The IRC component shortens all messages longer than this value
261 minus the length of your current nickname. IRC only allows raw protocol
262 lines messages that are 512 bytes or shorter, including the trailing
263 "\r\n". This is most relevant to long PRIVMSGs. The IRC component can't
264 be sure how long your user@host mask will be every time you send a
265 message, considering that most networks mangle the 'user' part and some
266 even replace the whole string (think FreeNode cloaks). If you have an
267 unusually long user@host mask you might want to decrease this value if
268 you're prone to sending long messages. Conversely, if you have an
269 unusually short one, you can increase this value if you want to be able
270 to send as long a message as possible. Be careful though, increase it
271 too much and the IRC server might disconnect you with a "Request too
272 long" message when you try to send a message that's too long.
273 'debug', if set to a true value causes the IRC component to print every
275 message sent to and from the server, as well as print some warnings
276 when it receives malformed messages. This option will be enabled if the
277 "POCOIRC_DEBUG" environment variable is set to a true value.
278 'plugin_debug', set to some true value to print plugin debug info,
280 default 0. Plugins are processed inside an eval. When you enable this
281 option, you will be notified when (and why) a plugin raises an
282 exception. This option will be enabled if the "POCOIRC_DEBUG"
283 environment variable is set to a true value.
284 'socks_proxy', specify a SOCKS4/SOCKS4a proxy to use.
286 'socks_port', the SOCKS port to use, defaults to 1080 if not specified.
288 'socks_id', specify a SOCKS user_id. Default is none.
290 'useipv6', enable the use of IPv6 for connections.
292 "spawn" will supply reasonable defaults for any of these attributes
294 which are missing, so don't feel obliged to write them all out.
295 If the component finds that POE::Component::Client::DNS is installed it
297 will use that to resolve the server name passed. Disable this behaviour
298 if you like, by passing: "NoDNS => 1".
299 Additionally there is a 'Flood' parameter. When true, it disables the
301 component's flood protection algorithms, allowing it to send messages
302 to an IRC server at full speed. Disconnects and k-lines are some common
303 side effects of flooding IRC servers, so care should be used when
304 enabling this option.
305 Two new attributes are 'Proxy' and 'ProxyPort' for sending your IRC
307 traffic through a proxy server. 'Proxy''s value should be the IP
308 address or server name of the proxy. 'ProxyPort''s value should be the
309 port on the proxy to connect to. "connect" will default to using the
310 actual IRC server's port if you provide a proxy but omit the proxy's
311 port. These are for HTTP Proxies. See 'socks_proxy' for SOCKS4 and
312 SOCKS4a support.
313 For those people who run bots behind firewalls and/or Network Address
315 Translation there are two additional attributes for DCC. 'DCCPorts', is
316 an arrayref of ports to use when initiating DCC connections. 'NATAddr',
317 is the NAT'ed IP address that your bot is hidden behind, this is sent
318 whenever you do DCC.
319 SSL support requires POE::Component::SSLify, as well as an IRC server
321 that supports SSL connections. If you're missing
322 POE::Component::SSLify, specifying 'UseSSL' will do nothing. The
323 default is to not try to use SSL.
324 'Resolver', requires a POE::Component::Client::DNS object. Useful when
326 spawning multiple poco-irc sessions, saves the overhead of multiple dns
327 sessions.
328 'NoDNS' has different results depending on whether it is set with
330 "spawn" or "connect". Setting it with "spawn", disables the creation of
331 the POE::Component::Client::DNS completely. Setting it with "connect"
332 on the other hand allows the PoCo-Client-DNS session to be spawned, but
333 will disable any dns lookups using it.
334 SOCKS4 proxy support is provided by 'socks_proxy', 'socks_port' and
336 'socks_id' parameters. If something goes wrong with the SOCKS
337 connection you should get a warning on STDERR. This is fairly
338 experimental currently.
339 IPv6 support is available for connecting to IPv6 enabled ircds (it
341 won't work for DCC though). To enable it, specify 'useipv6'. Socket6 is
342 required to be installed. If you have Socket6 and
343 POE::Component::Client::DNS installed and specify a hostname that
344 resolves to an IPv6 address then IPv6 will be used. If you specify an
345 ipv6 'localaddr' then IPv6 will be used.
346 "new"
348 This method is deprecated. See the "spawn" method instead. The first
349 argument should be a name (kernel alias) which this new connection will
350 be known by. Optionally takes more arguments (see "spawn" as name/value
351 pairs. Returns a POE::Component::IRC object. :)
352 Note: Use of this method will generate a warning. There are currently
354 no plans to make it die() >;]
355
357 These are methods supported by the POE::Component::IRC object. It also
358 inherits a few from Object::Pluggable. See its documentation for
359 details.
360 "server_name"
362 Takes no arguments. Returns the name of the IRC server that the
363 component is currently connected to.
364 "server_version"
366 Takes no arguments. Returns the IRC server version.
367 "nick_name"
369 Takes no arguments. Returns a scalar containing the current nickname
370 that the bot is using.
371 "localaddr"
373 Takes no arguments. Returns the IP address being used.
374 "session_id"
376 Takes no arguments. Returns the ID of the component's session. Ideal
377 for posting events to the component.
378 $kernel->post($irc->session_id() => 'mode' => $channel => '+o' => $dude);
380 "session_alias"
382 Takes no arguments. Returns the session alias that has been set through
383 "spawn"'s alias argument.
384 "send_queue"
386 The component provides anti-flood throttling. This method takes no
387 arguments and returns a scalar representing the number of messages that
388 are queued up waiting for dispatch to the irc server.
389 "logged_in"
391 Takes no arguments. Returns true or false depending on whether the IRC
392 component is logged into an IRC network.
393 "connected"
395 Takes no arguments. Returns true or false depending on whether the
396 component's socket is currently connected.
397 "disconnect"
399 Takes no arguments. Terminates the socket connection disgracefully >;o]
400 "raw_events"
402 With no arguments, returns true or false depending on whether "irc_raw"
403 and "irc_raw_out" events are being generated or not. Provide a true or
404 false argument to enable or disable this feature accordingly.
405 "isupport"
407 Takes one argument, a server capability to query. Returns "undef" on
408 failure or a value representing the applicable capability. A full list
409 of capabilities is available at
410 <http://www.irc.org/tech_docs/005.html>.
411 "isupport_dump_keys"
413 Takes no arguments, returns a list of the available server capabilities
414 keys, which can be used with "isupport".
415 "yield"
417 This method provides an alternative object based means of posting
418 events to the component. First argument is the event to post, following
419 arguments are sent as arguments to the resultant post.
420 $irc->yield(mode => $channel => '+o' => $dude);
422 "call"
424 This method provides an alternative object based means of calling
425 events to the component. First argument is the event to call, following
426 arguments are sent as arguments to the resultant call.
427 $irc->call(mode => $channel => '+o' => $dude);
429 "delay"
431 This method provides a way of posting delayed events to the component.
432 The first argument is an arrayref consisting of the delayed command to
433 post and any command arguments. The second argument is the time in
434 seconds that one wishes to delay the command being posted.
435 my $alarm_id = $irc->delay( [ mode => $channel => '+o' => $dude ], 60 );
437 Returns an alarm ID that can be used with "delay_remove" to cancel the
439 delayed event. This will be undefined if something went wrong.
440 "delay_remove"
442 This method removes a previously scheduled delayed event from the
443 component. Takes one argument, the "alarm_id" that was returned by a
444 "delay" method call.
445 my $arrayref = $irc->delay_remove( $alarm_id );
447 Returns an arrayref that was originally requested to be delayed.
449 "resolver"
451 Returns a reference to the POE::Component::Client::DNS object that is
452 internally created by the component.
453 "send_event"
455 Sends an event through the components event handling system. These will
456 get processed by plugins then by registered sessions. First argument is
457 the event name, followed by any parameters for that event.
458
460 How to talk to your new IRC component... here's the events we'll
461 accept. These are events that are posted to the component, either via
462 "$poe_kernel->post()" or via the object method "yield".
463 So the following would be functionally equivalent:
465 sub irc_001 {
467 my ($kernel,$sender) = @_[KERNEL,SENDER];
468 my $irc = $sender->get_heap(); # obtain the poco's object
469 $irc->yield( privmsg => 'foo' => 'Howdy!' );
471 $kernel->post( $sender => privmsg => 'foo' => 'Howdy!' );
472 $kernel->post( $irc->session_id() => privmsg => 'foo' => 'Howdy!' );
473 $kernel->post( $irc->session_alias() => privmsg => 'foo' => 'Howdy!' );
474 return;
476 }
477 Important Commands
479 "register"
480 Takes N arguments: a list of event names that your session wants to
482 listen for, minus the "irc_" prefix. So, for instance, if you just want
483 a bot that keeps track of which people are on a channel, you'll need to
484 listen for JOINs, PARTs, QUITs, and KICKs to people on the channel
485 you're in. You'd tell POE::Component::IRC that you want those events by
486 saying this:
487 $kernel->post('my client', 'register', qw(join part quit kick));
489 Then, whenever people enter or leave a channel your bot is on (forcibly
491 or not), your session will receive events with names like "irc_join",
492 "irc_kick", etc., which you can use to update a list of people on the
493 channel.
494 Registering for 'all' will cause it to send all IRC-related events to
496 you; this is the easiest way to handle it. See the test script for an
497 example.
498 Registering will generate an "irc_registered" event that your session
500 can trap. "ARG0" is the components object. Useful if you want to bolt
501 PoCo-IRC's new features such as Plugins into a bot coded to the older
502 deprecated API. If you are using the new API, ignore this :)
503 Registering with multiple component sessions can be tricky, especially
505 if one wants to marry up sessions/objects, etc. Check the SIGNALS
506 section for an alternative method of registering with multiple poco-
507 ircs.
508 Starting with version 4.96, if you spawn the component from inside
510 another POE session, the component will automatically register that
511 session as wanting 'all' irc events. That session will receive an
512 "irc_registered" event indicating that the component is up and ready to
513 go.
514 "connect"
516 Takes one argument: a hash reference of attributes for the new
518 connection, see "spawn" for details. This event tells the IRC client to
519 connect to a new/different server. If it has a connection already open,
520 it'll close it gracefully before reconnecting.
521 "ctcp" and "ctcpreply"
523 Sends a CTCP query or response to the nick(s) or channel(s) which you
525 specify. Takes 2 arguments: the nick or channel to send a message to
526 (use an array reference here to specify multiple recipients), and the
527 plain text of the message to send (the CTCP quoting will be handled for
528 you). The "/me" command in popular IRC clients is actually a CTCP
529 action.
530 # Doing a /me
532 $irc->yield(ctcp => $channel => 'ACTION dances.');
533 "join"
535 Tells your IRC client to join a single channel of your choice. Takes at
537 least one arg: the channel name (required) and the channel key
538 (optional, for password-protected channels).
539 "kick"
541 Tell the IRC server to forcibly evict a user from a particular channel.
543 Takes at least 2 arguments: a channel name, the nick of the user to
544 boot, and an optional witty message to show them as they sail out the
545 door.
546 "remove" (FreeNode only)
548 Tell the IRC server to forcibly evict a user from a particular channel.
550 Takes at least 2 arguments: a channel name, the nick of the user to
551 boot, and an optional witty message to show them as they sail out the
552 door. Similar to KICK but does an enforced PART instead.
553 "mode"
555 Request a mode change on a particular channel or user. Takes at least
557 one argument: the mode changes to effect, as a single string (e.g.
558 "#mychan +sm-p+o"), and any number of optional operands to the mode
559 changes (nicks, hostmasks, channel keys, whatever.) Or just pass them
560 all as one big string and it'll still work, whatever. I regret that I
561 haven't the patience now to write a detailed explanation, but serious
562 IRC users know the details anyhow.
563 "nick"
565 Allows you to change your nickname. Takes exactly one argument: the new
567 username that you'd like to be known as.
568 "nickserv" (FreeNode, ratbox, et al)
570 Talks to NickServ. Takes any number of arguments.
572 "notice"
574 Sends a NOTICE message to the nick(s) or channel(s) which you specify.
576 Takes 2 arguments: the nick or channel to send a notice to (use an
577 array reference here to specify multiple recipients), and the text of
578 the notice to send.
579 "part"
581 Tell your IRC client to leave the channels which you pass to it. Takes
583 any number of arguments: channel names to depart from. If the last
584 argument doesn't begin with a channel name identifier or contains a
585 space character, it will be treated as a PART message and dealt with
586 accordingly.
587 "privmsg"
589 Sends a public or private message to the nick(s) or channel(s) which
591 you specify. Takes 2 arguments: the nick or channel to send a message
592 to (use an array reference here to specify multiple recipients), and
593 the text of the message to send.
594 Have a look at the constants in POE::Component::IRC::Common if you
596 would like to use formatting and color codes in your messages.
597 "quit"
599 Tells the IRC server to disconnect you. Takes one optional argument:
601 some clever, witty string that other users in your channels will see as
602 you leave. You can expect to get an "irc_disconnected" event shortly
603 after sending this.
604 "shutdown"
606 By default, POE::Component::IRC sessions never go away. Even after
608 they're disconnected, they're still sitting around in the background,
609 waiting for you to call "connect" on them again to reconnect. (Whether
610 this behavior is the Right Thing is doubtful, but I don't want to break
611 backwards compatibility at this point.) You can send the IRC session a
612 "shutdown" event manually to make it delete itself.
613 If you are logged into an IRC server, "shutdown" first will send a quit
615 message and wait to be disconnected. It will wait for up to 5 seconds
616 before forcibly disconnecting from the IRC server. If you provide an
617 argument, that will be used as the QUIT message. If you provide two
618 arguments, the second one will be used as the timeout (in seconds).
619 Terminating multiple components can be tricky. Check the SIGNALS
621 section for a method of shutting down multiple poco-ircs.
622 "topic"
624 Retrieves or sets the topic for particular channel. If called with just
626 the channel name as an argument, it will ask the server to return the
627 current topic. If called with the channel name and a string, it will
628 set the channel topic to that string. Supply an empty string to unset a
629 channel topic.
630 "unregister"
632 Takes N arguments: a list of event names which you don't want to
634 receive. If you've previously done a "register" for a particular event
635 which you no longer care about, this event will tell the IRC connection
636 to stop sending them to you. (If you haven't, it just ignores you. No
637 big deal.)
638 If you have registered with 'all', attempting to unregister individual
640 events such as 'mode', etc. will not work. This is a 'feature'.
641 "debug"
643 Takes one argument: 0 to turn debugging off or 1 to turn debugging on.
645 This flips the debugging flag in POE::Filter::IRCD,
646 POE::Filter::IRC::Compat, and POE::Component::IRC. This has the same
647 effect as setting Debug in "spawn" or "connect".
648 Not-So-Important Commands
650 "admin"
651 Asks your server who your friendly neighborhood server administrators
653 are. If you prefer, you can pass it a server name to query, instead of
654 asking the server you're currently on.
655 "away"
657 When sent with an argument (a message describig where you went), the
659 server will note that you're now away from your machine or otherwise
660 preoccupied, and pass your message along to anyone who tries to
661 communicate with you. When sent without arguments, it tells the server
662 that you're back and paying attention.
663 "cap"
665 Used to query/enable/disable IRC protocol capabilities. Takes any
667 number of arguments.
668 "dcc*"
670 See the DCC plugin (loaded by default) documentation for DCC-related
672 commands.
673 "info"
675 Basically the same as the "version" command, except that the server is
677 permitted to return any information about itself that it thinks is
678 relevant. There's some nice, specific standards-writing for ya, eh?
679 "invite"
681 Invites another user onto an invite-only channel. Takes 2 arguments:
683 the nick of the user you wish to admit, and the name of the channel to
684 invite them to.
685 "ison"
687 Asks the IRC server which users out of a list of nicknames are
689 currently online. Takes any number of arguments: a list of nicknames to
690 query the IRC server about.
691 "links"
693 Asks the server for a list of servers connected to the IRC network.
695 Takes two optional arguments, which I'm too lazy to document here, so
696 all you would-be linklooker writers should probably go dig up the RFC.
697 "list"
699 Asks the server for a list of visible channels and their topics. Takes
701 any number of optional arguments: names of channels to get topic
702 information for. If called without any channel names, it'll list every
703 visible channel on the IRC network. This is usually a really big list,
704 so don't do this often.
705 "motd"
707 Request the server's "Message of the Day", a document which typically
709 contains stuff like the server's acceptable use policy and admin
710 contact email addresses, et cetera. Normally you'll automatically
711 receive this when you log into a server, but if you want it again,
712 here's how to do it. If you'd like to get the MOTD for a server other
713 than the one you're logged into, pass it the server's hostname as an
714 argument; otherwise, no arguments.
715 "names"
717 Asks the server for a list of nicknames on particular channels. Takes
719 any number of arguments: names of channels to get lists of users for.
720 If called without any channel names, it'll tell you the nicks of
721 everyone on the IRC network. This is a really big list, so don't do
722 this much.
723 "quote"
725 Sends a raw line of text to the server. Takes one argument: a string of
727 a raw IRC command to send to the server. It is more optimal to use the
728 events this module supplies instead of writing raw IRC commands
729 yourself.
730 "stats"
732 Returns some information about a server. Kinda complicated and not
734 terribly commonly used, so look it up in the RFC if you're curious.
735 Takes as many arguments as you please.
736 "time"
738 Asks the server what time it thinks it is, which it will return in a
740 human-readable form. Takes one optional argument: a server name to
741 query. If not supplied, defaults to current server.
742 "trace"
744 If you pass a server name or nick along with this request, it asks the
746 server for the list of servers in between you and the thing you
747 mentioned. If sent with no arguments, it will show you all the servers
748 which are connected to your current server.
749 "users"
751 Asks the server how many users are logged into it. Defaults to the
753 server you're currently logged into; however, you can pass a server
754 name as the first argument to query some other machine instead.
755 "version"
757 Asks the server about the version of ircd that it's running. Takes one
759 optional argument: a server name to query. If not supplied, defaults to
760 current server.
761 "who"
763 Lists the logged-on users matching a particular channel name, hostname,
765 nickname, or what-have-you. Takes one optional argument: a string for
766 it to search for. Wildcards are allowed; in the absence of this
767 argument, it will return everyone who's currently logged in (bad move).
768 Tack an "o" on the end if you want to list only IRCops, as per the RFC.
769 "whois"
771 Queries the IRC server for detailed information about a particular
773 user. Takes any number of arguments: nicknames or hostmasks to ask for
774 information about. As of version 3.2, you will receive an "irc_whois"
775 event in addition to the usual numeric responses. See below for
776 details.
777 "whowas"
779 Asks the server for information about nickname which is no longer
781 connected. Takes at least one argument: a nickname to look up (no
782 wildcards allowed), the optional maximum number of history entries to
783 return, and the optional server hostname to query. As of version 3.2,
784 you will receive an "irc_whowas" event in addition to the usual numeric
785 responses. See below for details.
786 "ping" and "pong"
788 Included for completeness sake. The component will deal with ponging to
790 pings automatically. Don't worry about it.
791 Purely Esoteric Commands
793 "die"
794 Tells the IRC server you're connect to, to terminate. Only useful for
796 IRCops, thank goodness. Takes no arguments.
797 "locops"
799 Opers-only command. This one sends a message to all currently logged-on
801 local-opers (+l). This option is specific to EFNet.
802 "oper"
804 In the exceedingly unlikely event that you happen to be an IRC
806 operator, you can use this command to authenticate with your IRC
807 server. Takes 2 arguments: your username and your password.
808 "operwall"
810 Opers-only command. This one sends a message to all currently logged-on
812 global opers. This option is specific to EFNet.
813 "rehash"
815 Tells the IRC server you're connected to, to rehash its configuration
817 files. Only useful for IRCops. Takes no arguments.
818 "restart"
820 Tells the IRC server you're connected to, to shut down and restart
822 itself. Only useful for IRCops, thank goodness. Takes no arguments.
823 "sconnect"
825 Tells one IRC server (which you have operator status on) to connect to
827 another. This is actually the CONNECT command, but I already had an
828 event called "connect", so too bad. Takes the args you'd expect: a
829 server to connect to, an optional port to connect on, and an optional
830 remote server to connect with, instead of the one you're currently on.
831 "squit"
833 Operator-only command used to disconnect server links. Takes two
835 arguments, the server to disconnect and a message explaining your
836 action.
837 "summon"
839 Don't even ask.
841 "servlist"
843 Lists the currently connected services on the network that are visible
845 to you. Takes two optional arguments, a mask for matching service
846 names against, and a service type.
847 "squery"
849 Sends a message to a service. Takes the same arguments as "privmsg".
851 "userhost"
853 Asks the IRC server for information about particular nicknames. (The
855 RFC doesn't define exactly what this is supposed to return.) Takes any
856 number of arguments: the nicknames to look up.
857 "wallops"
859 Another opers-only command. This one sends a message to all currently
861 logged-on opers (and +w users); sort of a mass PA system for the IRC
862 server administrators. Takes one argument: some clever, witty message
863 to send.
864
866 The events you will receive (or can ask to receive) from your running
867 IRC component. Note that all incoming event names your session will
868 receive are prefixed by "irc_", to inhibit event namespace pollution.
869 If you wish, you can ask the client to send you every event it
871 generates. Simply register for the event name "all". This is a lot
872 easier than writing a huge list of things you specifically want to
873 listen for.
874 FIXME: I'd really like to classify these somewhat ("basic", "oper",
876 "ctcp", "dcc", "raw" or some such), and I'd welcome suggestions for
877 ways to make this easier on the user, if you can think of some.
878 In your event handlers, $_[SENDER] is the particular component session
880 that sent you the event. "$_[SENDER]->get_heap()" will retrieve the
881 component's object. Useful if you want on-the-fly access to the object
882 and its methods.
883 Important Events
885 "irc_connected"
886 The IRC component will send an "irc_connected" event as soon as it
888 establishes a connection to an IRC server, before attempting to log in.
889 "ARG0" is the server name.
890 NOTE: When you get an "irc_connected" event, this doesn't mean you can
892 start sending commands to the server yet. Wait until you receive an
893 "irc_001" event (the server welcome message) before actually sending
894 anything back to the server.
895 "irc_ctcp"
897 "irc_ctcp" events are generated upon receipt of CTCP messages, in
899 addition to the "irc_ctcp_*" events mentioned below. They are identical
900 in every way to these, with one difference: instead of the * being in
901 the method name, it is prepended to the argument list. For example, if
902 someone types "/ctcp Flibble foo bar", an "irc_ctcp" event will be sent
903 with 'foo' as "ARG0", and the rest as given below.
904 It is not recommended that you register for both "irc_ctcp" and
906 "irc_ctcp_*" events, since they will both be fired and presumably cause
907 duplication.
908 "irc_ctcp_*"
910 "irc_ctcp_whatever" events are generated upon receipt of CTCP messages.
912 For instance, receiving a CTCP PING request generates an
913 "irc_ctcp_ping" event, CTCP ACTION (produced by typing "/me" in most
914 IRC clients) generates an "irc_ctcp_action" event, blah blah, so on and
915 so forth. "ARG0" is the nick!hostmask of the sender. "ARG1" is the
916 channel/recipient name(s). "ARG2" is the text of the CTCP message. On
917 servers supporting the IDENTIFY-MSG feature (e.g. FreeNode), CTCP
918 ACTIONs will have "ARG3", which will be 1 if the sender has identified
919 with NickServ, 0 otherwise.
920 Note that DCCs are handled separately -- see the DCC plugin.
922 "irc_ctcpreply_*"
924 "irc_ctcpreply_whatever" messages are just like "irc_ctcp_whatever"
926 messages, described above, except that they're generated when a
927 response to one of your CTCP queries comes back. They have the same
928 arguments and such as "irc_ctcp_*" events.
929 "irc_disconnected"
931 The counterpart to "irc_connected", sent whenever a socket connection
933 to an IRC server closes down (whether intentionally or
934 unintentionally). "ARG0" is the server name.
935 "irc_error"
937 You get this whenever the server sends you an ERROR message. Expect
939 this to usually be accompanied by the sudden dropping of your
940 connection. "ARG0" is the server's explanation of the error.
941 "irc_join"
943 Sent whenever someone joins a channel that you're on. "ARG0" is the
945 person's nick!hostmask. "ARG1" is the channel name.
946 "irc_invite"
948 Sent whenever someone offers you an invitation to another channel.
950 "ARG0" is the person's nick!hostmask. "ARG1" is the name of the channel
951 they want you to join.
952 "irc_kick"
954 Sent whenever someone gets booted off a channel that you're on. "ARG0"
956 is the kicker's nick!hostmask. "ARG1" is the channel name. "ARG2" is
957 the nick of the unfortunate kickee. "ARG3" is the explanation string
958 for the kick.
959 "irc_mode"
961 Sent whenever someone changes a channel mode in your presence, or when
963 you change your own user mode. "ARG0" is the nick!hostmask of that
964 someone. "ARG1" is the channel it affects (or your nick, if it's a user
965 mode change). "ARG2" is the mode string (i.e., "+o-b"). The rest of the
966 args ("ARG3 .. $#_") are the operands to the mode string (nicks,
967 hostmasks, channel keys, whatever).
968 "irc_msg"
970 Sent whenever you receive a PRIVMSG command that was addressed to you
972 privately. "ARG0" is the nick!hostmask of the sender. "ARG1" is an
973 array reference containing the nick(s) of the recipients. "ARG2" is the
974 text of the message. On servers supporting the IDENTIFY-MSG feature
975 (e.g. FreeNode), there will be an additional argument, "ARG3", will be
976 1 if the sender has identified with NickServ, 0 otherwise.
977 "irc_nick"
979 Sent whenever you, or someone around you, changes nicks. "ARG0" is the
981 nick!hostmask of the changer. "ARG1" is the new nick that they changed
982 to.
983 "irc_notice"
985 Sent whenever you receive a NOTICE command. "ARG0" is the nick!hostmask
987 of the sender. "ARG1" is an array reference containing the nick(s) or
988 channel name(s) of the recipients. "ARG2" is the text of the NOTICE
989 message.
990 "irc_part"
992 Sent whenever someone leaves a channel that you're on. "ARG0" is the
994 person's nick!hostmask. "ARG1" is the channel name. "ARG2" is the part
995 message.
996 "irc_public"
998 Sent whenever you receive a PRIVMSG command that was sent to a channel.
1000 "ARG0" is the nick!hostmask of the sender. "ARG1" is an array reference
1001 containing the channel name(s) of the recipients. "ARG2" is the text of
1002 the message. On servers supporting the IDENTIFY-MSG feature (e.g.
1003 FreeNode), there will be an additional argument, "ARG3", will be 1 if
1004 the sender has identified with NickServ, 0 otherwise.
1005 "irc_quit"
1007 Sent whenever someone on a channel with you quits IRC (or gets KILLed).
1009 "ARG0" is the nick!hostmask of the person in question. "ARG1" is the
1010 clever, witty message they left behind on the way out.
1011 "irc_socketerr"
1013 Sent when a connection couldn't be established to the IRC server.
1015 "ARG0" is probably some vague and/or misleading reason for what failed.
1016 "irc_topic"
1018 Sent when a channel topic is set or unset. "ARG0" is the nick!hostmask
1020 of the sender. "ARG1" is the channel affected. "ARG2" will be either: a
1021 string if the topic is being set; or a zero-length string (i.e. '') if
1022 the topic is being unset. Note: replies to queries about what a channel
1023 topic *is* (i.e. TOPIC #channel), are returned as numerics, not with
1024 this event.
1025 "irc_whois"
1027 Sent in response to a WHOIS query. "ARG0" is a hashref, with the
1029 following keys:
1030 'nick', the users nickname;
1032 'user', the users username;
1034 'host', their hostname;
1036 'real', their real name;
1038 'idle', their idle time in seconds;
1040 'signon', the epoch time they signed on (will be undef if ircd does not
1042 support this);
1043 'channels', an arrayref listing visible channels they are on, the
1045 channel is prefixed with '@','+','%' depending on whether they have +o
1046 +v or +h;
1047 'server', their server ( might not be useful on some networks );
1049 'oper', whether they are an IRCop, contains the IRC operator string if
1051 they are, undef if they aren't.
1052 'actually', some ircds report the users actual ip address, that'll be
1054 here;
1055 On ircu/seven IRCDs (e.g. FreeNode), if the user has registered with
1057 services, there will be another key:
1058 'account'.
1060 On Hyperion IRCDs, if the user has identified with NICKSERV there will
1062 be an additional key:
1063 'identified'.
1065 "irc_whowas"
1067 Similar to the above, except some keys will be missing.
1069 "irc_raw"
1071 Enabled by passing "Raw => 1" to "spawn" or "connect", or by calling
1073 "raw_events" with a true argument. "ARG0" is the raw IRC string
1074 received by the component from the IRC server, before it has been
1075 mangled by filters and such like.
1076 "irc_raw_out"
1078 Enabled by passing "Raw => 1" to "spawn" or "connect", or by calling
1080 "raw_events" with a true argument. "ARG0" is the raw IRC string sent by
1081 the component to the the IRC server.
1082 "irc_registered"
1084 Sent once to the requesting session on registration (see "register").
1086 "ARG0" is a reference tothe component's object.
1087 "irc_shutdown"
1089 Sent to all registered sessions when the component has been asked to
1091 "shutdown". "ARG0" will be the session ID of the requesting session.
1092 "irc_isupport"
1094 Emitted by the first event after an "irc_005", to indicate that
1096 isupport information has been gathered. "ARG0" is the
1097 POE::Component::IRC::Plugin::ISupport object.
1098 "irc_delay_set"
1100 Emitted on a successful addition of a delayed event using the "delay"
1102 method. "ARG0" will be the alarm_id which can be used later with
1103 "delay_remove". Subsequent parameters are the arguments that were
1104 passed to "delay".
1105 "irc_delay_removed"
1107 Emitted when a delayed command is successfully removed. "ARG0" will be
1109 the alarm_id that was removed. Subsequent parameters are the arguments
1110 that were passed to "delay".
1111 "irc_socks_failed"
1113 Emitted whenever we fail to connect successfully to a SOCKS server or
1115 the SOCKS server is not actually a SOCKS server. "ARG0" will be some
1116 vague reason as to what went wrong. Hopefully.
1117 "irc_socks_rejected"
1119 Emitted whenever a SOCKS connection is rejected by a SOCKS server.
1121 "ARG0" is the SOCKS code, "ARG1" the SOCKS server address, "ARG2" the
1122 SOCKS port and "ARG3" the SOCKS user id (if defined).
1123 Somewhat Less Important Events
1125 "irc_cap"
1126 A reply from the server regarding protocol capabilities. "ARG0" is the
1128 CAP subcommand (e.g. 'LS'). "ARG1" is the result of the subcommand,
1129 unless this is a multi-part reply, in which case "ARG1" is '*' and
1130 "ARG2" contains the result.
1131 "irc_dcc_*"
1133 See the DCC plugin (loaded by default) documentation for DCC-related
1135 events.
1136 "irc_ping"
1138 An event sent whenever the server sends a PING query to the client.
1140 (Don't confuse this with a CTCP PING, which is another beast entirely.
1141 If unclear, read the RFC.) Note that POE::Component::IRC will
1142 automatically take care of sending the PONG response back to the server
1143 for you, although you can still register to catch the event for
1144 informational purposes.
1145 "irc_snotice"
1147 A weird, non-RFC-compliant message from an IRC server. Don't worry
1149 about it. "ARG0" is the text of the server's message.
1150 All numeric events
1152 Most messages from IRC servers are identified only by three-digit
1153 numeric codes with undescriptive constant names like RPL_UMODEIS and
1154 ERR_NOTOPLEVEL. (Actually, the list of codes in the RFC is kind of out-
1155 of-date... the list in the back of Net::IRC::Event.pm is more complete,
1156 and different IRC networks have different and incompatible lists. Ack!)
1157 As an example, say you wanted to handle event 376 (RPL_ENDOFMOTD, which
1158 signals the end of the MOTD message). You'd register for '376', and
1159 listen for "irc_376" events. Simple, no? "ARG0" is the name of the
1160 server which sent the message. "ARG1" is the text of the message.
1161 "ARG2" is an array reference of the parsed message, so there is no need
1162 to parse "ARG1" yourself.
1163
1165 The component will handle a number of custom signals that you may send
1166 using POE::Kernel's "signal" method.
1167 "POCOIRC_REGISTER"
1169 Registering with multiple PoCo-IRC components has been a pita. Well, no
1170 more, using the power of POE::Kernel signals.
1171 If the component receives a "POCOIRC_REGISTER" signal it'll register
1173 the requesting session and trigger an "irc_registered" event. From that
1174 event one can get all the information necessary such as the poco-irc
1175 object and the SENDER session to do whatever one needs to build a poco-
1176 irc dispatch table.
1177 The way the signal handler in PoCo-IRC is written also supports sending
1179 the "POCOIRC_REGISTER" to multiple sessions simultaneously, by sending
1180 the signal to the POE Kernel itself.
1181 Pass the signal your session, session ID or alias, and the IRC events
1183 (as specified to "register").
1184 To register with multiple PoCo-IRCs one can do the following in your
1186 session's _start handler:
1187 sub _start {
1189 my ($kernel, $session) = @_[KERNEL, SESSION];
1190 # Registering with multiple pocoircs for 'all' IRC events
1192 $kernel->signal($kernel, 'POCOIRC_REGISTER', $session->ID(), 'all');
1193 return:
1195 }
1196 Each poco-irc will send your session an "irc_registered" event:
1198 sub irc_registered {
1200 my ($kernel, $sender, $heap, $irc_object) = @_[KERNEL, SENDER, HEAP, ARG0];
1201 # Get the poco-irc session ID
1203 my $sender_id = $sender->ID();
1204 # Or it's alias
1206 my $poco_alias = $irc_object->session_alias();
1207 # Store it in our heap maybe
1209 $heap->{irc_objects}->{ $sender_id } = $irc_object;
1210 # Make the poco connect
1212 $irc_object->yield(connect => { });
1213 return;
1215 }
1216 "POCOIRC_SHUTDOWN"
1218 Telling multiple poco-ircs to shutdown was a pita as well. The same
1219 principle as with registering applies to shutdown too.
1220 Send a "POCOIRC_SHUTDOWN" to the POE Kernel to terminate all the active
1222 poco-ircs simultaneously.
1223 $poe_kernel->signal($poe_kernel, 'POCOIRC_SHUTDOWN');
1225 Any additional parameters passed to the signal will become your quit
1227 messages on each IRC network.
1228
1230 Messages
1231 The only requirement the IRC protocol places on its messages is that
1232 they be 8-bits, and in ASCII. This has resulted in most of the Western
1233 world settling on ASCII-compatible Latin-1 (usually Microsoft's CP1252,
1234 a Latin-1 variant) as a convention. Recently, popular IRC clients
1235 (mIRC, xchat, certain irssi configurations) have begun sending a
1236 mixture of CP1252 and UTF-8 over the wire to allow more characters
1237 without breaking backward compatibility (too much). They send CP1252
1238 encoded messages if the characters fit within that encoding, otherwise
1239 falling back to UTF-8. Writing text with mixed encoding to a file,
1240 terminal, or database is rarely a good idea. To decode such messages
1241 reliably, see "irc_to_utf8" from POE::Component::IRC::Common.
1242 Channel names
1244 This matter is complicated further by the fact that some servers allow
1245 non-ASCII characters in channel names. The IRC component doesn't
1246 explicitly convert between encodings before sending your message along,
1247 but it has to concatenate the channel name and the message before
1248 sending them over the wire. So when you do "$irc->yield(privmsg =>
1249 $chan, 'aed`i')", where $chan is the unmodified channel name you got
1250 from the IRC component (i.e. it's a byte string), the channel name will
1251 end up getting double-encoded when concatenated with the message (which
1252 is a text string). If the channel name is all-ASCII, then nothing bad
1253 will happen, but if there are non-ASCII chars in it, you're in trouble.
1254 To prevent this, you can't simply call "irc_to_utf8" on the channel
1256 name and then use it, because IRC servers don't care about encodings.
1257 '#aed`i' in CP1252 is not the same channel as '#aed`i' in UTF-8. The
1258 channel name and your message must therefore both be byte stirngs, or
1259 both be text strings. If they're text strings, the UTF-8 flag must be
1260 off for both, or on for both.
1261 A simple rule to follow is to call "encode_utf8" on the channel name
1263 and/or message if they are text strings. Here are some examples:
1264 use Encode qw(encode_utf8);
1266 sub irc_public {
1268 my ($who, $where, $what) = @_[ARG0..ARG2];
1269 my $irc = $_[SENDER]->get_heap();
1270 # bad: if $where has any non-ASCII chars, they will get double-encoded
1272 $irc->yield(privmsg => $where, 'aed`i');
1273 # bad: if $what has any non-ASCII chars, they will get double-encoded
1275 $irc->yield(privmsg => '#aed`i', $what);
1276 # good: both are byte strings already, so this does what we expect
1278 $irc->yield(privmsg => $where, $what);
1279 # good: both are text strings (Latin1 as per Perl's default), so
1281 # they'll be concatenated correctly
1282 $irc->yield(privmsg => '#aed`i', 'aed`i');
1283 # good: same as the last one, except now they're both in UTF-8,
1285 # which means we'll be sending the message to a different channel
1286 use utf8;
1287 $irc->yield(privmsg => '#aed`i', 'aed`i');
1288 # good: $where and $msg_bytes are both byte strings
1290 my $msg_bytes = encode_utf8('aed`i');
1291 $irc->yield(privmsg => $where, $msg_bytes);
1292 # good: $chan_bytes and $what are both byte strings
1294 my $chan_bytes = encode_utf8('#aed`i');
1295 $irc->yield(privmsg => $chan_bytes, $what);
1296 }
1297 See also Encode, perluniintro, perlunitut, perlunicode, and perlunifaq.
1299
1301 A few have turned up in the past and they are sure to again. Please use
1302 <http://rt.cpan.org/> to report any. Alternatively, email the current
1303 maintainer.
1304
1306 You can find the latest source on github:
1307 http://github.com/bingos/poe-component-irc
1308 <http://github.com/bingos/poe-component-irc>
1309 The project's developers usually hang out in the "#poe" IRC channel on
1311 irc.freenode.org. Do drop us a line.
1312
1314 Chris "BinGOs" Williams <chris@bingosnet.co.uk>
1315 Hinrik Oern Sigurd`sson <hinrik.sig@gmail.com>
1317
1319 Dennis Taylor.
1320
1322 Copyright (c) Dennis Taylor, Chris Williams and Hinrik Oern Sigurd`sson
1323 This module may be used, modified, and distributed under the same terms
1325 as Perl itself. Please see the license that came with your Perl
1326 distribution for details.
1327
1329 The maddest of mad props go out to Rocco "dngor" Caputo
1330 <troc@netrus.net>, for inventing something as mind-bogglingly cool as
1331 POE, and to Kevin "oznoid" Lenzo <lenzo@cs.cmu.edu>, for being the
1332 attentive parent of our precocious little infobot on #perl.
1333 Further props to a few of the studly bughunters who made this module
1335 not suck: Abys <abys@web1-2-3.com>, Addi <addi@umich.edu>, ResDev
1336 <ben@reser.org>, and Roderick <roderick@argon.org>. Woohoo!
1337 Kudos to Apocalypse, <apocal@cpan.org>, for the plugin system and to
1339 Jeff 'japhy' Pinyan, <japhy@perlmonk.org>, for Pipeline.
1340 Thanks to the merry band of POE pixies from #PoE @ irc.perl.org,
1342 including ( but not limited to ), ketas, ct, dec, integral, webfox,
1343 immute, perigrin, paulv, alias.
1344 Check out the Changes file for further contributors.
1346
1348 RFC 1459 <http://www.faqs.org/rfcs/rfc1459.html>
1349 <http://www.irchelp.org/>,
1351 <http://poe.perl.org/>,
1353 <http://www.infobot.org/>,
1355 Some good examples reside in the POE cookbook which has a whole section
1357 devoted to IRC programming <http://poe.perl.org/?POE_Cookbook>.
1358 The examples/ folder of this distribution.
1360perl v5.12.2 2010-11-05 POE::Component::IRC(3)