2001-04-23 11:07:17 +04:00
|
|
|
MODULE API DOCUMENTATION
|
|
|
|
========================
|
|
|
|
|
Makes mozbot only mark joins as joined on a successful attempt. b=112049, r=kerz.
Implements getHelpLine and getModules API functions and updates documentation to match. b=130532, r=imajes.
Adds a notice() method to the mozbot API. Updates the documentation to reflect this. (Also updates the version and corrects a typo in the docs.) b=72960, r=timeless.
Fixes the problem whereby if a module doesn't load, it's not removed from the @modulenames list, which causes problems for modules that walk the @modulenames list to get each module in turn. b=133148, r=kerz.
The Log event for the Told event doesn't have the prefix text that made the event a Told event in the first place. This adds a field 'fulldata' to the event hash which will let loggers log the whole thing. Also updates documentation. b=133509, r=kerz.
Log events were not generated for events generated by the bot. This removes redundant checks to prevent that from happening (redundant since the server never sent us the messages in the first place) and then adds code to synthesise the relevant Log events. Updates the documentation to match. b=16226, r=kerz.
The Initialise handler was needlessly within the scope of an undef'd $/. This scopes the cause of this problem. b=131483, p=Robin Berjon, r=kerz, a=hixie.
Makes ctcpSend() send messages to the target, not the originator. This makes it work like say(). b=133140, r=caillion.
Adds a way to make the auth command not give confirmation feedback (quiet auth). b=134342, r=caillon.
2002-04-01 07:46:06 +04:00
|
|
|
This file documents the mozbot 2.4 bot module API.
|
2001-04-23 11:07:17 +04:00
|
|
|
Revisions are welcome.
|
|
|
|
|
|
|
|
Sample module
|
|
|
|
-------------
|
|
|
|
|
|
|
|
Here is the HelloWorld module:
|
|
|
|
|
|
|
|
################################
|
|
|
|
# Hello World Module #
|
|
|
|
################################
|
|
|
|
|
|
|
|
package BotModules::HelloWorld;
|
|
|
|
use vars qw(@ISA);
|
|
|
|
@ISA = qw(BotModules);
|
|
|
|
1;
|
|
|
|
|
|
|
|
sub Help {
|
|
|
|
my $self = shift;
|
|
|
|
my ($event) = @_;
|
|
|
|
return {
|
|
|
|
'' => 'This is the demo module that says Hello World.',
|
|
|
|
'hi' => 'Requests that the bot emit a hello world string.',
|
|
|
|
};
|
|
|
|
}
|
|
|
|
|
|
|
|
sub Told {
|
|
|
|
my $self = shift;
|
|
|
|
my ($event, $message) = @_;
|
|
|
|
if ($message =~ /^\s*hi\s*$/osi) {
|
|
|
|
$self->say($event, 'Hello World!');
|
|
|
|
} else {
|
|
|
|
return $self->SUPER::Told(@_);
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
################################
|
|
|
|
|
|
|
|
|
|
|
|
Creating a module
|
|
|
|
-----------------
|
|
|
|
|
|
|
|
Modules are perl objects with names that start with 'BotModules::'
|
|
|
|
and that are stored in files with the '.bm' extension in the
|
|
|
|
'BotModules' directory. The first non-comment line of each module
|
|
|
|
should be the 'package' line, which in the HelloWorld module reads:
|
|
|
|
|
|
|
|
package BotModules::HelloWorld;
|
|
|
|
|
|
|
|
For a module to work correctly, it should inherit from the
|
|
|
|
'BotModules' module (which is implemented internally in the main bot
|
|
|
|
executable). This is done by including the following two lines
|
|
|
|
immediately after the 'package' line:
|
|
|
|
|
|
|
|
use vars qw(@ISA);
|
|
|
|
@ISA = qw(BotModules);
|
|
|
|
|
|
|
|
Since modules are dynamically loaded and unloaded, they should avoid
|
|
|
|
using package globals. All variables should be stored in the '$self'
|
|
|
|
blessed hashref. For more details, see the documentation of the
|
|
|
|
'Initialise' function (below). Another result of the dynamic nature
|
|
|
|
of modules is that they should not use BEGIN {} or END {} blocks, nor
|
|
|
|
should they execute any code during their evaluation. Thus,
|
|
|
|
immediately after the @ISA... line, the module should return success.
|
|
|
|
This can be done easily:
|
|
|
|
|
|
|
|
1;
|
|
|
|
|
|
|
|
Following this, you are free to implement all the functions you need
|
|
|
|
for your module. Certain functions have certain calling semantics,
|
|
|
|
these are described below.
|
|
|
|
|
|
|
|
|
|
|
|
Module Functions
|
|
|
|
----------------
|
|
|
|
|
|
|
|
This section contains the names and descriptions of the functions in
|
|
|
|
your module that will be called automatically depending on what is
|
|
|
|
happening on IRC.
|
|
|
|
|
|
|
|
All your functions should start by shifting the $self variable from the
|
|
|
|
argument list:
|
|
|
|
|
|
|
|
my $self = shift;
|
|
|
|
|
|
|
|
After this, it is common to get the other variables too:
|
|
|
|
|
|
|
|
my ($event, @anythingElse) = @_;
|
|
|
|
|
|
|
|
...where the bit in the brackets is given in the brackets of the
|
|
|
|
definitions of the functions as shown below. For example, for
|
|
|
|
JoinedChannel it would be ($event, $channel), so a function to override
|
|
|
|
the default JoinedChannel action would be something like:
|
|
|
|
|
|
|
|
sub JoinedChannel {
|
|
|
|
my $self = shift;
|
|
|
|
my ($event, $channel) = @_;
|
|
|
|
# ...
|
|
|
|
return $self->SUPER::JoinedChannel($event, $channel); # call inherited method
|
|
|
|
}
|
|
|
|
|
|
|
|
Many functions have to return a special value, typically 0 if the event
|
|
|
|
was handled, and 1 if it was not.
|
|
|
|
|
|
|
|
What actually happens is that for every event that occurs, the bot
|
|
|
|
has a list of event handlers it should call. For example, if
|
|
|
|
someone says 'bot: hi' then the bot wants to call the Told()
|
|
|
|
handler and the Baffled() handler. It first calls the Told()
|
|
|
|
handler of every module. It then looks to see if any of the
|
|
|
|
handlers returned 0. If so, it stops. Note, though, that every
|
|
|
|
Told() handler got called! If none of the handlers returned 0,
|
|
|
|
then it looks to see what the highest return value was. If it was
|
|
|
|
greater than 1, then it increments the 'level' field of the $event
|
|
|
|
hash (see below) and calls all the Told() handlers that returned 1
|
|
|
|
or more again. This means that if your module decides whether or
|
|
|
|
not to respond by looking at a random number, it is prone to being
|
|
|
|
confused by another module!
|
|
|
|
|
|
|
|
YOU SHOULD NOT USE RANDOM NUMBERS TO DECIDE WHETHER OR NOT TO
|
|
|
|
RESPOND TO A MESSAGE!
|
|
|
|
|
|
|
|
Once all the relevant Told() handlers have been called again, the
|
|
|
|
bot once again examines all the return results, and stops if any
|
|
|
|
returned 0. If none did and if the current value of the level field
|
|
|
|
is less than the highest number returned from any of the modules,
|
|
|
|
then it repeats the whole process again. Once the level field is
|
|
|
|
equal to the highest number returned, then, if no module has ever
|
|
|
|
returned 0 in that whole loopy time, it moves on to the next
|
|
|
|
handler in the list (in this case Baffled()), and does the
|
|
|
|
_entire_ process again.
|
|
|
|
|
|
|
|
You may be asking yourself "Why oh why!". It is to allow you to
|
|
|
|
implement priority based responses. If your module returns '5' to
|
|
|
|
the Told() function, and only handles the event (i.e., only
|
|
|
|
returns 0) once the level field is 5, then it will only handle the
|
|
|
|
event if no other module has wanted to handle the event in any of
|
|
|
|
the prior levels.
|
|
|
|
|
|
|
|
It also allows inter-module communication, although since that is
|
|
|
|
dodgy, the details are left as an exercise to the reader.
|
|
|
|
|
|
|
|
Important: if you use this, make sure that you only reply to the
|
|
|
|
user once, based on the $event->{'level'} field. e.g., if you
|
|
|
|
replied when level was zero, then don't reply _again_ when it is
|
|
|
|
set to 1. This won't be a problem if your module only returns 1
|
|
|
|
(the default) or 0 (indicating success).
|
|
|
|
|
|
|
|
|
|
|
|
*** Help($event)
|
|
|
|
|
|
|
|
Every module that does anything visible should provide a 'Help'
|
|
|
|
function. This is called by the General module's 'help' command
|
|
|
|
implementation.
|
|
|
|
|
|
|
|
This function should return a hashref, with each key representing a
|
|
|
|
topic (probably a command) and each value the relevant help string.
|
|
|
|
The '' topic is special and should contain the help string for the
|
|
|
|
module itself.
|
|
|
|
|
|
|
|
|
|
|
|
*** Initialise()
|
|
|
|
|
|
|
|
Called when the module is loaded.
|
|
|
|
|
|
|
|
No special return values.
|
|
|
|
|
|
|
|
|
|
|
|
*** Schedule($event)
|
|
|
|
|
|
|
|
Schedule - Called after bot is set up, to set up any scheduled
|
|
|
|
tasks. See 'schedule' in the API documentation below for information
|
|
|
|
on how to do this.
|
|
|
|
|
|
|
|
No special return values. Always call inherited function!
|
|
|
|
|
|
|
|
|
|
|
|
*** JoinedIRC($event)
|
|
|
|
|
|
|
|
Called before joining any channels (but after module is setup). This
|
|
|
|
does not get called for dynamically installed modules.
|
|
|
|
|
|
|
|
No special return values. Always call inherited function!
|
|
|
|
|
|
|
|
|
|
|
|
*** JoinedChannel($event, $channel)
|
|
|
|
|
|
|
|
Called after joining a channel for the first time, for example if
|
|
|
|
the bot has been /invited.
|
|
|
|
|
|
|
|
No special return values. Always call inherited the function, as this
|
|
|
|
is where the autojoin function is implemented.
|
|
|
|
|
|
|
|
|
|
|
|
*** PartedChannel($event, $channel)
|
|
|
|
|
|
|
|
Called after the bot has left a channel, for example if the bot has
|
2001-04-29 12:35:29 +04:00
|
|
|
been /kicked.
|
2001-04-23 11:07:17 +04:00
|
|
|
|
|
|
|
No special return values. Always call inherited the function, as this
|
|
|
|
is where the autopart function is implemented.
|
|
|
|
|
|
|
|
|
|
|
|
*** InChannel($event)
|
|
|
|
|
|
|
|
Called to determine if the module is 'in' the channel or not.
|
|
|
|
Generally you will not need to override this.
|
|
|
|
|
|
|
|
Return 0 if the module is not enabled in the channel in which the
|
|
|
|
event occured, non zero otherwise.
|
|
|
|
|
|
|
|
|
|
|
|
*** IsBanned($event)
|
|
|
|
|
|
|
|
Same as InChannel(), but for determining if the user is banned or
|
|
|
|
not.
|
|
|
|
|
|
|
|
Return 1 if the user that caused the event is banned from this
|
|
|
|
module, non zero otherwise.
|
|
|
|
|
|
|
|
|
|
|
|
*** Log($event)
|
|
|
|
|
|
|
|
Called once for most events, regardless of the result of the
|
|
|
|
other handlers. This is the event to use if you wish to log
|
|
|
|
everything that happens on IRC (duh).
|
|
|
|
|
|
|
|
No return value.
|
|
|
|
|
|
|
|
|
|
|
|
*** Baffled($event, $message)
|
|
|
|
|
|
|
|
Called for messages prefixed by the bot's nick which we don't
|
|
|
|
understand (i.e., that Told couldn't deal with).
|
|
|
|
|
|
|
|
Return 1 if you can't do anything (this is all the default
|
|
|
|
implementation of Baffled() does).
|
|
|
|
|
|
|
|
|
|
|
|
*** Told($event, $message)
|
|
|
|
|
|
|
|
Called for messages heard that are prefixed by the bot's nick. See
|
|
|
|
also Baffled.
|
|
|
|
|
|
|
|
Return 1 if you can't do anything (this is all the default
|
|
|
|
implementation of Told() does).
|
|
|
|
|
|
|
|
|
|
|
|
*** Heard($event, $message)
|
|
|
|
|
|
|
|
Called for all messages not aimed directly at the bot, or those
|
|
|
|
aimed at the bot but with no content (e.g., "bot!!!").
|
|
|
|
|
|
|
|
Return 1 if you can't do anything (this is all the default
|
|
|
|
implementation of Heard() does).
|
|
|
|
|
|
|
|
|
|
|
|
*** Felt($event, $message)
|
|
|
|
|
|
|
|
Called for all emotes containing bot's nick.
|
|
|
|
|
|
|
|
Return 1 if you can't do anything (this is all the default
|
|
|
|
implementation of Felt() does).
|
|
|
|
|
|
|
|
|
|
|
|
*** Saw($event, $message)
|
|
|
|
|
|
|
|
Called for all emotes except those directly at the bot.
|
|
|
|
|
|
|
|
Return 1 if you can't do anything (this is all the default
|
|
|
|
implementation does).
|
|
|
|
|
|
|
|
|
|
|
|
*** Invited($event, $channel)
|
|
|
|
|
|
|
|
Called when bot is invited into another channel.
|
|
|
|
|
|
|
|
Return 1 if you can't do anything (this is all the default
|
|
|
|
implementation does).
|
|
|
|
|
|
|
|
|
|
|
|
*** Kicked($event, $channel)
|
|
|
|
|
|
|
|
Called when bot is kicked out of a channel.
|
|
|
|
|
|
|
|
Return 1 if you can't do anything (this is all the default
|
|
|
|
implementation does).
|
|
|
|
|
|
|
|
|
|
|
|
*** ModeChange($event, $what, $change, $who)
|
|
|
|
|
|
|
|
Called when either the channel or a person has a mode flag changed.
|
|
|
|
|
|
|
|
Return 1 if you can't do anything (this is all the default
|
|
|
|
implementation does).
|
|
|
|
|
|
|
|
|
|
|
|
*** GotOpped($event, $channel, $who)
|
|
|
|
|
|
|
|
Called when the bot is opped. (Not currently implemented.)
|
|
|
|
|
|
|
|
Return 1 if you can't do anything (this is all the default
|
|
|
|
implementation does).
|
|
|
|
|
|
|
|
|
|
|
|
*** GotDeopped($event, $channel, $who)
|
|
|
|
|
|
|
|
Called when the bot is deopped. (Not currently implemented.)
|
|
|
|
|
|
|
|
Return 1 if you can't do anything (this is all the default
|
|
|
|
implementation does).
|
|
|
|
|
|
|
|
|
|
|
|
*** Authed($event, $who)
|
|
|
|
|
|
|
|
Called when someone authenticates with us. Note that you cannot
|
|
|
|
do any channel-specific operations here since authentication is
|
|
|
|
done directly and without any channels involved. (Of course,
|
|
|
|
you can always do channel-wide stuff based on a channel list...)
|
|
|
|
|
|
|
|
Return 1 if you can't do anything (this is all the default
|
|
|
|
implementation does).
|
|
|
|
|
|
|
|
|
|
|
|
*** SpottedNickChange($event, $from, $to)
|
|
|
|
|
|
|
|
Called when someone changes their nick. You cannot use directSay
|
|
|
|
here, since $event has the details of the old nick. And 'say' is
|
|
|
|
useless since the channel is the old userhost string... This may be
|
|
|
|
changed in a future implementation.
|
|
|
|
|
|
|
|
Return 1 if you can't do anything (this is all the default
|
|
|
|
implementation does).
|
|
|
|
|
|
|
|
|
|
|
|
*** SpottedTopicChange($event, $channel, $newtopic)
|
|
|
|
|
|
|
|
Called when the topic in a channel is changed.
|
|
|
|
|
|
|
|
Return 1 if you can't do anything (this is all the default
|
|
|
|
implementation does).
|
|
|
|
|
|
|
|
|
|
|
|
*** SpottedJoin($event, $channel, $who)
|
|
|
|
|
|
|
|
Called when someone joins a channel.
|
|
|
|
|
|
|
|
Return 1 if you can't do anything (this is all the default
|
|
|
|
implementation does).
|
|
|
|
|
|
|
|
|
|
|
|
*** SpottedPart($event, $channel, $who)
|
|
|
|
|
|
|
|
Called when someone leaves a channel.
|
|
|
|
|
|
|
|
Return 1 if you can't do anything (this is all the default
|
|
|
|
implementation does).
|
|
|
|
|
|
|
|
|
|
|
|
*** SpottedKick($event, $channel, $who)
|
|
|
|
|
|
|
|
Called when someone leaves a channel, um, forcibly.
|
|
|
|
|
|
|
|
Return 1 if you can't do anything (this is all the default
|
|
|
|
implementation does).
|
|
|
|
|
|
|
|
|
|
|
|
*** SpottedQuit($event, $who, $why)
|
|
|
|
|
|
|
|
Called when someone leaves a server. You can't use say or directSay
|
|
|
|
as no channel involved and the user has quit, anyway (obviously).
|
|
|
|
This may change in future implementations (don't ask me how, please...).
|
|
|
|
|
|
|
|
Return 1 if you can't do anything (this is all the default
|
|
|
|
implementation does).
|
|
|
|
|
|
|
|
|
|
|
|
*** SpottedOpping($event, $channel, $who)
|
|
|
|
|
|
|
|
Called when someone is opped. (Not currently implemented.)
|
|
|
|
|
|
|
|
Return 1 if you can't do anything (this is all the default
|
|
|
|
implementation does).
|
|
|
|
|
|
|
|
|
|
|
|
*** SpottedDeopping($event, $channel, $who)
|
|
|
|
|
|
|
|
Called when someone is... deopped, maybe? (Not currently implemented.)
|
|
|
|
|
|
|
|
Return 1 if you can't do anything (this is all the default
|
|
|
|
implementation does).
|
|
|
|
|
|
|
|
|
2002-02-12 17:51:59 +03:00
|
|
|
*** CTCPPing($event, $who, $what)
|
|
|
|
|
|
|
|
Called when the bot receives a CTCP ping.
|
|
|
|
|
|
|
|
Return 1 if you can't do anything (this is all the default
|
|
|
|
implementation does).
|
|
|
|
|
|
|
|
|
|
|
|
*** CTCPVerson($event, $who, $what)
|
|
|
|
|
|
|
|
Called when the bot receives a CTCP verson.
|
|
|
|
|
|
|
|
Return 1 if you can't do anything (this is all the default
|
|
|
|
implementation does).
|
|
|
|
|
|
|
|
|
|
|
|
*** CTCPSource($event, $who, $what)
|
|
|
|
|
|
|
|
Called when the bot receives a CTCP source.
|
|
|
|
|
|
|
|
Return 1 if you can't do anything (this is all the default
|
|
|
|
implementation does).
|
|
|
|
|
|
|
|
|
2001-04-23 11:07:17 +04:00
|
|
|
*** Scheduled($event, @data)
|
|
|
|
|
|
|
|
Called when a scheduled timer triggers. (See 'schedule' in the next
|
|
|
|
section to see how to schedule stuff.) By default, if the first
|
|
|
|
element of the @data array is a coderef, then the coderef is called
|
|
|
|
with ($event,@data) as the arguments. Otherwise, 'debug' is called
|
|
|
|
(see below).
|
|
|
|
|
|
|
|
No special return values. Always call inherited function if you
|
|
|
|
cannot handle the scheduled event yourself.
|
|
|
|
|
|
|
|
|
|
|
|
*** GotURI($event, $uri, $contents, @data)
|
|
|
|
|
|
|
|
Called when a requested URI has been downloaded. $contents contains
|
|
|
|
the actual contents of the file. See getURI().
|
|
|
|
|
|
|
|
No special return values.
|
|
|
|
|
|
|
|
|
|
|
|
*** ChildCompleted($event, $type, $output, @data)
|
|
|
|
|
|
|
|
Called when a spawned child has completed. $output contains
|
|
|
|
the output of the process. $type contains the child type as
|
|
|
|
given to the spawnChild() API function (which see).
|
|
|
|
|
|
|
|
No special return values. Always call the inherited function if
|
|
|
|
you cannot handle the given '$type'!
|
|
|
|
|
|
|
|
|
|
|
|
*** RegisterConfig()
|
|
|
|
|
|
|
|
Called when initialised, should call registerVariables(), which see
|
|
|
|
below.
|
|
|
|
|
|
|
|
No special return values. Always call inherited function!
|
|
|
|
|
|
|
|
|
|
|
|
*** Set($event, $variable, $value)
|
|
|
|
|
|
|
|
Called to set a variable to a particular value.
|
|
|
|
|
|
|
|
Should return one of the following:
|
|
|
|
-1 - silent success (caller should not report back to user)
|
|
|
|
0 - success
|
|
|
|
1 - can't set variable because it is of type ref($module->{$variable})
|
|
|
|
2 - variable not found or not writable (if $module->{$variable})
|
|
|
|
3 - variable is list and wrong format was used
|
|
|
|
4 - variable is hash and wrong format was used
|
|
|
|
9 - unknown error
|
|
|
|
|
|
|
|
Note that error codes 1-4 are probably too specific to the default
|
|
|
|
'Set' function to be of any use. Reporting your own error messages
|
|
|
|
is fine.
|
|
|
|
|
|
|
|
Always call inherited function if you cannot set the variable yourself!
|
|
|
|
|
|
|
|
|
|
|
|
*** Get($event, $variable)
|
|
|
|
|
|
|
|
Called to get a particular variable.
|
|
|
|
|
|
|
|
Should return the value of the variable. Default returns the value
|
|
|
|
of $self->{$variable}.
|
|
|
|
|
|
|
|
Always call inherited function if you cannot get the variable yourself!
|
|
|
|
|
|
|
|
|
|
|
|
The $event variable is a hash with the following keys:
|
|
|
|
|
|
|
|
'bot' => the IRC bot object - DO NOT USE THIS!!! [1]
|
|
|
|
'channel' => the channel the event occured in, or '' if n/a [2]
|
|
|
|
'from' => the nick of the person who created the event, if any
|
|
|
|
'target' => the target of the 'say' function (channel || from)
|
|
|
|
'user' => the userhost of the event
|
|
|
|
'data' => the main data of the event
|
Makes mozbot only mark joins as joined on a successful attempt. b=112049, r=kerz.
Implements getHelpLine and getModules API functions and updates documentation to match. b=130532, r=imajes.
Adds a notice() method to the mozbot API. Updates the documentation to reflect this. (Also updates the version and corrects a typo in the docs.) b=72960, r=timeless.
Fixes the problem whereby if a module doesn't load, it's not removed from the @modulenames list, which causes problems for modules that walk the @modulenames list to get each module in turn. b=133148, r=kerz.
The Log event for the Told event doesn't have the prefix text that made the event a Told event in the first place. This adds a field 'fulldata' to the event hash which will let loggers log the whole thing. Also updates documentation. b=133509, r=kerz.
Log events were not generated for events generated by the bot. This removes redundant checks to prevent that from happening (redundant since the server never sent us the messages in the first place) and then adds code to synthesise the relevant Log events. Updates the documentation to match. b=16226, r=kerz.
The Initialise handler was needlessly within the scope of an undef'd $/. This scopes the cause of this problem. b=131483, p=Robin Berjon, r=kerz, a=hixie.
Makes ctcpSend() send messages to the target, not the originator. This makes it work like say(). b=133140, r=caillion.
Adds a way to make the auth command not give confirmation feedback (quiet auth). b=134342, r=caillon.
2002-04-01 07:46:06 +04:00
|
|
|
'fulldata' => the data of the event before it got mangled [3]
|
2001-04-23 11:07:17 +04:00
|
|
|
'to' => the target of the event
|
|
|
|
'subtype' => the IRC module's idea of what the event was [1]
|
|
|
|
'maintype' => the name of the first handler called (eg. 'Told')
|
|
|
|
'level' => the number of times the handler has been called in a row
|
|
|
|
'userName' => the name of the user as they authenticated
|
|
|
|
'userFlags' => used internally for the implementation of isAdmin(). [1]
|
|
|
|
'nick' => the nick of the bot
|
|
|
|
|
|
|
|
It is passed to most functions, as the first parameter. Modify at your
|
|
|
|
own risk! ;-) If you do write to this hash at all, ensure that you make
|
|
|
|
a 'local' copy first. See the 'Parrot' module for an example of safely
|
|
|
|
modifying the $event hash. Note that some of these fields may be
|
|
|
|
inaccurate at times, due to peculiarities of the IRC protocol.
|
|
|
|
|
|
|
|
[1]: These fields are dependent on the underlying implementation, so
|
|
|
|
if you use them then your modules will not be compatible with any other
|
|
|
|
implementations that use the same API. The 'bot' field in particular is
|
|
|
|
a blessed reference to a Net::IRC::Connection object in this
|
|
|
|
implementation, and is passed around so that the API functions know
|
|
|
|
what to operate on. However, in a POE implementation it could be
|
|
|
|
something totally different, maybe even undef. There are some other
|
|
|
|
fields in the $event hash that start with an underscore (in particular
|
|
|
|
there is '_event'). Do not even _think_ about using those. Using them
|
|
|
|
is akin to hard-coding the ionode of the 'ls' program into your source
|
|
|
|
so that you can read directories by branching to a disk address.
|
|
|
|
|
|
|
|
[2]: The 'channel' field is ALWAYS lowercase. You should always lowercase
|
|
|
|
any channel names you get from users before using them in comparisons or
|
|
|
|
hash lookups.
|
|
|
|
|
Makes mozbot only mark joins as joined on a successful attempt. b=112049, r=kerz.
Implements getHelpLine and getModules API functions and updates documentation to match. b=130532, r=imajes.
Adds a notice() method to the mozbot API. Updates the documentation to reflect this. (Also updates the version and corrects a typo in the docs.) b=72960, r=timeless.
Fixes the problem whereby if a module doesn't load, it's not removed from the @modulenames list, which causes problems for modules that walk the @modulenames list to get each module in turn. b=133148, r=kerz.
The Log event for the Told event doesn't have the prefix text that made the event a Told event in the first place. This adds a field 'fulldata' to the event hash which will let loggers log the whole thing. Also updates documentation. b=133509, r=kerz.
Log events were not generated for events generated by the bot. This removes redundant checks to prevent that from happening (redundant since the server never sent us the messages in the first place) and then adds code to synthesise the relevant Log events. Updates the documentation to match. b=16226, r=kerz.
The Initialise handler was needlessly within the scope of an undef'd $/. This scopes the cause of this problem. b=131483, p=Robin Berjon, r=kerz, a=hixie.
Makes ctcpSend() send messages to the target, not the originator. This makes it work like say(). b=133140, r=caillion.
Adds a way to make the auth command not give confirmation feedback (quiet auth). b=134342, r=caillon.
2002-04-01 07:46:06 +04:00
|
|
|
[3] This is the same as the 'data' slot except for Told and Baffled
|
|
|
|
events where it also contains the prefix that was stripped.
|
|
|
|
|
2001-04-23 11:07:17 +04:00
|
|
|
|
|
|
|
Module API
|
|
|
|
----------
|
|
|
|
|
|
|
|
This section contains the names and descriptions of the functions
|
|
|
|
that your module can call. While you can override these, it is not
|
|
|
|
recommended.
|
|
|
|
|
|
|
|
*** debug(@messages)
|
|
|
|
|
|
|
|
Outputs each item in @messages to the console (or the log file if
|
|
|
|
the bot has lost its controlling tty).
|
|
|
|
|
|
|
|
Example:
|
|
|
|
$self->debug('about to fetch listing from FTP...');
|
|
|
|
|
|
|
|
|
|
|
|
*** saveConfig()
|
|
|
|
|
|
|
|
Saves the state of the module's registered variables to the
|
|
|
|
configuration file. This should be called when the variables have
|
|
|
|
changed.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
$self->saveConfig(); # save our state!
|
|
|
|
|
|
|
|
|
|
|
|
*** registerVariables( [ $name, $persistent, $settable, $value ] )
|
|
|
|
|
|
|
|
Registers variables (duh). It actually takes a list of arrayrefs.
|
|
|
|
The first item in each arrayref is the name to use (the name of the
|
|
|
|
variable in the blessed hashref that is the module's object, i.e.
|
|
|
|
$self). The second controls if the variable is saved when
|
|
|
|
saveConfig() is called. If it is set to 1 then the variable is
|
|
|
|
saved, if 0 then it is not, and if undef then the current setting is
|
|
|
|
not changed. Similarly, the third item controls whether or not the
|
|
|
|
variable can be set using the 'vars' command (in the Admin
|
|
|
|
module). 1 = yes, 0 = no, undef = leave unchanged. The fourth value,
|
|
|
|
if defined, is used to set the variable. See the Initialise
|
|
|
|
function's entry for more details.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
$self->registerVariables(
|
|
|
|
[ 'ftpDelay', 1, 1, 60 ],
|
2001-04-29 12:35:29 +04:00
|
|
|
[ 'ftpSite', 1, 1, 'ftp.mozilla.org' ],
|
2001-04-23 11:07:17 +04:00
|
|
|
);
|
|
|
|
|
|
|
|
|
|
|
|
*** schedule($event, $time, $times, @data)
|
|
|
|
|
|
|
|
Schedules one or more events. $event is the usual event hash. $time
|
|
|
|
is the number of seconds to wait. It can be a scalarref to a
|
|
|
|
variable that contains this number, too, in which case it is
|
|
|
|
dereferenced. This comes in useful for making the frequency of
|
|
|
|
repeating events customisable. $times is the number of times to
|
|
|
|
perform the event, which can also be -1 meaning 'forever'. @data
|
|
|
|
(the remainder of the parameters) will be passed, untouched, to the
|
|
|
|
event handler, Scheduled. See the previous section.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
$self->schedule($event, \$self->{'ftpDelay'}, -1, 'ftp', \$ftpsite);
|
|
|
|
|
|
|
|
|
|
|
|
*** getURI($event, $uri, @data)
|
|
|
|
|
|
|
|
Gets a URI in the background then calls GotURI (which see, above).
|
|
|
|
|
|
|
|
Example:
|
|
|
|
$self->getURI($event, $ftpsite, 'ftp');
|
|
|
|
|
|
|
|
|
|
|
|
*** spawnChild($event, $command, $arguments, $type, $data)
|
|
|
|
|
|
|
|
Spawns a child in the background then calls ChildCompleted (which see,
|
|
|
|
above). $arguments and $data are array refs! $command is either a
|
|
|
|
command name (e.g., 'wget', 'ls') or a CODEREF. If it is a CODEREF,
|
|
|
|
then you will be wanting to make sure that the first argument is
|
|
|
|
the object reference, unless we are talking inlined code or something...
|
|
|
|
|
|
|
|
Example:
|
|
|
|
$self->spawnChild($event, '/usr/games/fortune', ['-s', '-o'],
|
|
|
|
'fortune', [@data]);
|
|
|
|
|
|
|
|
*** getModule($name)
|
|
|
|
|
|
|
|
Returns a reference to the module with the given name. In general you
|
|
|
|
should not need to use this, but if you write a management module, for
|
|
|
|
instance, then this could be useful. See God.bm for an example of this.
|
|
|
|
|
|
|
|
IT IS VITAL THAT YOU DO NOT KEEP THE REFERENCE
|
|
|
|
THAT THIS FUNCTION RETURNS!!!
|
|
|
|
|
|
|
|
If you did so, the module would not get garbage collected if it ever
|
|
|
|
got unloaded or some such.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
my $module = $self->getModule('Admin');
|
|
|
|
push(@{$module->{'files'}}, 'BotModules/SupportFile.pm');
|
|
|
|
|
|
|
|
|
Makes mozbot only mark joins as joined on a successful attempt. b=112049, r=kerz.
Implements getHelpLine and getModules API functions and updates documentation to match. b=130532, r=imajes.
Adds a notice() method to the mozbot API. Updates the documentation to reflect this. (Also updates the version and corrects a typo in the docs.) b=72960, r=timeless.
Fixes the problem whereby if a module doesn't load, it's not removed from the @modulenames list, which causes problems for modules that walk the @modulenames list to get each module in turn. b=133148, r=kerz.
The Log event for the Told event doesn't have the prefix text that made the event a Told event in the first place. This adds a field 'fulldata' to the event hash which will let loggers log the whole thing. Also updates documentation. b=133509, r=kerz.
Log events were not generated for events generated by the bot. This removes redundant checks to prevent that from happening (redundant since the server never sent us the messages in the first place) and then adds code to synthesise the relevant Log events. Updates the documentation to match. b=16226, r=kerz.
The Initialise handler was needlessly within the scope of an undef'd $/. This scopes the cause of this problem. b=131483, p=Robin Berjon, r=kerz, a=hixie.
Makes ctcpSend() send messages to the target, not the originator. This makes it work like say(). b=133140, r=caillion.
Adds a way to make the auth command not give confirmation feedback (quiet auth). b=134342, r=caillon.
2002-04-01 07:46:06 +04:00
|
|
|
*** getModules()
|
|
|
|
|
|
|
|
Returns the list of module names that are loaded, in alphabetical
|
|
|
|
order, which you can then use with getModule().
|
|
|
|
|
|
|
|
Example:
|
|
|
|
my @modulenames = $self->getModules();
|
|
|
|
local $" = ', ';
|
|
|
|
$self->ctcpReply($event, 'VERSION', "mozbot $VERSION (@modulenames)");
|
|
|
|
|
|
|
|
|
|
|
|
*** getHelpLine()
|
|
|
|
|
|
|
|
Returns the bot's help line.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
$self->say($event, $self->getHelpLine());
|
|
|
|
|
|
|
|
|
|
|
|
*** getLogFilename($name)
|
|
|
|
|
|
|
|
Returns a filename (with path) appropriate to use for logging. $name
|
|
|
|
should be the filename wanted, without a path.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
my $logName = $self->getLogFilename("$channel.log");
|
|
|
|
if (open(LOG, ">>$logName")) {
|
|
|
|
print LOG $data;
|
|
|
|
close LOG;
|
|
|
|
} else {
|
|
|
|
# XXX error handling
|
|
|
|
}
|
|
|
|
|
|
|
|
|
2001-04-23 11:07:17 +04:00
|
|
|
*** unescapeXML($xml)
|
|
|
|
|
|
|
|
Performs the following conversions on the argument and returns the result:
|
|
|
|
' => '
|
|
|
|
" => "
|
|
|
|
< => <
|
|
|
|
> => >
|
|
|
|
& => &
|
|
|
|
|
|
|
|
Example:
|
|
|
|
my $text = $self->unescapeXML($output);
|
|
|
|
|
|
|
|
|
|
|
|
*** tellAdmin($event, $data);
|
|
|
|
|
|
|
|
Tries to tell an administrator $data. As currently implemented, only
|
|
|
|
one administrator will get the message, and there is no guarentee
|
|
|
|
that they will read it or even that the admin in question is
|
|
|
|
actually on IRC at the time.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
$self->tellAdmin($event, 'Someone just tried to crack me...');
|
|
|
|
|
|
|
|
|
|
|
|
*** say($event, $data)
|
|
|
|
|
|
|
|
Says $data in whatever channel the event was spotted in (this can be
|
|
|
|
/msg if that is how the event occured).
|
|
|
|
|
|
|
|
Example:
|
|
|
|
$self->say($event, 'Yo, dude.');
|
|
|
|
|
|
|
|
|
|
|
|
*** announce($event, $data)
|
|
|
|
|
|
|
|
Says $data in all the channels the module is in.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
$self->announce($event, 'Bugzilla is back up.');
|
|
|
|
|
|
|
|
|
|
|
|
*** directSay($event, $data)
|
|
|
|
|
|
|
|
Sends a message directly to the cause of the last event (i.e., like
|
|
|
|
/msg). It is recommended to use 'say' normally, so that users have a
|
|
|
|
choice of whether or not to get the answer in the channel (they
|
|
|
|
would say their command there) or not (they would /msg their
|
|
|
|
command).
|
|
|
|
|
|
|
|
Example:
|
|
|
|
$self->directSay($event, 'Actually, that\'s not right.');
|
|
|
|
|
|
|
|
|
Makes mozbot only mark joins as joined on a successful attempt. b=112049, r=kerz.
Implements getHelpLine and getModules API functions and updates documentation to match. b=130532, r=imajes.
Adds a notice() method to the mozbot API. Updates the documentation to reflect this. (Also updates the version and corrects a typo in the docs.) b=72960, r=timeless.
Fixes the problem whereby if a module doesn't load, it's not removed from the @modulenames list, which causes problems for modules that walk the @modulenames list to get each module in turn. b=133148, r=kerz.
The Log event for the Told event doesn't have the prefix text that made the event a Told event in the first place. This adds a field 'fulldata' to the event hash which will let loggers log the whole thing. Also updates documentation. b=133509, r=kerz.
Log events were not generated for events generated by the bot. This removes redundant checks to prevent that from happening (redundant since the server never sent us the messages in the first place) and then adds code to synthesise the relevant Log events. Updates the documentation to match. b=16226, r=kerz.
The Initialise handler was needlessly within the scope of an undef'd $/. This scopes the cause of this problem. b=131483, p=Robin Berjon, r=kerz, a=hixie.
Makes ctcpSend() send messages to the target, not the originator. This makes it work like say(). b=133140, r=caillion.
Adds a way to make the auth command not give confirmation feedback (quiet auth). b=134342, r=caillon.
2002-04-01 07:46:06 +04:00
|
|
|
*** channelSay($event, $data)
|
2001-04-23 11:07:17 +04:00
|
|
|
|
|
|
|
Sends a message to the channel in which the message was given.
|
|
|
|
If the original command was sent in a /msg, then this will result
|
|
|
|
in precisely nothing. Useful in conjunction with directSay() to
|
|
|
|
make it clear that a reply was sent privately.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
$self->directSay($event, $veryLongReply);
|
|
|
|
$self->channelSay($event, "$event->{'from'}: data /msg'ed");
|
|
|
|
|
|
|
|
|
|
|
|
*** emote($event, $what)
|
|
|
|
*** directEmote($event, $what)
|
|
|
|
|
|
|
|
Same as say() and directSay(), but do the equivalent of /me instead.
|
|
|
|
|
|
|
|
Examples:
|
|
|
|
$self->emote($event, "slaps $event->{'from'} with a big smelly trout.");
|
|
|
|
$self->directEmote($event, "waves.");
|
|
|
|
|
|
|
|
|
|
|
|
*** sayOrEmote($event, $what)
|
|
|
|
*** directSayOrEmote($event, $what)
|
|
|
|
|
|
|
|
Call say (directSay) or emote (directEmote) based on the contents of $what.
|
|
|
|
If $what starts with '/me' then the relevant emote variation is called,
|
|
|
|
otherwise the say variations are used. The leading '/me' is trimmed before
|
|
|
|
being passed on.
|
|
|
|
|
|
|
|
Examples:
|
|
|
|
$self->sayOrEmote($event, $greeting);
|
|
|
|
$self->directSayOrEmote($event, $privateMessage);
|
|
|
|
|
|
|
|
|
2002-02-12 17:51:59 +03:00
|
|
|
*** ctcpSend($event, $type, $data)
|
|
|
|
|
|
|
|
Same as say() but for sending CTCP messages.
|
|
|
|
|
|
|
|
Examples:
|
|
|
|
$self->ctcpSend($event, 'PING', time());
|
|
|
|
|
|
|
|
|
|
|
|
*** ctcpReply($event, $type, $data)
|
|
|
|
|
|
|
|
Same as ctcpSend() but for sending CTCP replies.
|
|
|
|
|
|
|
|
Examples:
|
|
|
|
$self->ctcpReply($event, 'VERSION', "Version $major.$minor");
|
|
|
|
|
|
|
|
|
Makes mozbot only mark joins as joined on a successful attempt. b=112049, r=kerz.
Implements getHelpLine and getModules API functions and updates documentation to match. b=130532, r=imajes.
Adds a notice() method to the mozbot API. Updates the documentation to reflect this. (Also updates the version and corrects a typo in the docs.) b=72960, r=timeless.
Fixes the problem whereby if a module doesn't load, it's not removed from the @modulenames list, which causes problems for modules that walk the @modulenames list to get each module in turn. b=133148, r=kerz.
The Log event for the Told event doesn't have the prefix text that made the event a Told event in the first place. This adds a field 'fulldata' to the event hash which will let loggers log the whole thing. Also updates documentation. b=133509, r=kerz.
Log events were not generated for events generated by the bot. This removes redundant checks to prevent that from happening (redundant since the server never sent us the messages in the first place) and then adds code to synthesise the relevant Log events. Updates the documentation to match. b=16226, r=kerz.
The Initialise handler was needlessly within the scope of an undef'd $/. This scopes the cause of this problem. b=131483, p=Robin Berjon, r=kerz, a=hixie.
Makes ctcpSend() send messages to the target, not the originator. This makes it work like say(). b=133140, r=caillion.
Adds a way to make the auth command not give confirmation feedback (quiet auth). b=134342, r=caillon.
2002-04-01 07:46:06 +04:00
|
|
|
*** notice($event, $data)
|
|
|
|
|
|
|
|
Sends a notice containing $data to whatever channel the event was
|
|
|
|
spotted in (this can be /msg if that is how the event occured).
|
|
|
|
|
|
|
|
Example:
|
|
|
|
foreach (@{$self->{'channels'}}) {
|
|
|
|
local $event->{'target'} = $_;
|
|
|
|
$self->notice($event, 'This is a test of the emergency announcement system.');
|
|
|
|
}
|
|
|
|
|
|
|
|
|
2001-04-23 11:07:17 +04:00
|
|
|
*** isAdmin($event)
|
|
|
|
|
|
|
|
Returns true if the cause of the event was an authenticated administrator.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
if ($self->isAdmin($event)) { ... }
|
|
|
|
|
|
|
|
|
|
|
|
*** setAway($event, $message)
|
|
|
|
|
|
|
|
Set the bot's 'away' flag. A blank message will mark the bot as
|
|
|
|
back. Note: If you need this you are doing something wrong!!!
|
|
|
|
Remember that you should not be doing any lengthy processes since if
|
2001-04-29 12:35:29 +04:00
|
|
|
you are away for any length of time, the bot will be disconnected!
|
2001-04-23 11:07:17 +04:00
|
|
|
|
|
|
|
Also note that in 2.0 this is not throttled, so DO NOT call this
|
|
|
|
repeatedly, or put yourself in any position where you allow IRC
|
|
|
|
users to cause your module to call this. Otherwise, you open
|
|
|
|
yourself to denial of service attacks.
|
|
|
|
|
|
|
|
Finally, note that calling 'do', 'emote', 'say', and all the
|
|
|
|
related functions will also reset the 'away' flag.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
$self->setAway($event, 'brb...');
|
|
|
|
|
|
|
|
|
|
|
|
*** setNick($event, $nick)
|
|
|
|
|
|
|
|
Set the bot's nick. This handles all the changing of the internal
|
|
|
|
state variables and saving the configuration and everything.
|
|
|
|
It will also add the nick to the list of nicks to try when
|
|
|
|
the bot finds its nick is already in use.
|
|
|
|
|
|
|
|
Note that in 2.0 this is not throttled, so DO NOT call this
|
|
|
|
repeatedly, or put yourself in any position where you allow IRC
|
|
|
|
users to cause your module to call this. Otherwise, you open
|
|
|
|
yourself to denial of service attacks.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
$self->setNick($event, 'zippy');
|
|
|
|
|
|
|
|
|
|
|
|
*** mode($event, $channel, $mode, $argument)
|
|
|
|
|
|
|
|
Changes a mode of channel $channel.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
$self->mode($event, $event->{'channel'}, '+o', 'Hixie');
|
|
|
|
|
|
|
|
|
|
|
|
*** invite($event, $who, $channel)
|
|
|
|
|
|
|
|
Invite $who to channel $channel. This can be used for intrabot
|
|
|
|
control, or to get people into a +i channel, for instance.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
$self->invite($event, 'Hixie', '#privateChannel');
|
|
|
|
|
|
|
|
|
|
|
|
*** prettyPrint($preferredLineLength, $prefix, $indent, $divider, @input)
|
|
|
|
|
|
|
|
Takes @input, and resorts it so that the lines are of roughly the same
|
|
|
|
length, aiming optimally at $preferredLineLength, prefixing each line
|
|
|
|
with $indent, placing $divider between each item in @input if they
|
|
|
|
appear on the same line, and sticking $prefix at the start of it all on
|
|
|
|
the first line. The $prefix may be undef.
|
|
|
|
|
|
|
|
Returns the result of all that.
|
|
|
|
|
|
|
|
This is what the 'help' command uses to pretty print its output.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
my @result = $self->prettyPrint($linelength, undef, 'Info: ', ' -- ', @infoItems);
|
|
|
|
|
|
|
|
|
|
|
|
*** wordWrap($preferredLineLength, $prefix, $indent, $divider, @input)
|
|
|
|
|
|
|
|
Takes @input, and places each item sequentially on lines, aiming optimally
|
|
|
|
at $preferredLineLength, prefixing each line with $indent, placing $divider
|
|
|
|
between each item in @input if they appear on the same line, and sticking
|
|
|
|
$prefix at the start of it all on the first line, without ever cutting
|
|
|
|
items across lines. The $prefix may be undef.
|
|
|
|
|
|
|
|
Returns the result of all that.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
my @result = $self->wordWrap($linelength, undef, 'Info: ', ' ', split(/\s+/os, @lines);
|
|
|
|
|
|
|
|
|
|
|
|
*** days($time)
|
|
|
|
|
|
|
|
Returns a string describing the length of time between $time and now.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
$self->debug('uptime: '.$self->days($^T));
|
|
|
|
|
|
|
|
|
|
|
|
*** sanitizeRegexp($regexp)
|
|
|
|
|
|
|
|
Checks to see if $regexp is a valid regular expression. If it is, returns
|
|
|
|
the argument unchanged. Otherwise, returns quotemeta($regexp), which should
|
|
|
|
be safe to use in regular expressions as a plain text search string.
|
|
|
|
|
|
|
|
Do not add prefixes or suffixes to the pattern after sanitizing it.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
$pattern = $self->sanitizeRegexp($pattern);
|
|
|
|
$data =~ /$pattern//gosi;
|
|
|
|
|
|
|
|
|
|
|
|
-- end --
|