POE::Component::IRC(3pm)

1POE::Component::IRC(3)User Contributed Perl DocumentationPOE::Component::IRC(3)
2
3
4

NAME

6       POE::Component::IRC - A fully event-driven IRC client module
7

SYNOPSIS

9        # A simple Rot13 'encryption' bot
10
11        use strict;
12        use warnings;
13        use POE qw(Component::IRC);
14
15        my $nickname = 'Flibble' . $$;
16        my $ircname  = 'Flibble the Sailor Bot';
17        my $server   = 'irc.perl.org';
18
19        my @channels = ('#Blah', '#Foo', '#Bar');
20
21        # 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
28        POE::Session->create(
29            package_states => [
30                main => [ qw(_default _start irc_001 irc_public) ],
31            ],
32            heap => { irc => $irc },
33        );
34
35        $poe_kernel->run();
36
37        sub _start {
38            my $heap = $_[HEAP];
39
40            # retrieve our component's object from the heap where we stashed it
41            my $irc = $heap->{irc};
42
43            $irc->yield( register => 'all' );
44            $irc->yield( connect => { } );
45            return;
46        }
47
48        sub irc_001 {
49            my $sender = $_[SENDER];
50
51            # 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
56            print "Connected to ", $irc->server_name(), "\n";
57
58            # we join our channels
59            $irc->yield( join => $_ ) for @channels;
60            return;
61        }
62
63        sub irc_public {
64            my ($sender, $who, $where, $what) = @_[SENDER, ARG0 .. ARG2];
65            my $nick = ( split /!/, $who )[0];
66            my $channel = $where->[0];
67
68            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
75        # We registered for all events, this will produce some debug info.
76        sub _default {
77            my ($event, $args) = @_[ARG0 .. $#_];
78            my @output = ( "$event: " );
79
80            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;
90        }
91

DESCRIPTION

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
100       [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
107       The POE::Component::IRC distribution has a docs/ folder with a
108       collection of salient documentation including the pertinent RFCs.
109
110       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
115       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
121       The SYNOPSIS demonstrates a fairly basic bot.
122
123       See POE::Component::IRC::Cookbook for more examples.
124
125   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
130       ·   POE::Component::IRC::State
131
132           POE::Component::IRC::State provides all the functionality of
133           POE::Component::IRC but also tracks IRC state entities such as
134           nicks and channels.
135
136       ·   POE::Component::IRC::Qnet
137
138           POE::Component::IRC::Qnet is POE::Component::IRC tweaked for use on
139           Quakenet IRC network.
140
141       ·   POE::Component::IRC::Qnet::State
142
143           POE::Component::IRC::Qnet::State is a tweaked version of
144           POE::Component::IRC::State for use on the Quakenet IRC network.
145
146   The Plugin system
147       As of 3.7, PoCo-IRC sports a plugin system. The documentation for it
148       can be read by looking at POE::Component::IRC::Plugin.  That is not a
149       subclass, just a placeholder for documentation!
150
151       A number of useful plugins have made their way into the core
152       distribution:
153
154       ·   POE::Component::IRC::Plugin::DCC
155
156           Provides DCC support. Loaded by default.
157
158       ·   POE::Component::IRC::Plugin::AutoJoin
159
160           Keeps you on your favorite channels throughout reconnects and even
161           kicks.
162
163       ·   POE::Component::IRC::Plugin::Connector
164
165           Glues an irc bot to an IRC network, i.e. deals with maintaining
166           ircd connections.
167
168       ·   POE::Component::IRC::Plugin::BotTraffic
169
170           Under normal circumstances irc bots do not normal the msgs and
171           public msgs that they generate themselves. This plugin enables you
172           to handle those events.
173
174       ·   POE::Component::IRC::Plugin::BotAddressed
175
176           Generates "irc_bot_addressed" / "irc_bot_mentioned" /
177           "irc_bot_mentioned_action" events whenever your bot's name comes up
178           in channel discussion.
179
180       ·   POE::Component::IRC::Plugin::BotCommand
181
182           Provides an easy way to handle commands issued to your bot.
183
184       ·   POE::Component::IRC::Plugin::Console
185
186           See inside the component. See what events are being sent. Generate
187           irc commands manually. A TCP based console.
188
189       ·   POE::Component::IRC::Plugin::FollowTail
190
191           Follow the tail of an ever-growing file.
192
193       ·   POE::Component::IRC::Plugin::Logger
194
195           Log public and private messages to disk.
196
197       ·   POE::Component::IRC::Plugin::NickServID
198
199           Identify with NickServ when needed.
200
201       ·   POE::Component::IRC::Plugin::Proxy
202
203           A lightweight IRC proxy/bouncer.
204
205       ·   POE::Component::IRC::Plugin::CTCP
206
207           Automagically generates replies to ctcp version, time and userinfo
208           queries.
209
210       ·   POE::Component::IRC::Plugin::PlugMan
211
212           An experimental Plugin Manager plugin.
213
214       ·   POE::Component::IRC::Plugin::NickReclaim
215
216           Automagically deals with your nickname being in use and reclaiming
217           it.
218
219       ·   POE::Component::IRC::Plugin::CycleEmpty
220
221           Cycles (parts and rejoins) channels if they become empty and
222           opless, in order to gain ops.
223

CONSTRUCTORS

225       Both constructors return an object. The object is also available within
226       'irc_' event handlers by using "$_[SENDER]->get_heap()". See also
227       "register" and "irc_registered".
228
229   "spawn"
230       Takes a number of arguments, all of which are optional. All the options
231       below may be supplied to the "connect" input event as well, except for
232       'alias', 'options', 'NoDNS', 'debug', and 'plugin_debug'.
233
234       ·   'alias', a name (kernel alias) that this instance will be known by;
235
236       ·   'options', a hashref containing POE::Session options;
237
238       ·   'Server', the server name;
239
240       ·   'Port', the remote port number;
241
242       ·   'Password', an optional password for restricted servers;
243
244       ·   'Nick', your client's IRC nickname;
245
246       ·   'Username', your client's username;
247
248       ·   'Ircname', some cute comment or something.
249
250       ·   'Bitmode', an integer representing your initial user modes set in
251           the USER command. See RFC 2812. If you do not set this, 8 (+i) will
252           be used.
253
254       ·   'UseSSL', set to some true value if you want to connect using SSL.
255
256       ·   'SSLCert', set to a SSL Certificate(PAM encoded) to connect using a
257           client cert
258
259       ·   'SSLKey', set to a SSL Key(PAM encoded) to connect using a client
260           cert
261
262       ·   'SSLCtx', set to a SSL Context to configure the SSL Connection
263
264           The 'SSLCert' and 'SSLKey' both need to be specified. The 'SSLCtx'
265           takes precedence specified.
266
267       ·   'Raw', set to some true value to enable the component to send
268           "irc_raw" and "irc_raw_out" events.
269
270       ·   'LocalAddr', which local IP address on a multihomed box to connect
271           as;
272
273       ·   'LocalPort', the local TCP port to open your socket on;
274
275       ·   'NoDNS', set this to 1 to disable DNS lookups using PoCo-Client-
276           DNS. (See note below).
277
278       ·   'Flood', when true, it disables the component's flood protection
279           algorithms, allowing it to send messages to an IRC server at full
280           speed. Disconnects and k-lines are some common side effects of
281           flooding IRC servers, so care should be used when enabling this
282           option.  Default is false.
283
284           Two new attributes are 'Proxy' and 'ProxyPort' for sending your
285           =item * 'Proxy', IP address or server name of a proxy server to
286           use.
287
288       ·   'ProxyPort', which tcp port on the proxy to connect to.
289
290       ·   'NATAddr', what other clients see as your IP address.
291
292       ·   'DCCPorts', an arrayref containing tcp ports that can be used for
293           DCC sends.
294
295       ·   'Resolver', provide a POE::Component::Client::DNS object for the
296           component to use.
297
298       ·   'msg_length', the maximum length of IRC messages, in bytes.
299           Default is 450. The IRC component shortens all messages longer than
300           this value minus the length of your current nickname. IRC only
301           allows raw protocol lines messages that are 512 bytes or shorter,
302           including the trailing "\r\n". This is most relevant to long
303           PRIVMSGs. The IRC component can't be sure how long your user@host
304           mask will be every time you send a message, considering that most
305           networks mangle the 'user' part and some even replace the whole
306           string (think FreeNode cloaks). If you have an unusually long
307           user@host mask you might want to decrease this value if you're
308           prone to sending long messages. Conversely, if you have an
309           unusually short one, you can increase this value if you want to be
310           able to send as long a message as possible. Be careful though,
311           increase it too much and the IRC server might disconnect you with a
312           "Request too long" message when you try to send a message that's
313           too long.
314
315       ·   'debug', if set to a true value causes the IRC component to print
316           every message sent to and from the server, as well as print some
317           warnings when it receives malformed messages. This option will be
318           enabled if the "POCOIRC_DEBUG" environment variable is set to a
319           true value.
320
321       ·   'plugin_debug', set to some true value to print plugin debug info,
322           default 0. Plugins are processed inside an eval. When you enable
323           this option, you will be notified when (and why) a plugin raises an
324           exception. This option will be enabled if the "POCOIRC_DEBUG"
325           environment variable is set to a true value.
326
327       ·   'socks_proxy', specify a SOCKS4/SOCKS4a proxy to use.
328
329       ·   'socks_port', the SOCKS port to use, defaults to 1080 if not
330           specified.
331
332       ·   'socks_id', specify a SOCKS user_id. Default is none.
333
334       ·   'useipv6', enable the use of IPv6 for connections.
335
336       ·   'webirc', enable the use of WEBIRC to spoof host/IP.  You must have
337           a WEBIRC password set up on the IRC server/network (so will only
338           work for servers which trust you to spoof the IP & host the
339           connection is from) - value should be a hashref containing keys
340           "pass", "user", "host" and "ip".
341
342       "spawn" will supply reasonable defaults for any of these attributes
343       which are missing, so don't feel obliged to write them all out.
344
345       If the component finds that POE::Component::Client::DNS is installed it
346       will use that to resolve the server name passed. Disable this behaviour
347       if you like, by passing: "NoDNS => 1".
348
349       IRC traffic through a proxy server. 'Proxy''s value should be the IP
350       address or server name of the proxy. 'ProxyPort''s value should be the
351       port on the proxy to connect to. "connect" will default to using the
352       actual IRC server's port if you provide a proxy but omit the proxy's
353       port. These are for HTTP Proxies. See 'socks_proxy' for SOCKS4 and
354       SOCKS4a support.
355
356       For those people who run bots behind firewalls and/or Network Address
357       Translation there are two additional attributes for DCC. 'DCCPorts', is
358       an arrayref of ports to use when initiating DCC connections.
359       'NATAddr', is the NAT'ed IP address that your bot is hidden behind,
360       this is sent whenever you do DCC.
361
362       SSL support requires POE::Component::SSLify, as well as an IRC server
363       that supports SSL connections. If you're missing
364       POE::Component::SSLify, specifying 'UseSSL' will do nothing. The
365       default is to not try to use SSL.
366
367       'Resolver', requires a POE::Component::Client::DNS object. Useful when
368       spawning multiple poco-irc sessions, saves the overhead of multiple dns
369       sessions.
370
371       'NoDNS' has different results depending on whether it is set with
372       "spawn" or "connect". Setting it with "spawn", disables the creation of
373       the POE::Component::Client::DNS completely. Setting it with "connect"
374       on the other hand allows the PoCo-Client-DNS session to be spawned, but
375       will disable any dns lookups using it.
376
377       SOCKS4 proxy support is provided by 'socks_proxy', 'socks_port' and
378       'socks_id' parameters. If something goes wrong with the SOCKS
379       connection you should get a warning on STDERR. This is fairly
380       experimental currently.
381
382       IPv6 support is available for connecting to IPv6 enabled ircds (it
383       won't work for DCC though). To enable it, specify 'useipv6'. Perl
384       >=5.14 or Socket6 (for older Perls) is required. If you that and
385       POE::Component::Client::DNS installed and specify a hostname that
386       resolves to an IPv6 address then IPv6 will be used.  If you specify an
387       ipv6 'localaddr' then IPv6 will be used.
388
389   "new"
390       This method is deprecated. See the "spawn" method instead.  The first
391       argument should be a name (kernel alias) which this new connection will
392       be known by. Optionally takes more arguments (see "spawn" as name/value
393       pairs. Returns a POE::Component::IRC object. :)
394
395       Note: Use of this method will generate a warning. There are currently
396       no plans to make it die() >;]
397

METHODS

399   Information
400       "server"
401
402       Takes no arguments. Returns the server host we are currently connected
403       to (or trying to connect to).
404
405       "port"
406
407       Takes no arguments. Returns the server port we are currently connected
408       to (or trying to connect to).
409
410       "server_name"
411
412       Takes no arguments. Returns the name of the IRC server that the
413       component is currently connected to.
414
415       "server_version"
416
417       Takes no arguments. Returns the IRC server version.
418
419       "nick_name"
420
421       Takes no arguments. Returns a scalar containing the current nickname
422       that the bot is using.
423
424       "localaddr"
425
426       Takes no arguments. Returns the IP address being used.
427
428       "send_queue"
429
430       The component provides anti-flood throttling. This method takes no
431       arguments and returns a scalar representing the number of messages that
432       are queued up waiting for dispatch to the irc server.
433
434       "logged_in"
435
436       Takes no arguments. Returns true or false depending on whether the IRC
437       component is logged into an IRC network.
438
439       "connected"
440
441       Takes no arguments. Returns true or false depending on whether the
442       component's socket is currently connected.
443
444       "disconnect"
445
446       Takes no arguments. Terminates the socket connection disgracefully >;o]
447
448       "isupport"
449
450       Takes one argument, a server capability to query. Returns "undef" on
451       failure or a value representing the applicable capability. A full list
452       of capabilities is available at
453       <http://www.irc.org/tech_docs/005.html>.
454
455       "isupport_dump_keys"
456
457       Takes no arguments, returns a list of the available server capabilities
458       keys, which can be used with "isupport".
459
460       "resolver"
461
462       Returns a reference to the POE::Component::Client::DNS object that is
463       internally created by the component.
464
465   Events
466       "session_id"
467
468       Inherited from POE::Component::Syndicator
469
470       Takes no arguments. Returns the ID of the component's session. Ideal
471       for posting events to the component.
472
473        $kernel->post($irc->session_id() => 'mode' => $channel => '+o' => $dude);
474
475       "session_alias"
476
477       Inherited from POE::Component::Syndicator
478
479       Takes no arguments. Returns the session alias that has been set through
480       "spawn"'s 'alias' argument.
481
482       "raw_events"
483
484       With no arguments, returns true or false depending on whether "irc_raw"
485       and "irc_raw_out" events are being generated or not. Provide a true or
486       false argument to enable or disable this feature accordingly.
487
488       "yield"
489
490       Inherited from POE::Component::Syndicator
491
492       This method provides an alternative object based means of posting
493       events to the component. First argument is the event to post, following
494       arguments are sent as arguments to the resultant post.
495
496        $irc->yield(mode => $channel => '+o' => $dude);
497
498       "call"
499
500       Inherited from POE::Component::Syndicator
501
502       This method provides an alternative object based means of calling
503       events to the component. First argument is the event to call, following
504       arguments are sent as arguments to the resultant call.
505
506        $irc->call(mode => $channel => '+o' => $dude);
507
508       "delay"
509
510       Inherited from POE::Component::Syndicator
511
512       This method provides a way of posting delayed events to the component.
513       The first argument is an arrayref consisting of the delayed command to
514       post and any command arguments. The second argument is the time in
515       seconds that one wishes to delay the command being posted.
516
517        my $alarm_id = $irc->delay( [ mode => $channel => '+o' => $dude ], 60 );
518
519       Returns an alarm ID that can be used with "delay_remove" to cancel the
520       delayed event. This will be undefined if something went wrong.
521
522       "delay_remove"
523
524       Inherited from POE::Component::Syndicator
525
526       This method removes a previously scheduled delayed event from the
527       component.  Takes one argument, the "alarm_id" that was returned by a
528       "delay" method call.
529
530        my $arrayref = $irc->delay_remove( $alarm_id );
531
532       Returns an arrayref that was originally requested to be delayed.
533
534       "send_event"
535
536       Inherited from POE::Component::Syndicator
537
538       Sends an event through the component's event handling system. These
539       will get processed by plugins then by registered sessions. First
540       argument is the event name, followed by any parameters for that event.
541
542       "send_event_next"
543
544       Inherited from POE::Component::Syndicator
545
546       This sends an event right after the one that's currently being
547       processed.  Useful if you want to generate some event which is directly
548       related to another event so you want them to appear together. This
549       method can only be called when POE::Component::IRC is processing an
550       event, e.g. from one of your event handlers. Takes the same arguments
551       as "send_event".
552
553       "send_event_now"
554
555       Inherited from POE::Component::Syndicator
556
557       This will send an event to be processed immediately. This means that if
558       an event is currently being processed and there are plugins or sessions
559       which will receive it after you do, then an event sent with
560       "send_event_now" will be received by those plugins/sessions before the
561       current event. Takes the same arguments as "send_event".
562
563   Plugins
564       "pipeline"
565
566       Inherited from Object::Pluggable
567
568       Returns the Object::Pluggable::Pipeline object.
569
570       "plugin_add"
571
572       Inherited from Object::Pluggable
573
574       Accepts two arguments:
575
576        The alias for the plugin
577        The actual plugin object
578        Any number of extra arguments
579
580       The alias is there for the user to refer to it, as it is possible to
581       have multiple plugins of the same kind active in one Object::Pluggable
582       object.
583
584       This method goes through the pipeline's "push()" method, which will
585       call "$plugin->plugin_register($pluggable, @args)".
586
587       Returns the number of plugins now in the pipeline if plugin was
588       initialized, "undef"/an empty list if not.
589
590       "plugin_del"
591
592       Inherited from Object::Pluggable
593
594       Accepts the following arguments:
595
596        The alias for the plugin or the plugin object itself
597        Any number of extra arguments
598
599       This method goes through the pipeline's "remove()" method, which will
600       call "$plugin->plugin_unregister($pluggable, @args)".
601
602       Returns the plugin object if the plugin was removed, "undef"/an empty
603       list if not.
604
605       "plugin_get"
606
607       Inherited from Object::Pluggable
608
609       Accepts the following arguments:
610
611        The alias for the plugin
612
613       This method goes through the pipeline's "get()" method.
614
615       Returns the plugin object if it was found, "undef"/an empty list if
616       not.
617
618       "plugin_list"
619
620       Inherited from Object::Pluggable
621
622       Takes no arguments.
623
624       Returns a hashref of plugin objects, keyed on alias, or an empty list
625       if there are no plugins loaded.
626
627       "plugin_order"
628
629       Inherited from Object::Pluggable
630
631       Takes no arguments.
632
633       Returns an arrayref of plugin objects, in the order which they are
634       encountered in the pipeline.
635
636       "plugin_register"
637
638       Inherited from Object::Pluggable
639
640       Accepts the following arguments:
641
642        The plugin object
643        The type of the hook (the hook types are specified with _pluggable_init()'s 'types')
644        The event name[s] to watch
645
646       The event names can be as many as possible, or an arrayref. They
647       correspond to the prefixed events and naturally, arbitrary events too.
648
649       You do not need to supply events with the prefix in front of them, just
650       the names.
651
652       It is possible to register for all events by specifying 'all' as an
653       event.
654
655       Returns 1 if everything checked out fine, "undef"/an empty list if
656       something is seriously wrong.
657
658       "plugin_unregister"
659
660       Inherited from Object::Pluggable
661
662       Accepts the following arguments:
663
664        The plugin object
665        The type of the hook (the hook types are specified with _pluggable_init()'s 'types')
666        The event name[s] to unwatch
667
668       The event names can be as many as possible, or an arrayref. They
669       correspond to the prefixed events and naturally, arbitrary events too.
670
671       You do not need to supply events with the prefix in front of them, just
672       the names.
673
674       It is possible to register for all events by specifying 'all' as an
675       event.
676
677       Returns 1 if all the event name[s] was unregistered, undef if some was
678       not found.
679

INPUT EVENTS

681       How to talk to your new IRC component... here's the events we'll
682       accept.  These are events that are posted to the component, either via
683       "$poe_kernel->post()" or via the object method "yield".
684
685       So the following would be functionally equivalent:
686
687        sub irc_001 {
688            my ($kernel,$sender) = @_[KERNEL,SENDER];
689            my $irc = $sender->get_heap(); # obtain the poco's object
690
691            $irc->yield( privmsg => 'foo' => 'Howdy!' );
692            $kernel->post( $sender => privmsg => 'foo' => 'Howdy!' );
693            $kernel->post( $irc->session_id() => privmsg => 'foo' => 'Howdy!' );
694            $kernel->post( $irc->session_alias() => privmsg => 'foo' => 'Howdy!' );
695
696            return;
697        }
698
699   Important Commands
700       "register"
701
702       Inherited from POE::Component::Syndicator
703
704       Takes N arguments: a list of event names that your session wants to
705       listen for, minus the "irc_" prefix. So, for instance, if you just want
706       a bot that keeps track of which people are on a channel, you'll need to
707       listen for JOINs, PARTs, QUITs, and KICKs to people on the channel
708       you're in. You'd tell POE::Component::IRC that you want those events by
709       saying this:
710
711        $kernel->post('my client', 'register', qw(join part quit kick));
712
713       Then, whenever people enter or leave a channel your bot is on (forcibly
714       or not), your session will receive events with names like "irc_join",
715       "irc_kick", etc., which you can use to update a list of people on the
716       channel.
717
718       Registering for 'all' will cause it to send all IRC-related events to
719       you; this is the easiest way to handle it. See the test script for an
720       example.
721
722       Registering will generate an "irc_registered" event that your session
723       can trap. "ARG0" is the components object. Useful if you want to bolt
724       PoCo-IRC's new features such as Plugins into a bot coded to the older
725       deprecated API. If you are using the new API, ignore this :)
726
727       Registering with multiple component sessions can be tricky, especially
728       if one wants to marry up sessions/objects, etc. Check the SIGNALS
729       section for an alternative method of registering with multiple poco-
730       ircs.
731
732       Starting with version 4.96, if you spawn the component from inside
733       another POE session, the component will automatically register that
734       session as wanting 'all' irc events. That session will receive an
735       "irc_registered" event indicating that the component is up and ready to
736       go.
737
738       "unregister"
739
740       Inherited from POE::Component::Syndicator
741
742       Takes N arguments: a list of event names which you don't want to
743       receive. If you've previously done a "register" for a particular event
744       which you no longer care about, this event will tell the IRC connection
745       to stop sending them to you. (If you haven't, it just ignores you. No
746       big deal.)
747
748       If you have registered with 'all', attempting to unregister individual
749       events such as 'mode', etc. will not work. This is a 'feature'.
750
751       "connect"
752
753       Takes one argument: a hash reference of attributes for the new
754       connection, see "spawn" for details. This event tells the IRC client to
755       connect to a new/different server. If it has a connection already open,
756       it'll close it gracefully before reconnecting.
757
758       "ctcp" and "ctcpreply"
759
760       Sends a CTCP query or response to the nick(s) or channel(s) which you
761       specify. Takes 2 arguments: the nick or channel to send a message to
762       (use an array reference here to specify multiple recipients), and the
763       plain text of the message to send (the CTCP quoting will be handled for
764       you). The "/me" command in popular IRC clients is actually a CTCP
765       action.
766
767        # Doing a /me
768        $irc->yield(ctcp => $channel => 'ACTION dances.');
769
770       "join"
771
772       Tells your IRC client to join a single channel of your choice. Takes at
773       least one arg: the channel name (required) and the channel key
774       (optional, for password-protected channels).
775
776       "kick"
777
778       Tell the IRC server to forcibly evict a user from a particular channel.
779       Takes at least 2 arguments: a channel name, the nick of the user to
780       boot, and an optional witty message to show them as they sail out the
781       door.
782
783       "remove"
784
785       Tell the IRC server to forcibly evict a user from a particular channel.
786       Takes at least 2 arguments: a channel name, the nick of the user to
787       boot, and an optional witty message to show them as they sail out the
788       door. Similar to KICK but does an enforced PART instead. Not supported
789       by all servers.
790
791       "mode"
792
793       Request a mode change on a particular channel or user. Takes at least
794       one argument: the mode changes to effect, as a single string (e.g.
795       "#mychan +sm-p+o"), and any number of optional operands to the mode
796       changes (nicks, hostmasks, channel keys, whatever.) Or just pass them
797       all as one big string and it'll still work, whatever. I regret that I
798       haven't the patience now to write a detailed explanation, but serious
799       IRC users know the details anyhow.
800
801       "nick"
802
803       Allows you to change your nickname. Takes exactly one argument: the new
804       username that you'd like to be known as.
805
806       "nickserv"
807
808       Talks to NickServ, on networks which have it. Takes any number of
809       arguments.
810
811       "notice"
812
813       Sends a NOTICE message to the nick(s) or channel(s) which you specify.
814       Takes 2 arguments: the nick or channel to send a notice to (use an
815       array reference here to specify multiple recipients), and the text of
816       the notice to send.
817
818       "part"
819
820       Tell your IRC client to leave the channels which you pass to it. Takes
821       any number of arguments: channel names to depart from. If the last
822       argument doesn't begin with a channel name identifier or contains a
823       space character, it will be treated as a PART message and dealt with
824       accordingly.
825
826       "privmsg"
827
828       Sends a public or private message to the nick(s) or channel(s) which
829       you specify. Takes 2 arguments: the nick or channel to send a message
830       to (use an array reference here to specify multiple recipients), and
831       the text of the message to send.
832
833       Have a look at the constants in IRC::Utils if you would like to use
834       formatting and color codes in your messages.
835
836        $irc->yield('primvsg', '#mychannel', 'Hello there');
837
838        # same, but with a green Hello
839        use IRC::Utils qw(GREEN NORMAL);
840        $irc->yield('primvsg', '#mychannel', GREEN.'Hello'.NORMAL.' there');
841
842       "quit"
843
844       Tells the IRC server to disconnect you. Takes one optional argument:
845       some clever, witty string that other users in your channels will see as
846       you leave. You can expect to get an "irc_disconnected" event shortly
847       after sending this.
848
849       "shutdown"
850
851       By default, POE::Component::IRC sessions never go away. Even after
852       they're disconnected, they're still sitting around in the background,
853       waiting for you to call "connect" on them again to reconnect. (Whether
854       this behavior is the Right Thing is doubtful, but I don't want to break
855       backwards compatibility at this point.) You can send the IRC session a
856       "shutdown" event manually to make it delete itself.
857
858       If you are logged into an IRC server, "shutdown" first will send a quit
859       message and wait to be disconnected. It will wait for up to 5 seconds
860       before forcibly disconnecting from the IRC server. If you provide an
861       argument, that will be used as the QUIT message. If you provide two
862       arguments, the second one will be used as the timeout (in seconds).
863
864       Terminating multiple components can be tricky. Check the SIGNALS
865       section for a method of shutting down multiple poco-ircs.
866
867       "topic"
868
869       Retrieves or sets the topic for particular channel. If called with just
870       the channel name as an argument, it will ask the server to return the
871       current topic. If called with the channel name and a string, it will
872       set the channel topic to that string. Supply an empty string to unset a
873       channel topic.
874
875       "debug"
876
877       Takes one argument: 0 to turn debugging off or 1 to turn debugging on.
878       This flips the debugging flag in POE::Filter::IRCD,
879       POE::Filter::IRC::Compat, and POE::Component::IRC. This has the same
880       effect as setting Debug in "spawn" or "connect".
881
882   Not-So-Important Commands
883       "admin"
884
885       Asks your server who your friendly neighborhood server administrators
886       are. If you prefer, you can pass it a server name to query, instead of
887       asking the server you're currently on.
888
889       "away"
890
891       When sent with an argument (a message describig where you went), the
892       server will note that you're now away from your machine or otherwise
893       preoccupied, and pass your message along to anyone who tries to
894       communicate with you. When sent without arguments, it tells the server
895       that you're back and paying attention.
896
897       "cap"
898
899       Used to query/enable/disable IRC protocol capabilities. Takes any
900       number of arguments.
901
902       "dcc*"
903
904       See the DCC plugin (loaded by default) documentation for DCC-related
905       commands.
906
907       "info"
908
909       Basically the same as the "version" command, except that the server is
910       permitted to return any information about itself that it thinks is
911       relevant. There's some nice, specific standards-writing for ya, eh?
912
913       "invite"
914
915       Invites another user onto an invite-only channel. Takes 2 arguments:
916       the nick of the user you wish to admit, and the name of the channel to
917       invite them to.
918
919       "ison"
920
921       Asks the IRC server which users out of a list of nicknames are
922       currently online. Takes any number of arguments: a list of nicknames to
923       query the IRC server about.
924
925       "links"
926
927       Asks the server for a list of servers connected to the IRC network.
928       Takes two optional arguments, which I'm too lazy to document here, so
929       all you would-be linklooker writers should probably go dig up the RFC.
930
931       "list"
932
933       Asks the server for a list of visible channels and their topics. Takes
934       any number of optional arguments: names of channels to get topic
935       information for. If called without any channel names, it'll list every
936       visible channel on the IRC network. This is usually a really big list,
937       so don't do this often.
938
939       "motd"
940
941       Request the server's "Message of the Day", a document which typically
942       contains stuff like the server's acceptable use policy and admin
943       contact email addresses, et cetera. Normally you'll automatically
944       receive this when you log into a server, but if you want it again,
945       here's how to do it. If you'd like to get the MOTD for a server other
946       than the one you're logged into, pass it the server's hostname as an
947       argument; otherwise, no arguments.
948
949       "names"
950
951       Asks the server for a list of nicknames on particular channels. Takes
952       any number of arguments: names of channels to get lists of users for.
953       If called without any channel names, it'll tell you the nicks of
954       everyone on the IRC network. This is a really big list, so don't do
955       this much.
956
957       "quote"
958
959       Sends a raw line of text to the server. Takes one argument: a string of
960       a raw IRC command to send to the server. It is more optimal to use the
961       events this module supplies instead of writing raw IRC commands
962       yourself.
963
964       "stats"
965
966       Returns some information about a server. Kinda complicated and not
967       terribly commonly used, so look it up in the RFC if you're curious.
968       Takes as many arguments as you please.
969
970       "time"
971
972       Asks the server what time it thinks it is, which it will return in a
973       human-readable form. Takes one optional argument: a server name to
974       query. If not supplied, defaults to current server.
975
976       "trace"
977
978       If you pass a server name or nick along with this request, it asks the
979       server for the list of servers in between you and the thing you
980       mentioned. If sent with no arguments, it will show you all the servers
981       which are connected to your current server.
982
983       "users"
984
985       Asks the server how many users are logged into it. Defaults to the
986       server you're currently logged into; however, you can pass a server
987       name as the first argument to query some other machine instead.
988
989       "version"
990
991       Asks the server about the version of ircd that it's running. Takes one
992       optional argument: a server name to query. If not supplied, defaults to
993       current server.
994
995       "who"
996
997       Lists the logged-on users matching a particular channel name, hostname,
998       nickname, or what-have-you. Takes one optional argument: a string for
999       it to search for. Wildcards are allowed; in the absence of this
1000       argument, it will return everyone who's currently logged in (bad move).
1001       Tack an "o" on the end if you want to list only IRCops, as per the RFC.
1002
1003       "whois"
1004
1005       Queries the IRC server for detailed information about a particular
1006       user. Takes any number of arguments: nicknames or hostmasks to ask for
1007       information about. As of version 3.2, you will receive an "irc_whois"
1008       event in addition to the usual numeric responses. See below for
1009       details.
1010
1011       "whowas"
1012
1013       Asks the server for information about nickname which is no longer
1014       connected. Takes at least one argument: a nickname to look up (no
1015       wildcards allowed), the optional maximum number of history entries to
1016       return, and the optional server hostname to query. As of version 3.2,
1017       you will receive an "irc_whowas" event in addition to the usual numeric
1018       responses. See below for details.
1019
1020       "ping" and "pong"
1021
1022       Included for completeness sake. The component will deal with ponging to
1023       pings automatically. Don't worry about it.
1024
1025   Purely Esoteric Commands
1026       "die"
1027
1028       Tells the IRC server you're connect to, to terminate. Only useful for
1029       IRCops, thank goodness. Takes no arguments.
1030
1031       "locops"
1032
1033       Opers-only command. This one sends a message to all currently logged-on
1034       local-opers (+l). This option is specific to EFNet.
1035
1036       "oper"
1037
1038       In the exceedingly unlikely event that you happen to be an IRC
1039       operator, you can use this command to authenticate with your IRC
1040       server. Takes 2 arguments: your username and your password.
1041
1042       "operwall"
1043
1044       Opers-only command. This one sends a message to all currently logged-on
1045       global opers. This option is specific to EFNet.
1046
1047       "rehash"
1048
1049       Tells the IRC server you're connected to, to rehash its configuration
1050       files. Only useful for IRCops. Takes no arguments.
1051
1052       "restart"
1053
1054       Tells the IRC server you're connected to, to shut down and restart
1055       itself.  Only useful for IRCops, thank goodness. Takes no arguments.
1056
1057       "sconnect"
1058
1059       Tells one IRC server (which you have operator status on) to connect to
1060       another. This is actually the CONNECT command, but I already had an
1061       event called "connect", so too bad. Takes the args you'd expect: a
1062       server to connect to, an optional port to connect on, and an optional
1063       remote server to connect with, instead of the one you're currently on.
1064
1065       "squit"
1066
1067       Operator-only command used to disconnect server links. Takes two
1068       arguments, the server to disconnect and a message explaining your
1069       action.
1070
1071       "summon"
1072
1073       Don't even ask.
1074
1075       "servlist"
1076
1077       Lists the currently connected services on the network that are visible
1078       to you.  Takes two optional arguments, a mask for matching service
1079       names against, and a service type.
1080
1081       "squery"
1082
1083       Sends a message to a service. Takes the same arguments as "privmsg".
1084
1085       "userhost"
1086
1087       Asks the IRC server for information about particular nicknames. (The
1088       RFC doesn't define exactly what this is supposed to return.) Takes any
1089       number of arguments: the nicknames to look up.
1090
1091       "wallops"
1092
1093       Another opers-only command. This one sends a message to all currently
1094       logged-on opers (and +w users); sort of a mass PA system for the IRC
1095       server administrators. Takes one argument: some clever, witty message
1096       to send.
1097

OUTPUT EVENTS

1099       The events you will receive (or can ask to receive) from your running
1100       IRC component. Note that all incoming event names your session will
1101       receive are prefixed by "irc_", to inhibit event namespace pollution.
1102
1103       If you wish, you can ask the client to send you every event it
1104       generates. Simply register for the event name "all". This is a lot
1105       easier than writing a huge list of things you specifically want to
1106       listen for.
1107
1108       FIXME: I'd really like to classify these somewhat ("basic", "oper",
1109       "ctcp", "dcc", "raw" or some such), and I'd welcome suggestions for
1110       ways to make this easier on the user, if you can think of some.
1111
1112       In your event handlers, $_[SENDER] is the particular component session
1113       that sent you the event. "$_[SENDER]->get_heap()" will retrieve the
1114       component's object. Useful if you want on-the-fly access to the object
1115       and its methods.
1116
1117   Important Events
1118       "irc_registered"
1119
1120       Inherited from POE::Component::Syndicator
1121
1122       Sent once to the requesting session on registration (see "register").
1123       "ARG0" is a reference tothe component's object.
1124
1125       "irc_shutdown"
1126
1127       Inherited from POE::Component::Syndicator
1128
1129       Sent to all registered sessions when the component has been asked to
1130       "shutdown". "ARG0" will be the session ID of the requesting session.
1131
1132       "irc_connected"
1133
1134       The IRC component will send an "irc_connected" event as soon as it
1135       establishes a connection to an IRC server, before attempting to log in.
1136       "ARG0" is the server name.
1137
1138       NOTE: When you get an "irc_connected" event, this doesn't mean you can
1139       start sending commands to the server yet. Wait until you receive an
1140       "irc_001" event (the server welcome message) before actually sending
1141       anything back to the server.
1142
1143       "irc_ctcp"
1144
1145       "irc_ctcp" events are generated upon receipt of CTCP messages, in
1146       addition to the "irc_ctcp_*" events mentioned below. They are identical
1147       in every way to these, with one difference: instead of the * being in
1148       the method name, it is prepended to the argument list. For example, if
1149       someone types "/ctcp Flibble foo bar", an "irc_ctcp" event will be sent
1150       with 'foo' as "ARG0", and the rest as given below.
1151
1152       It is not recommended that you register for both "irc_ctcp" and
1153       "irc_ctcp_*" events, since they will both be fired and presumably cause
1154       duplication.
1155
1156       "irc_ctcp_*"
1157
1158       "irc_ctcp_whatever" events are generated upon receipt of CTCP messages.
1159       For instance, receiving a CTCP PING request generates an
1160       "irc_ctcp_ping" event, CTCP ACTION (produced by typing "/me" in most
1161       IRC clients) generates an "irc_ctcp_action" event, blah blah, so on and
1162       so forth. "ARG0" is the nick!hostmask of the sender. "ARG1" is the
1163       channel/recipient name(s). "ARG2" is the text of the CTCP message. On
1164       servers supporting the IDENTIFY-MSG feature (e.g. FreeNode), CTCP
1165       ACTIONs will have "ARG3", which will be 1 if the sender has identified
1166       with NickServ, 0 otherwise.
1167
1168       Note that DCCs are handled separately -- see the DCC plugin.
1169
1170       "irc_ctcpreply_*"
1171
1172       "irc_ctcpreply_whatever" messages are just like "irc_ctcp_whatever"
1173       messages, described above, except that they're generated when a
1174       response to one of your CTCP queries comes back. They have the same
1175       arguments and such as "irc_ctcp_*" events.
1176
1177       "irc_disconnected"
1178
1179       The counterpart to "irc_connected", sent whenever a socket connection
1180       to an IRC server closes down (whether intentionally or
1181       unintentionally). "ARG0" is the server name.
1182
1183       "irc_error"
1184
1185       You get this whenever the server sends you an ERROR message. Expect
1186       this to usually be accompanied by the sudden dropping of your
1187       connection. "ARG0" is the server's explanation of the error.
1188
1189       "irc_join"
1190
1191       Sent whenever someone joins a channel that you're on. "ARG0" is the
1192       person's nick!hostmask. "ARG1" is the channel name.
1193
1194       "irc_invite"
1195
1196       Sent whenever someone offers you an invitation to another channel.
1197       "ARG0" is the person's nick!hostmask. "ARG1" is the name of the channel
1198       they want you to join.
1199
1200       "irc_kick"
1201
1202       Sent whenever someone gets booted off a channel that you're on. "ARG0"
1203       is the kicker's nick!hostmask. "ARG1" is the channel name. "ARG2" is
1204       the nick of the unfortunate kickee. "ARG3" is the explanation string
1205       for the kick.
1206
1207       "irc_mode"
1208
1209       Sent whenever someone changes a channel mode in your presence, or when
1210       you change your own user mode. "ARG0" is the nick!hostmask of that
1211       someone. "ARG1" is the channel it affects (or your nick, if it's a user
1212       mode change). "ARG2" is the mode string (i.e., "+o-b"). The rest of the
1213       args ("ARG3 .. $#_") are the operands to the mode string (nicks,
1214       hostmasks, channel keys, whatever).
1215
1216       "irc_msg"
1217
1218       Sent whenever you receive a PRIVMSG command that was addressed to you
1219       privately. "ARG0" is the nick!hostmask of the sender. "ARG1" is an
1220       array reference containing the nick(s) of the recipients. "ARG2" is the
1221       text of the message. On servers supporting the IDENTIFY-MSG feature
1222       (e.g.  FreeNode), there will be an additional argument, "ARG3", which
1223       will be 1 if the sender has identified with NickServ, 0 otherwise.
1224
1225       "irc_nick"
1226
1227       Sent whenever you, or someone around you, changes nicks. "ARG0" is the
1228       nick!hostmask of the changer. "ARG1" is the new nick that they changed
1229       to.
1230
1231       "irc_notice"
1232
1233       Sent whenever you receive a NOTICE command. "ARG0" is the nick!hostmask
1234       of the sender. "ARG1" is an array reference containing the nick(s) or
1235       channel name(s) of the recipients. "ARG2" is the text of the NOTICE
1236       message.
1237
1238       "irc_part"
1239
1240       Sent whenever someone leaves a channel that you're on. "ARG0" is the
1241       person's nick!hostmask. "ARG1" is the channel name. "ARG2" is the part
1242       message.
1243
1244       "irc_public"
1245
1246       Sent whenever you receive a PRIVMSG command that was sent to a channel.
1247       "ARG0" is the nick!hostmask of the sender. "ARG1" is an array reference
1248       containing the channel name(s) of the recipients. "ARG2" is the text of
1249       the message. On servers supporting the IDENTIFY-MSG feature (e.g.
1250       FreeNode), there will be an additional argument, "ARG3", which will be
1251       1 if the sender has identified with NickServ, 0 otherwise.
1252
1253       "irc_quit"
1254
1255       Sent whenever someone on a channel with you quits IRC (or gets KILLed).
1256       "ARG0" is the nick!hostmask of the person in question. "ARG1" is the
1257       clever, witty message they left behind on the way out.
1258
1259       "irc_socketerr"
1260
1261       Sent when a connection couldn't be established to the IRC server.
1262       "ARG0" is probably some vague and/or misleading reason for what failed.
1263
1264       "irc_topic"
1265
1266       Sent when a channel topic is set or unset. "ARG0" is the nick!hostmask
1267       of the sender. "ARG1" is the channel affected. "ARG2" will be either: a
1268       string if the topic is being set; or a zero-length string (i.e. '') if
1269       the topic is being unset. Note: replies to queries about what a channel
1270       topic *is* (i.e. TOPIC #channel), are returned as numerics, not with
1271       this event.
1272
1273       "irc_whois"
1274
1275       Sent in response to a WHOIS query. "ARG0" is a hashref, with the
1276       following keys:
1277
1278       ·   'nick', the users nickname;
1279
1280       ·   'user', the users username;
1281
1282       ·   'host', their hostname;
1283
1284       ·   'real', their real name;
1285
1286       ·   'idle', their idle time in seconds;
1287
1288       ·   'signon', the epoch time they signed on (will be undef if ircd does
1289           not support this);
1290
1291       ·   'channels', an arrayref listing visible channels they are on, the
1292           channel is prefixed with '@','+','%' depending on whether they have
1293           +o +v or +h;
1294
1295       ·   'server', their server (might not be useful on some networks);
1296
1297       ·   'oper', whether they are an IRCop, contains the IRC operator string
1298           if they are, undef if they aren't.
1299
1300       ·   'actually', some ircds report the user's actual ip address, that'll
1301           be here;
1302
1303       ·   'identified'. if the user has identified with NICKSERV (ircu,
1304           seven, Plexus)
1305
1306       ·   'modes', a string describing the user's modes (Rizon)
1307
1308       "irc_whowas"
1309
1310       Similar to the above, except some keys will be missing.
1311
1312       "irc_raw"
1313
1314       Enabled by passing "Raw => 1" to "spawn" or "connect", or by calling
1315       "raw_events" with a true argument. "ARG0" is the raw IRC string
1316       received by the component from the IRC server, before it has been
1317       mangled by filters and such like.
1318
1319       "irc_raw_out"
1320
1321       Enabled by passing "Raw => 1" to "spawn" or "connect", or by calling
1322       "raw_events" with a true argument. "ARG0" is the raw IRC string sent by
1323       the component to the the IRC server.
1324
1325       "irc_isupport"
1326
1327       Emitted by the first event after an "irc_005", to indicate that
1328       isupport information has been gathered. "ARG0" is the
1329       POE::Component::IRC::Plugin::ISupport object.
1330
1331       "irc_socks_failed"
1332
1333       Emitted whenever we fail to connect successfully to a SOCKS server or
1334       the SOCKS server is not actually a SOCKS server. "ARG0" will be some
1335       vague reason as to what went wrong. Hopefully.
1336
1337       "irc_socks_rejected"
1338
1339       Emitted whenever a SOCKS connection is rejected by a SOCKS server.
1340       "ARG0" is the SOCKS code, "ARG1" the SOCKS server address, "ARG2" the
1341       SOCKS port and "ARG3" the SOCKS user id (if defined).
1342
1343       "irc_plugin_add"
1344
1345       Inherited from Object::Pluggable
1346
1347       Emitted whenever a new plugin is added to the pipeline. "ARG0" is the
1348       plugin alias. "ARG1" is the plugin object.
1349
1350       "irc_plugin_del"
1351
1352       Inherited from Object::Pluggable
1353
1354       Emitted whenever a plugin is removed from the pipeline. "ARG0" is the
1355       plugin alias. "ARG1" is the plugin object.
1356
1357       "irc_plugin_error"
1358
1359       Inherited from Object::Pluggable
1360
1361       Emitted when an error occurs while executing a plugin handler. "ARG0"
1362       is the error message. "ARG1" is the plugin alias. "ARG2" is the plugin
1363       object.
1364
1365   Somewhat Less Important Events
1366       "irc_cap"
1367
1368       A reply from the server regarding protocol capabilities. "ARG0" is the
1369       CAP subcommand (e.g. 'LS'). "ARG1" is the result of the subcommand,
1370       unless this is a multi-part reply, in which case "ARG1" is '*' and
1371       "ARG2" contains the result.
1372
1373       "irc_dcc_*"
1374
1375       See the DCC plugin (loaded by default) documentation for DCC-related
1376       events.
1377
1378       "irc_ping"
1379
1380       An event sent whenever the server sends a PING query to the client.
1381       (Don't confuse this with a CTCP PING, which is another beast entirely.
1382       If unclear, read the RFC.) Note that POE::Component::IRC will
1383       automatically take care of sending the PONG response back to the server
1384       for you, although you can still register to catch the event for
1385       informational purposes.
1386
1387       "irc_snotice"
1388
1389       A weird, non-RFC-compliant message from an IRC server. Usually sent
1390       during to you during an authentication phase right after you connect,
1391       while the server does a hostname lookup or similar tasks. "ARG0" is the
1392       text of the server's message. "ARG1" is the target, which could be '*'
1393       or 'AUTH' or whatever. Servers vary as to whether these notices include
1394       a server name as the sender, or no sender at all. "ARG1" is the sender,
1395       if any.
1396
1397       "irc_delay_set"
1398
1399       Inherited from POE::Component::Syndicator
1400
1401       Emitted on a successful addition of a delayed event using the "delay"
1402       method. "ARG0" will be the alarm_id which can be used later with
1403       "delay_remove". Subsequent parameters are the arguments that were
1404       passed to "delay".
1405
1406       "irc_delay_removed"
1407
1408       Inherited from POE::Component::Syndicator
1409
1410       Emitted when a delayed command is successfully removed. "ARG0" will be
1411       the alarm_id that was removed. Subsequent parameters are the arguments
1412       that were passed to "delay".
1413
1414   All numeric events
1415       Most messages from IRC servers are identified only by three-digit
1416       numeric codes with undescriptive constant names like RPL_UMODEIS and
1417       ERR_NOTOPLEVEL. (Actually, the list of codes in the RFC is kind of out-
1418       of-date... the list in the back of Net::IRC::Event.pm is more complete,
1419       and different IRC networks have different and incompatible lists. Ack!)
1420       As an example, say you wanted to handle event 376 (RPL_ENDOFMOTD, which
1421       signals the end of the MOTD message). You'd register for '376', and
1422       listen for "irc_376" events. Simple, no? "ARG0" is the name of the
1423       server which sent the message. "ARG1" is the text of the message.
1424       "ARG2" is an array reference of the parsed message, so there is no need
1425       to parse "ARG1" yourself.
1426

SIGNALS

1428       The component will handle a number of custom signals that you may send
1429       using POE::Kernel's "signal" method.
1430
1431   "POCOIRC_REGISTER"
1432       Inherited from POE::Component::Syndicator
1433
1434       Registering with multiple PoCo-IRC components has been a pita. Well, no
1435       more, using the power of POE::Kernel signals.
1436
1437       If the component receives a "POCOIRC_REGISTER" signal it'll register
1438       the requesting session and trigger an "irc_registered" event. From that
1439       event one can get all the information necessary such as the poco-irc
1440       object and the SENDER session to do whatever one needs to build a poco-
1441       irc dispatch table.
1442
1443       The way the signal handler in PoCo-IRC is written also supports sending
1444       the "POCOIRC_REGISTER" to multiple sessions simultaneously, by sending
1445       the signal to the POE Kernel itself.
1446
1447       Pass the signal your session, session ID or alias, and the IRC events
1448       (as specified to "register").
1449
1450       To register with multiple PoCo-IRCs one can do the following in your
1451       session's _start handler:
1452
1453        sub _start {
1454            my ($kernel, $session) = @_[KERNEL, SESSION];
1455
1456            # Registering with multiple pocoircs for 'all' IRC events
1457            $kernel->signal($kernel, 'POCOIRC_REGISTER', $session->ID(), 'all');
1458
1459            return:
1460        }
1461
1462       Each poco-irc will send your session an "irc_registered" event:
1463
1464        sub irc_registered {
1465            my ($kernel, $sender, $heap, $irc_object) = @_[KERNEL, SENDER, HEAP, ARG0];
1466
1467            # Get the poco-irc session ID
1468            my $sender_id = $sender->ID();
1469
1470            # Or it's alias
1471            my $poco_alias = $irc_object->session_alias();
1472
1473            # Store it in our heap maybe
1474            $heap->{irc_objects}->{ $sender_id } = $irc_object;
1475
1476            # Make the poco connect
1477            $irc_object->yield(connect => { });
1478
1479            return;
1480        }
1481
1482   "POCOIRC_SHUTDOWN"
1483       Inherited from POE::Component::Syndicator
1484
1485       Telling multiple poco-ircs to shutdown was a pita as well. The same
1486       principle as with registering applies to shutdown too.
1487
1488       Send a "POCOIRC_SHUTDOWN" to the POE Kernel to terminate all the active
1489       poco-ircs simultaneously.
1490
1491        $poe_kernel->signal($poe_kernel, 'POCOIRC_SHUTDOWN');
1492
1493       Any additional parameters passed to the signal will become your quit
1494       messages on each IRC network.
1495

ENCODING

1497       This can be an issue. Take a look at IRC::Utils' section on it.
1498

BUGS

1500       A few have turned up in the past and they are sure to again. Please use
1501       <http://rt.cpan.org/> to report any. Alternatively, email the current
1502       maintainer.
1503

DEVELOPMENT

1505       You can find the latest source on github:
1506       <http://github.com/bingos/poe-component-irc>
1507
1508       The project's developers usually hang out in the "#poe" IRC channel on
1509       irc.perl.org. Do drop us a line.
1510

MAINTAINERS

1512       Chris "BinGOs" Williams <chris@bingosnet.co.uk>
1513
1514       Hinrik Örn Sigurðsson <hinrik.sig@gmail.com>
1515

AUTHOR

1517       Dennis Taylor.
1518

LICENCE

1520       Copyright (c) Dennis Taylor, Chris Williams and Hinrik Örn Sigurðsson
1521
1522       This module may be used, modified, and distributed under the same terms
1523       as Perl itself. Please see the license that came with your Perl
1524       distribution for details.
1525

MAD PROPS

1527       The maddest of mad props go out to Rocco "dngor" Caputo
1528       <troc@netrus.net>, for inventing something as mind-bogglingly cool as
1529       POE, and to Kevin "oznoid" Lenzo <lenzo@cs.cmu.edu>, for being the
1530       attentive parent of our precocious little infobot on #perl.
1531
1532       Further props to a few of the studly bughunters who made this module
1533       not suck: Abys <abys@web1-2-3.com>, Addi <addi@umich.edu>, ResDev
1534       <ben@reser.org>, and Roderick <roderick@argon.org>. Woohoo!
1535
1536       Kudos to Apocalypse, <apocal@cpan.org>, for the plugin system and to
1537       Jeff 'japhy' Pinyan, <japhy@perlmonk.org>, for Pipeline.
1538
1539       Thanks to the merry band of POE pixies from #PoE @ irc.perl.org,
1540       including ( but not limited to ), ketas, ct, dec, integral, webfox,
1541       immute, perigrin, paulv, alias.
1542
1543       IP functions are shamelessly 'borrowed' from Net::IP by Manuel Valente
1544
1545       Check out the Changes file for further contributors.
1546