]> git.somenet.org - irc/bugbot.git/blob - BotModules/devel.txt
GITOLITE.txt
[irc/bugbot.git] / BotModules / devel.txt
1 MODULE API DOCUMENTATION  
2 ========================
3
4 This file documents the mozbot 2.5 bot module API.
5 Revisions are welcome.
6
7 Sample module
8 -------------
9
10 Here is the HelloWorld module:
11
12 ################################
13 # Hello World Module           #
14 ################################
15
16 package BotModules::HelloWorld;
17 use vars qw(@ISA);
18 @ISA = qw(BotModules);
19 1;
20
21 sub Help {
22     my $self = shift;
23     my ($event) = @_;
24     return {
25         '' => 'This is the demo module that says Hello World.',
26         'hi' => 'Requests that the bot emit a hello world string.',
27     };
28 }
29
30 sub Told {
31     my $self = shift;
32     my ($event, $message) = @_;
33     if ($message =~ /^\s*hi\s*$/osi) {
34         $self->say($event, 'Hello World!');
35     } else {
36         return $self->SUPER::Told(@_);
37     }
38 }
39
40 ################################
41
42
43 Creating a module
44 -----------------
45
46 Modules are perl objects with names that start with 'BotModules::'
47 and that are stored in files with the '.bm' extension in the
48 'BotModules' directory. The first non-comment line of each module
49 should be the 'package' line, which in the HelloWorld module reads:
50
51    package BotModules::HelloWorld;
52
53 For a module to work correctly, it should inherit from the
54 'BotModules' module (which is implemented internally in the main bot
55 executable). This is done by including the following two lines
56 immediately after the 'package' line:
57
58    use vars qw(@ISA);
59    @ISA = qw(BotModules);
60
61 Since modules are dynamically loaded and unloaded, they should avoid
62 using package globals. All variables should be stored in the '$self'
63 blessed hashref. For more details, see the documentation of the
64 'Initialise' function (below). Another result of the dynamic nature
65 of modules is that they should not use BEGIN {} or END {} blocks, nor
66 should they execute any code during their evaluation. Thus,
67 immediately after the @ISA... line, the module should return success.
68 This can be done easily:
69
70    1;
71
72 Following this, you are free to implement all the functions you need
73 for your module. Certain functions have certain calling semantics,
74 these are described below.
75
76
77 Module Functions
78 ----------------
79
80 This section contains the names and descriptions of the functions in
81 your module that will be called automatically depending on what is
82 happening on IRC.
83
84 All your functions should start by shifting the $self variable from
85 the argument list:
86
87    my $self = shift;
88
89 After this, it is common to get the other variables too:
90
91    my ($event, @anythingElse) = @_;
92
93 ...where the bit in the brackets is given in the brackets of the
94 definitions of the functions as shown below. For example, for
95 JoinedChannel it would be ($event, $channel), so a function to
96 override the default JoinedChannel action would be something like:
97
98    sub JoinedChannel {
99        my $self = shift;
100        my ($event, $channel) = @_;
101        # ...
102        return $self->SUPER::JoinedChannel($event, $channel); # call inherited method
103    }
104
105 Many functions have to return a special value, typically 0 if the
106 event was handled, and 1 if it was not.
107
108 For these functions, what actually happens is that for the relevant
109 event, the bot has a list of event handlers it should call. For
110 example, if someone says 'bot: hi' then the bot wants to call the
111 Told() handler and the Baffled() handler. It first calls the Told()
112 handler of every module. It then looks to see if any of the handlers
113 returned 0. If so, it stops. Note, though, that every Told() handler
114 got called! If none of the handlers returned 0, then it looks to see
115 what the highest return value was. If it was greater than 1, then it
116 increments the 'level' field of the $event hash (see below) and calls
117 all the Told() handlers that returned 1 or more again. This means that
118 if your module decides whether or not to respond by looking at a
119 random number, it is prone to being confused by another module!
120
121    YOU SHOULD NOT USE RANDOM NUMBERS TO DECIDE WHETHER OR NOT TO
122    RESPOND TO A MESSAGE!
123
124 Once all the relevant Told() handlers have been called again, the 
125 bot once again examines all the return results, and stops if any 
126 returned 0. If none did and if the current value of the level field 
127 is less than the highest number returned from any of the modules, 
128 then it repeats the whole process again. Once the level field is 
129 equal to the highest number returned, then, if no module has ever
130 returned 0 in that whole loopy time, it moves on to the next
131 handler in the list (in this case Baffled()), and does the
132 _entire_ process again.
133
134 You may be asking yourself "Why oh why!". It is to allow you to
135 implement priority based responses. If your module returns '5' to
136 the Told() function, and only handles the event (i.e., only
137 returns 0) once the level field is 5, then it will only handle the
138 event if no other module has wanted to handle the event in any of
139 the prior levels.
140
141 It also allows inter-module communication, although since that is
142 dodgy, the details are left as an exercise to the reader.
143
144 Important: if you use this, make sure that you only reply to the 
145 user once, based on the $event->{'level'} field. e.g., if you
146 replied when level was zero, then don't reply _again_ when it is
147 set to 1. This won't be a problem if your module only returns 1
148 (the default) or 0 (indicating success).
149
150
151 *** Help($event)
152
153  Every module that does anything visible should provide a 'Help'
154  function. This is called by the General module's 'help' command
155  implementation.
156
157  This function should return a hashref, with each key representing a
158  topic (probably a command) and each value the relevant help string.
159  The '' topic is special and should contain the help string for the
160  module itself.
161
162
163 *** Initialise()
164
165  Called when the module is loaded.
166
167  No special return values.
168
169
170 *** Schedule($event)
171
172  Schedule - Called after bot is set up, to set up any scheduled
173  tasks. See 'schedule' in the API documentation below for information
174  on how to do this.
175
176  No special return values. Always call inherited function!
177
178
179 *** JoinedIRC($event)
180
181  Called before joining any channels (but after module is setup). This
182  does not get called for dynamically installed modules.
183
184  No special return values. Always call inherited function!
185
186
187 *** JoinedChannel($event, $channel)
188
189  Called after joining a channel for the first time, for example if
190  the bot has been /invited.
191
192  No special return values. Always call inherited the function, as this
193  is where the autojoin function is implemented.
194
195
196 *** PartedChannel($event, $channel)
197
198  Called after the bot has left a channel, for example if the bot has 
199  been /kicked.
200
201  No special return values. Always call inherited the function, as this
202  is where the autopart function is implemented.
203
204
205 *** InChannel($event)
206
207  Called to determine if the module is 'in' the channel or not.
208  Generally you will not need to override this.
209
210  Return 0 if the module is not enabled in the channel in which the
211  event occured, non zero otherwise.
212
213
214 *** IsBanned($event)
215
216  Same as InChannel(), but for determining if the user is banned or
217  not.
218
219  Return 1 if the user that caused the event is banned from this
220  module, non zero otherwise.
221
222
223 *** Log($event)
224
225  Called once for most events, regardless of the result of the 
226  other handlers. This is the event to use if you wish to log
227  everything that happens on IRC (duh).
228
229  No return value.
230
231
232 *** Baffled($event, $message)
233
234  Called for messages prefixed by the bot's nick which we don't
235  understand (i.e., that Told couldn't deal with).
236
237  Return 1 if you can't do anything (this is all the default
238  implementation of Baffled() does).
239
240
241 *** Told($event, $message)
242
243  Called for messages heard that are prefixed by the bot's nick. See
244  also Baffled.
245
246  Return 1 if you can't do anything (this is all the default
247  implementation of Told() does).
248
249
250 *** Heard($event, $message)
251
252  Called for all messages not aimed directly at the bot, or those
253  aimed at the bot but with no content (e.g., "bot!!!").
254
255  Return 1 if you can't do anything (this is all the default
256  implementation of Heard() does).
257  
258
259 *** Noticed($event, $message)
260
261  Called for all 'notice' messages, whether aimed directly at the bot
262  or not. Don't use this message to trigger responses! Doing so is a
263  violation of the IRC protocol.
264
265  To quote RFC 1459: 
266
267  # [...] automatic replies must never be sent in response to a NOTICE
268  # message. [...] The object of this rule is to avoid loops between a
269  # client automatically sending something in response to something it
270  # received. This is typically used by automatons (clients with either
271  # an AI or other interactive program controlling their actions) which
272  # are always seen to be replying lest they end up in a loop with
273  # another automaton.
274
275  Return 1 if you can't do anything (this is all the default
276  implementation of Noticed() does).
277  
278
279 *** Felt($event, $message)
280
281  Called for all emotes containing bot's nick.
282
283  Return 1 if you can't do anything (this is all the default
284  implementation of Felt() does).
285
286
287 *** Saw($event, $message)
288
289  Called for all emotes except those directly at the bot.
290
291  Return 1 if you can't do anything (this is all the default
292  implementation does).
293
294
295 *** Invited($event, $channel)
296
297  Called when bot is invited into another channel.
298
299  Return 1 if you can't do anything (this is all the default
300  implementation does).
301
302
303 *** Kicked($event, $channel)
304
305  Called when bot is kicked out of a channel.
306
307  Return 1 if you can't do anything (this is all the default
308  implementation does).
309
310
311 *** ModeChange($event, $what, $change, $who)
312
313  Called when either the channel or a person has a mode flag changed.
314
315  Return 1 if you can't do anything (this is all the default
316  implementation does).
317
318
319 *** GotOpped($event, $channel, $who)
320
321  Called when the bot is opped. (Not currently implemented.)
322
323  Return 1 if you can't do anything (this is all the default
324  implementation does).
325
326
327 *** GotDeopped($event, $channel, $who)
328
329  Called when the bot is deopped. (Not currently implemented.)
330
331  Return 1 if you can't do anything (this is all the default
332  implementation does).
333
334
335 *** Authed($event, $who)
336
337  Called when someone authenticates with us. Note that you cannot
338  do any channel-specific operations here since authentication is
339  done directly and without any channels involved. (Of course,
340  you can always do channel-wide stuff based on a channel list...)
341
342  Return 1 if you can't do anything (this is all the default
343  implementation does).
344
345
346 *** SpottedNickChange($event, $from, $to)
347
348  Called when someone changes their nick. You cannot use directSay
349  here, since $event has the details of the old nick. And 'say' is
350  useless since the channel is the old userhost string... This may be
351  changed in a future implementation.
352
353  Return 1 if you can't do anything (this is all the default
354  implementation does).
355
356
357 *** SpottedTopicChange($event, $channel, $newtopic)
358
359  Called when the topic in a channel is changed.
360
361  Return 1 if you can't do anything (this is all the default
362  implementation does).
363
364
365 *** SpottedJoin($event, $channel, $who)
366
367  Called when someone joins a channel (including the bot).
368
369  Return 1 if you can't do anything (this is all the default
370  implementation does).
371
372
373 *** SpottedPart($event, $channel, $who)
374
375  Called when someone leaves a channel (including the bot).
376
377  Return 1 if you can't do anything (this is all the default
378  implementation does).
379
380
381 *** SpottedKick($event, $channel, $who)
382
383  Called when someone leaves a channel, um, forcibly (including the
384  bot).
385
386  Return 1 if you can't do anything (this is all the default
387  implementation does).
388
389
390 *** SpottedQuit($event, $who, $why)
391
392  Called when someone leaves a server. You can't use say or directSay
393  as no channel involved and the user has quit, anyway (obviously).
394  This may change in future implementations (don't ask me how, please...).
395
396  This does not get called for the bot itself. There is no way to
397  reliably detect this (the core code itself has difficulty detecting
398  this case, and sometimes only detects it when it is not really in a
399  position to call into the modules). You may wish to use the 'unload'
400  handler or 'DESTROY' function instead.
401
402  Return 1 if you can't do anything (this is all the default
403  implementation does).
404
405
406 *** SpottedOpping($event, $channel, $who)
407
408  Called when someone is opped. (Not currently implemented.)
409
410  Return 1 if you can't do anything (this is all the default
411  implementation does).
412
413
414 *** SpottedDeopping($event, $channel, $who)
415
416  Called when someone is... deopped, maybe? (Not currently implemented.)
417
418  Return 1 if you can't do anything (this is all the default
419  implementation does).
420
421
422 *** CTCPPing($event, $who, $what)
423
424  Called when the bot receives a CTCP ping.
425
426  Return 1 if you can't do anything (this is all the default
427  implementation does).
428
429
430 *** CTCPVerson($event, $who, $what)
431
432  Called when the bot receives a CTCP verson.
433
434  Return 1 if you can't do anything (this is all the default
435  implementation does).
436
437
438 *** CTCPSource($event, $who, $what)
439
440  Called when the bot receives a CTCP source.
441
442  Return 1 if you can't do anything (this is all the default
443  implementation does).
444
445
446 *** Scheduled($event, @data)
447
448  Called when a scheduled timer triggers. (See 'schedule' in the next
449  section to see how to schedule stuff.) By default, if the first
450  element of the @data array is a coderef, then the coderef is called
451  with ($event,@data) as the arguments. Otherwise, 'debug' is called
452  (see below).
453
454  No special return values. Always call inherited function if you
455  cannot handle the scheduled event yourself.
456
457
458 *** GotURI($event, $uri, $contents, @data)
459
460  Called when a requested URI has been downloaded. $contents contains
461  the actual contents of the file. See getURI().
462
463  No special return values.
464
465
466 *** ChildCompleted($event, $type, $output, @data)
467
468  Called when a spawned child has completed. $output contains
469  the output of the process. $type contains the child type as
470  given to the spawnChild() API function (which see).
471
472  No special return values. Always call the inherited function if
473  you cannot handle the given '$type'!
474
475
476 *** DataAvailable($event, $handle, $data, $closed)
477
478  Called when $handle has data available. See registerDataHandle(). 
479  $data is the string that was read from the handle. Don't perform
480  blocking read I/O on $handle, since all the data that was available
481  has been read. (The handle is only returned because it is expected
482  you will use that as a key to work out who is talking to you.)
483  The $closed argument will be set to true if the handle is now closed.
484
485  No special return values. Make sure to call the inherited function if
486  you did not expect to see data on the specified $handle.
487
488
489 *** RegisterConfig()
490
491  Called when initialised, should call registerVariables(), which see
492  below.
493
494  No special return values. Always call inherited function!
495
496
497 *** Set($event, $variable, $value)
498
499  Called to set a variable to a particular value.
500
501  Should return one of the following:
502   -1 - silent success (caller should not report back to user)
503    0 - success
504    1 - can't set variable because it is of type ref($module->{$variable})
505    2 - variable not found or not writable (if $module->{$variable})
506    3 - variable is list and wrong format was used
507    4 - variable is hash and wrong format was used
508    9 - unknown error
509  
510  Note that error codes 1-4 are probably too specific to the default
511  'Set' function to be of any use. Reporting your own error messages
512  is fine.
513
514  Always call inherited function if you cannot set the variable yourself!
515
516
517 *** Get($event, $variable)
518
519  Called to get a particular variable.
520
521  Should return the value of the variable. Default returns the value
522  of $self->{$variable}.
523
524  Always call inherited function if you cannot get the variable yourself!
525
526
527 *** Unload()
528
529  Called when the module is unloaded. However, this is not always
530  reliably called when the module is unloaded immediately prior to the
531  bot shutting down or branching to a different process.
532
533  In general, relying on this function is poor design. It should only
534  really be used for things like untie-ing from hashes or disconnecting
535  from databases, where the code executing is not critical, merely good
536  manners or helpful.
537
538  No special return values. You are encouraged not to use this method. 
539  It is documented for completeness only.
540
541  Default implementation does nothing.
542
543
544
545 The $event variable is a hash with the following keys:
546
547     'bot' => the IRC bot object - DO NOT USE THIS!!! [1]
548     'channel' => the channel the event occured in, or '' if n/a [2]
549     'from' => the nick of the person who created the event, if any
550     'target' => the target of the 'say' function (channel || from)
551     'user' => the userhost of the event
552     'data' => the main data of the event
553     'fulldata' => the data of the event before it got mangled [3]
554     'to' => the target of the event
555     'subtype' => the IRC module's idea of what the event was [1]
556     'maintype' => the name of the first handler called (eg. 'Told')
557     'level' => the number of times the handler has been called in a row
558     'userName' => the name of the user as they authenticated
559     'userFlags' => used internally for the implementation of isAdmin() [1]
560     'nick' => the nick of the bot
561     'time' => the value of time() when the event was constructed [4]
562
563 It is passed to most functions, as the first parameter. Modify at your 
564 own risk! ;-) If you do write to this hash at all, ensure that you make 
565 a 'local' copy first. See the 'Parrot' module for an example of safely 
566 modifying the $event hash. Note that some of these fields may be 
567 inaccurate at times, due to peculiarities of the IRC protocol.
568
569 [1]: These fields are dependent on the underlying implementation, so
570 if you use them then your modules will not be compatible with any other
571 implementations that use the same API. The 'bot' field in particular is
572 a blessed reference to a Net::IRC::Connection object in this 
573 implementation, and is passed around so that the API functions know
574 what to operate on. However, in a POE implementation it could be 
575 something totally different, maybe even undef. There are some other
576 fields in the $event hash that start with an underscore (in particular
577 there is '_event'). Do not even _think_ about using those. Using them
578 is akin to hard-coding the ionode of the 'ls' program into your source
579 so that you can read directories by branching to a disk address.
580
581 [2]: The 'channel' field is ALWAYS lowercase. You should always lowercase
582 any channel names you get from users before using them in comparisons or
583 hash lookups.
584
585 [3]: This is the same as the 'data' slot except for Told and Baffled
586 events where it also contains the prefix that was stripped.
587
588 [4]: Use this instead of calling time() so as to avoid time drift when
589 comparing times at various points.
590
591
592 Module API
593 ----------
594
595 This section contains the names and descriptions of the functions
596 that your module can call. While you can override these, it is not
597 recommended.
598
599 *** debug(@messages)
600
601  Outputs each item in @messages to the console (or the log file if
602  the bot has lost its controlling tty).
603
604  Example:
605     $self->debug('about to fetch listing from FTP...');
606
607
608 *** saveConfig()
609
610  Saves the state of the module's registered variables to the
611  configuration file. This should be called when the variables have
612  changed.
613
614  Example:
615     $self->saveConfig(); # save our state!
616
617
618 *** registerVariables( [ $name, $persistent, $settable, $value ] )
619
620  Registers variables (duh). It actually takes a list of arrayrefs.
621  The first item in each arrayref is the name to use (the name of the
622  variable in the blessed hashref that is the module's object, i.e.
623  $self). The second controls if the variable is saved when
624  saveConfig() is called. If it is set to 1 then the variable is
625  saved, if 0 then it is not, and if undef then the current setting is
626  not changed. Similarly, the third item controls whether or not the
627  variable can be set using the 'vars' command (in the Admin
628  module). 1 = yes, 0 = no, undef = leave unchanged. The fourth value,
629  if defined, is used to set the variable. See the Initialise
630  function's entry for more details.
631
632  Example:
633     $self->registerVariables(
634         [ 'ftpDelay', 1, 1, 60 ],
635         [ 'ftpSite', 1, 1, 'ftp.mozilla.org' ],
636     );
637
638  Only simple scalars, references to arrays of scalars, and references
639  to hashes of scalars, can be stored in registered variables.
640
641
642 *** schedule($event, $time, $times, @data)
643
644  Schedules one or more events. $event is the usual event hash. $time
645  is the number of seconds to wait. It can be a scalarref to a
646  variable that contains this number, too, in which case it is
647  dereferenced. This comes in useful for making the frequency of
648  repeating events customisable. $times is the number of times to
649  perform the event, which can also be -1 meaning 'forever'. @data
650  (the remainder of the parameters) will be passed, untouched, to the
651  event handler, Scheduled. See the previous section.
652
653  Example:
654     $self->schedule($event, \$self->{'ftpDelay'}, -1, 'ftp', \$ftpsite); 
655
656
657 *** getURI($event, $uri, @data)
658
659  Gets a URI in the background then calls GotURI (which see, above).
660
661  Example:
662     $self->getURI($event, $ftpsite, 'ftp'); 
663
664
665 *** spawnChild($event, $command, $arguments, $type, $data)
666
667  Spawns a child in the background then calls ChildCompleted (which see, 
668  above). $arguments and $data are array refs! $command is either a 
669  command name (e.g., 'wget', 'ls') or a CODEREF. If it is a CODEREF,
670  then you will be wanting to make sure that the first argument is
671  the object reference, unless we are talking inlined code or something...
672
673  Example:
674     $self->spawnChild($event, '/usr/games/fortune', ['-s', '-o'], 
675                       'fortune', [@data]); 
676
677
678 *** registerDataHandle($event, $handle)
679
680  Adds $handle to the list of file handles and sockets to watch. When
681  data is available on that socket, DataAvailable() will be called.
682
683
684 *** getModule($name)
685
686  Returns a reference to the module with the given name. In general you
687  should not need to use this, but if you write a management module, for
688  instance, then this could be useful. See God.bm for an example of this.
689
690             IT IS VITAL THAT YOU DO NOT KEEP THE REFERENCE 
691                     THAT THIS FUNCTION RETURNS!!!
692
693  If you did so, the module would not get garbage collected if it ever
694  got unloaded or some such.
695
696  Example:
697     my $module = $self->getModule('Admin');
698     push(@{$module->{'files'}}, 'BotModules/SupportFile.pm');
699
700
701 *** getModules()
702
703  Returns the list of module names that are loaded, in alphabetical
704  order, which you can then use with getModule().
705
706  Example:
707     my @modulenames = $self->getModules();
708     local $" = ', ';
709     $self->ctcpReply($event, 'VERSION', "mozbot $VERSION (@modulenames)");
710
711
712 *** getMessageQueue()
713
714  Returns a reference to the message queue. Manipulating this is
715  probably not a good idea. In particular, don't add anything to this
716  array, use the say(), directSay(), channelSay(), announce(),
717  tellAdmin(), etc, methods defined below.
718
719  Each item in this array is an array ref, consisting of three
720  subitems. The first subitem is a scalar with the name of the channel
721  or nick targetted, the second is the message to send, and the third
722  is a scalar equal to one of: 'msg', 'me', 'notice', 'ctcpSend',
723  'ctcpReply'. The second subitem is a scalar, except in the case of
724  'ctcpSend' messages, in which case it's an array ref consisting of
725  first the type of the CTCP message, and then the data.
726
727  Note: Don't use 'delete' to remove items from this array, since that
728  leaves undefs in the array, which will later cause a crash.
729
730  Example:
731     my $queue = $self->getMessageQueue();
732     foreach my $message (@$queue) {
733         ++$count if $message->[0] eq $event->{'from'};
734     }
735
736
737 *** getHelpLine()
738
739  Returns the bot's help line.
740
741  Example:
742     $self->say($event, $self->getHelpLine());
743
744
745 *** getLogFilename($name)
746
747  Returns a filename (with path) appropriate to use for logging. $name
748  should be the filename wanted, without a path.
749
750  Example:
751     my $logName = $self->getLogFilename("$channel.log");
752     if (open(LOG, ">>$logName")) {
753         print LOG $data;
754         close LOG;
755     } else {
756         # XXX error handling
757     }
758
759
760 *** unescapeXML($xml)
761
762  Performs the following conversions on the argument and returns the result: 
763     ' => '
764     " => "
765     &lt;   => <
766     &gt;   => >
767     &amp;  => &
768
769  Example:
770     my $text = $self->unescapeXML($output);
771
772
773 *** tellAdmin($event, $data);
774
775  Tries to tell an administrator $data. As currently implemented, only
776  one administrator will get the message, and there is no guarentee
777  that they will read it or even that the admin in question is
778  actually on IRC at the time.
779
780  Example:
781     $self->tellAdmin($event, 'Someone just tried to crack me...');
782
783
784 *** say($event, $data)
785  
786  Says $data in whatever channel the event was spotted in (this can be
787  /msg if that is how the event occured).  
788
789  Example:
790     $self->say($event, 'Yo, dude.');
791
792
793 *** announce($event, $data)
794  
795  Says $data in all the channels the module is in.
796
797  Example:
798     $self->announce($event, 'Bugzilla is back up.');
799
800
801 *** directSay($event, $data)
802
803  Sends a message directly to the cause of the last event (i.e., like
804  /msg). It is recommended to use 'say' normally, so that users have a
805  choice of whether or not to get the answer in the channel (they
806  would say their command there) or not (they would /msg their
807  command).
808
809  Example:
810     $self->directSay($event, 'Actually, that\'s not right.');
811
812
813 *** channelSay($event, $data)
814
815  Sends a message to the channel in which the message was given.
816  If the original command was sent in a /msg, then this will result
817  in precisely nothing. Useful in conjunction with directSay() to 
818  make it clear that a reply was sent privately.
819
820  Example:
821     $self->directSay($event, $veryLongReply);
822     $self->channelSay($event, "$event->{'from'}: data /msg'ed");
823
824
825 *** emote($event, $what)
826 *** directEmote($event, $what)
827
828  Same as say() and directSay(), but do the equivalent of /me instead.
829
830  Examples:
831     $self->emote($event, "slaps $event->{'from'} with a big smelly trout.");
832     $self->directEmote($event, "waves.");
833
834
835 *** sayOrEmote($event, $what)
836 *** directSayOrEmote($event, $what)
837
838  Call say (directSay) or emote (directEmote) based on the contents of $what.
839  If $what starts with '/me' then the relevant emote variation is called,
840  otherwise the say variations are used. The leading '/me' is trimmed before
841  being passed on.
842
843  Examples:
844     $self->sayOrEmote($event, $greeting);
845     $self->directSayOrEmote($event, $privateMessage);
846
847
848 *** ctcpSend($event, $type, $data)
849
850  Same as say() but for sending CTCP messages.
851
852  Examples:
853     $self->ctcpSend($event, 'PING', $event->{'time'});
854
855
856 *** ctcpReply($event, $type, $data)
857
858  Same as ctcpSend() but for sending CTCP replies.
859
860  Examples:
861     $self->ctcpReply($event, 'VERSION', "Version $major.$minor");
862
863
864 *** notice($event, $data)
865  
866  Sends a notice containing $data to whatever channel the event was
867  spotted in (this can be /msg if that is how the event occured).
868
869  Example:
870     foreach (@{$self->{'channels'}}) {
871         local $event->{'target'} = $_;
872         $self->notice($event, 'This is a test of the emergency announcement system.');
873     }
874
875
876 *** isAdmin($event)
877
878  Returns true if the cause of the event was an authenticated administrator.
879
880  Example:
881     if ($self->isAdmin($event)) { ... }
882
883
884 *** setAway($event, $message)
885
886  Set the bot's 'away' flag. A blank message will mark the bot as
887  back. Note: If you need this you are doing something wrong!!!
888  Remember that you should not be doing any lengthy processes since if
889  you are away for any length of time, the bot will be disconnected!
890
891  Also note that in 2.0 this is not throttled, so DO NOT call this
892  repeatedly, or put yourself in any position where you allow IRC
893  users to cause your module to call this. Otherwise, you open
894  yourself to denial of service attacks.
895
896  Finally, note that calling 'do', 'emote', 'say', and all the 
897  related functions will also reset the 'away' flag.
898
899  Example:
900     $self->setAway($event, 'brb...');
901
902
903 *** setNick($event, $nick)
904
905  Set the bot's nick. This handles all the changing of the internal
906  state variables and saving the configuration and everything.
907  It will also add the nick to the list of nicks to try when
908  the bot finds its nick is already in use.
909
910  Note that in 2.0 this is not throttled, so DO NOT call this
911  repeatedly, or put yourself in any position where you allow IRC
912  users to cause your module to call this. Otherwise, you open
913  yourself to denial of service attacks.
914
915  Example:
916     $self->setNick($event, 'zippy');
917
918
919 *** mode($event, $channel, $mode, $argument)
920
921  Changes a mode of channel $channel.
922
923  Example:
924     $self->mode($event, $event->{'channel'}, '+o', 'Hixie');
925
926
927 *** invite($event, $who, $channel)
928
929  Invite $who to channel $channel. This can be used for intrabot
930  control, or to get people into a +i channel, for instance.
931
932  Example:
933     $self->invite($event, 'Hixie', '#privateChannel');
934
935
936 *** prettyPrint($preferredLineLength, $prefix, $indent, $divider, @input)
937
938  Takes @input, and resorts it so that the lines are of roughly the same
939  length, aiming optimally at $preferredLineLength, prefixing each line
940  with $indent, placing $divider between each item in @input if they 
941  appear on the same line, and sticking $prefix at the start of it all on
942  the first line. The $prefix may be undef.
943
944  Returns the result of all that.
945
946  This is what the 'help' command uses to pretty print its output.
947
948  This is basically the same as wordWrap() but it can change the order
949  of the input.
950
951  Example:
952     my @result = $self->prettyPrint($linelength, undef, 'Info: ', ' -- ', @infoItems);
953
954
955 *** wordWrap($preferredLineLength, $prefix, $indent, $divider, @input)
956
957  Takes @input, and places each item sequentially on lines, aiming optimally
958  at $preferredLineLength, prefixing each line with $indent, placing $divider
959  between each item in @input if they appear on the same line, and sticking 
960  $prefix at the start of it all on the first line, without ever cutting
961  items across lines. The $prefix may be undef.
962
963  Returns the result of all that.
964
965  This is basically the same as prettyPrint() but it doesn't change the
966  order of the input.
967
968  Example:
969     my @result = $self->wordWrap($linelength, undef, 'Info: ', ' ', split(/\s+/os, @lines);
970
971
972 *** days($time)
973
974  Returns a string describing the length of time between $time and now.
975
976  Example:
977     $self->debug('uptime: '.$self->days($^T));
978
979
980 *** sanitizeRegexp($regexp)
981
982  Checks to see if $regexp is a valid regular expression. If it is, returns
983  the argument unchanged. Otherwise, returns quotemeta($regexp), which should
984  be safe to use in regular expressions as a plain text search string.
985
986  Do not add prefixes or suffixes to the pattern after sanitizing it.
987  
988  Example:
989      $pattern = $self->sanitizeRegexp($pattern);
990      $data =~ /$pattern//gsi;
991
992
993 -- end --