Class ScriptBotCore

ScriptBotCore is intended to be a very basic core for a bot built via JavaScript. The bot core provides simple system for managing plugins, and very few features. This core is intended to be extended by the plugins, rather than having the features directly tacked onto the bot.

If new features are added directly to the bot (because the "expense" of making them plugins would not be worth it) any plugins that recieve information from this feature should receive a JS object (not a Java object), even if it requires taking extra steps to convert.
Defined in: </ScriptBot/trunk/src/app/scriptbot.js>.

Class Summary
Constructor Attributes	Constructor Name and Description
	ScriptBotCore() Creates a default ScriptBotCore.

Field Summary
Field Attributes	Field Name and Description
	ERROR A public constant (read only) representing an error "source" in log messages.
<inner>	prefix This is the main prefix to which the bot responds.
	SERVER A public constant (read only) representing the server in log messages.

Method Summary
Method Attributes	Method Name and Description
	exit() Causes this bot instance to disconnect from the server immediately.
	fireEvent(type, args) Fires the given event (type) with the following arguments (in an array).
	fireMessageEvent(type, args, priv) An internal function to specially handle onMessage events.
	getPluginInformation() Returns a list of all the names of the registered information handlers.
	initialize(nick, ircServer, ircChannel, password) Connects the bot with the specified name to the specified IRC server, and joins a default channel, if given.
	log(msg, source, extraLine) Logs the given message to the console, optionally displaying the source of the message.
	onAction(sender, login, hostname, target, action)
	onChannelInfo(channel, userCount, topic)
	onConnect()
	onDeop(channel, sourceNick, sourceLogin, sourceHostname, recipient)
	onDeVoice(channel, sourceNick, sourceLogin, sourceHostname, recipient)
	onDisconnect()
	onFinger(sourceNick, sourceLogin, sourceHostname, target)
	onInvite(targetNick, sourceNick, sourceLogin, sourceHostname, channel)
	onJoin(channel, sender, login, hostname)
	onKick(channel, kickerNick, kickerLogin, kickerHostname, recipientNick, reason)
	onMessage(channel, sender, login, hostname, message)
	onMode(channel, sourceNick, sourceLogin, sourceHostname, mode)
	onNickChange(oldNick, login, hostname, newNick)
	onNotice(sourceNick, sourceLogin, sourceHostname, target, notice)
	onOp(channel, sourceNick, sourceLogin, sourceHostname, recipient)
	onPart(channel, sender, login, hostname)
	onPing(sourceNick, sourceLogin, sourceHostname, target, pingValue)
	onPrivateMessage(sender, login, hostname, message)
	onQuit(sourceNick, sourceLogin, sourceHostname, reason)
	onRemoveChannelBan(channel, sourceNick, sourceLogin, sourceHostname, hostmask)
	onRemoveChannelKey(channel, sourceNick, sourceLogin, sourceHostname, key)
	onRemoveChannelLimit(channel, sourceNick, sourceLogin, sourceHostname)
	onRemoveInviteOnly(channel, sourceNick, sourceLogin, sourceHostname)
	onRemoveModerated(channel, sourceNick, sourceLogin, sourceHostname)
	onRemoveNoExternalMessages(channel, sourceNick, sourceLogin, sourceHostname)
	onRemovePrivate(channel, sourceNick, sourceLogin, sourceHostname)
	onRemoveSecret(channel, sourceNick, sourceLogin, sourceHostname)
	onRemoveTopicProtection(channel, sourceNick, sourceLogin, sourceHostname)
	onServerResponse(code, response)
	onSetChannelBan(channel, sourceNick, sourceLogin, sourceHostname, hostmask)
	onSetChannelKey(channel, sourceNick, sourceLogin, sourceHostname, key)
	onSetChannelLimit(channel, sourceNick, sourceLogin, sourceHostname, limit)
	onSetInviteOnly(channel, sourceNick, sourceLogin, sourceHostname)
	onSetModerated(channel, sourceNick, sourceLogin, sourceHostname)
	onSetNoExternalMessages(channel, sourceNick, sourceLogin, sourceHostname)
	onSetPrivate(channel, sourceNick, sourceLogin, sourceHostname)
	onSetSecret(channel, sourceNick, sourceLogin, sourceHostname)
	onSetTopicProtection(channel, sourceNick, sourceLogin, sourceHostname)
	onTime(sourceNick, sourceLogin, sourceHostname, target)
	onTopic(channel, topic, setBy, date, changed)
	onUnknown(line)
	onUserList(channel, users)
	onUserMode(targetNick, sourceNick, sourceLogin, sourceHostname, mode)
	onVersion(sourceNick, sourceLogin, sourceHostname, target)
	onVoice(channel, sourceNick, sourceLogin, sourceHostname, recipient)
	registerPlugin(event, handler, id) Registers a restricted plugin for the speicifed event.
	registerPluginInfo(plugin, handler, id) Registers a handler to be called when a user asks for information on a plugin or command to which a plugin may respond.
	registerUnhandledEventPlugin(event, handler) Registers a restricted plugin which is called if/when no other plugins handle the specified event.
	registerUnhandledPluginInfo(handler) Registers a handler to be called when a no information handlers were called for a given information request.
	registerUnrestrictedPlugin(event, handler, id) Registers an unrestricted plugin for the speicifed event.
	setPassword(value) Sets the password to be used when this bot attempts to join a server.
	setScriptLoggingEnabled(value) Sets whether or not to enabled this bot's own logging.
	setVerbose(value) Sets whether or not to enabled PircBot's included logging.
	unregisterPlugin(plugin, info) Unregisters a handler so it is no longer called on events.
	unregisterPluginByEvent(plugin, id, Whether) Unregisters a handler so it is no longer called for the specified event.
	unregisterPluginInfo(plugin, id) Unregisters a help entry so that it is no longer called.
	unregisterUnhandledEventPlugin(event) Removes the unhandled-event listener called for the specified event.
	unregisterUnhandledPluginInfo() Unregisters the function called when nothing handles an information request.

Class Detail

ScriptBotCore()

Creates a default ScriptBotCore. To connect to IRC, see #initialize.
Author: AMcBain, 2008.

Field Detail

{string} ERROR

A public constant (read only) representing an error "source" in log messages.

<inner> {string} prefix

This is the main prefix to which the bot responds.

Default Value:: "@"

{string} SERVER

A public constant (read only) representing the server in log messages.

Method Detail

exit()

Causes this bot instance to disconnect from the server immediately.

fireEvent(type, args)

Fires the given event (type) with the following arguments (in an array).

Parameters:
{string} type: The name of the event.
{Array} args: The array parameters.

Since:: 2.0.1

fireMessageEvent(type, args, priv)

An internal function to specially handle onMessage events.

Parameters:
{string} type: The name of the event.
{Array} args: The array parameters.
{boolean} priv: Whether this is a private message or not.

Since:: 2.0.1

{Array} getPluginInformation()

Returns a list of all the names of the registered information handlers. This can be used as a general guide to the plugins installed in this bot. However, it is possible certain plugins did not register an information handler, in which case they cannot be returned by this function.

Since:: 2.0.1

Returns:: A list of registered plugin information handlers' names.

See:: #registerPluginInfo

initialize(nick, ircServer, ircChannel, password)

Connects the bot with the specified name to the specified IRC server, and joins a default channel, if given. A password may also be supplied for registered nicks.

Parameters:
{string} nick: The nick used when the bot attempts to join IRC.
{string} ircServer: The server to which this bot will attempt to connect.
{string} ircChannel: The default channel to join after this bot successfully connects to IRC.
{string} password Optional: Optionally the password for the given nick, if it is registered with services.

Since:: 2.0.1

log(msg, source, extraLine)

Logs the given message to the console, optionally displaying the source of the message.

Parameters:
{string} msg: The message to be logged.
{string} source Optional: Optionally, the source of the item logging this message.
{boolean} extraLine Optional: Optionally print an extra new line after this log message.

Since:: 2.0.1

onAction(sender, login, hostname, target, action)

Parameters:
sender
login
hostname
target
action

onChannelInfo(channel, userCount, topic)

Parameters:
channel
userCount
topic

onConnect()

onDeop(channel, sourceNick, sourceLogin, sourceHostname, recipient)

Parameters:
channel
sourceNick
sourceLogin
sourceHostname
recipient

onDeVoice(channel, sourceNick, sourceLogin, sourceHostname, recipient)

Parameters:
channel
sourceNick
sourceLogin
sourceHostname
recipient

onDisconnect()

onFinger(sourceNick, sourceLogin, sourceHostname, target)

Parameters:
sourceNick
sourceLogin
sourceHostname
target

onInvite(targetNick, sourceNick, sourceLogin, sourceHostname, channel)

Parameters:
targetNick
sourceNick
sourceLogin
sourceHostname
channel

onJoin(channel, sender, login, hostname)

Parameters:
channel
sender
login
hostname

onKick(channel, kickerNick, kickerLogin, kickerHostname, recipientNick, reason)

Parameters:
channel
kickerNick
kickerLogin
kickerHostname
recipientNick
reason

onMessage(channel, sender, login, hostname, message)

Parameters:
channel
sender
login
hostname
message

onMode(channel, sourceNick, sourceLogin, sourceHostname, mode)

Parameters:
channel
sourceNick
sourceLogin
sourceHostname
mode

onNickChange(oldNick, login, hostname, newNick)

Parameters:
oldNick
login
hostname
newNick

onNotice(sourceNick, sourceLogin, sourceHostname, target, notice)

Parameters:
sourceNick
sourceLogin
sourceHostname
target
notice

onOp(channel, sourceNick, sourceLogin, sourceHostname, recipient)

Parameters:
channel
sourceNick
sourceLogin
sourceHostname
recipient

onPart(channel, sender, login, hostname)

Parameters:
channel
sender
login
hostname

onPing(sourceNick, sourceLogin, sourceHostname, target, pingValue)

Parameters:
sourceNick
sourceLogin
sourceHostname
target
pingValue

onPrivateMessage(sender, login, hostname, message)

Parameters:
sender
login
hostname
message

onQuit(sourceNick, sourceLogin, sourceHostname, reason)

Parameters:
sourceNick
sourceLogin
sourceHostname
reason

onRemoveChannelBan(channel, sourceNick, sourceLogin, sourceHostname, hostmask)

Parameters:
channel
sourceNick
sourceLogin
sourceHostname
hostmask

onRemoveChannelKey(channel, sourceNick, sourceLogin, sourceHostname, key)

Parameters:
channel
sourceNick
sourceLogin
sourceHostname
key

onRemoveChannelLimit(channel, sourceNick, sourceLogin, sourceHostname)

Parameters:
channel
sourceNick
sourceLogin
sourceHostname

onRemoveInviteOnly(channel, sourceNick, sourceLogin, sourceHostname)

Parameters:
channel
sourceNick
sourceLogin
sourceHostname

onRemoveModerated(channel, sourceNick, sourceLogin, sourceHostname)

Parameters:
channel
sourceNick
sourceLogin
sourceHostname

onRemoveNoExternalMessages(channel, sourceNick, sourceLogin, sourceHostname)

Parameters:
channel
sourceNick
sourceLogin
sourceHostname

onRemovePrivate(channel, sourceNick, sourceLogin, sourceHostname)

Parameters:
channel
sourceNick
sourceLogin
sourceHostname

onRemoveSecret(channel, sourceNick, sourceLogin, sourceHostname)

Parameters:
channel
sourceNick
sourceLogin
sourceHostname

onRemoveTopicProtection(channel, sourceNick, sourceLogin, sourceHostname)

Parameters:
channel
sourceNick
sourceLogin
sourceHostname

onServerResponse(code, response)

Parameters:
code
response

onSetChannelBan(channel, sourceNick, sourceLogin, sourceHostname, hostmask)

Parameters:
channel
sourceNick
sourceLogin
sourceHostname
hostmask

onSetChannelKey(channel, sourceNick, sourceLogin, sourceHostname, key)

Parameters:
channel
sourceNick
sourceLogin
sourceHostname
key

onSetChannelLimit(channel, sourceNick, sourceLogin, sourceHostname, limit)

Parameters:
channel
sourceNick
sourceLogin
sourceHostname
limit

onSetInviteOnly(channel, sourceNick, sourceLogin, sourceHostname)

Parameters:
channel
sourceNick
sourceLogin
sourceHostname

onSetModerated(channel, sourceNick, sourceLogin, sourceHostname)

Parameters:
channel
sourceNick
sourceLogin
sourceHostname

onSetNoExternalMessages(channel, sourceNick, sourceLogin, sourceHostname)

Parameters:
channel
sourceNick
sourceLogin
sourceHostname

onSetPrivate(channel, sourceNick, sourceLogin, sourceHostname)

Parameters:
channel
sourceNick
sourceLogin
sourceHostname

onSetSecret(channel, sourceNick, sourceLogin, sourceHostname)

Parameters:
channel
sourceNick
sourceLogin
sourceHostname

onSetTopicProtection(channel, sourceNick, sourceLogin, sourceHostname)

Parameters:
channel
sourceNick
sourceLogin
sourceHostname

onTime(sourceNick, sourceLogin, sourceHostname, target)

Parameters:
sourceNick
sourceLogin
sourceHostname
target

onTopic(channel, topic, setBy, date, changed)

Parameters:
channel
topic
setBy
date
changed

onUnknown(line)

Parameters:
line

onUserList(channel, users)

Parameters:
channel
users

onUserMode(targetNick, sourceNick, sourceLogin, sourceHostname, mode)

Parameters:
targetNick
sourceNick
sourceLogin
sourceHostname
mode

onVersion(sourceNick, sourceLogin, sourceHostname, target)

Parameters:
sourceNick
sourceLogin
sourceHostname
target

onVoice(channel, sourceNick, sourceLogin, sourceHostname, recipient)

Parameters:
channel
sourceNick
sourceLogin
sourceHostname
recipient

registerPlugin(event, handler, id)

Registers a restricted plugin for the speicifed event. Restricted plugins do not recieve the whole IRC line sent for some events, and may only be called if the the IRC line was intended for the bot.

Parameters:
{string} event: The name of the event for which this handler is being registered.
{Function} handler: The function to be called when this event is fired.
{string} id Optional: An optional id to be assigned to this plugin.

Since:: 2.0.1

See:: #unregisterPlugin; #registerUrestrictedPlugin; #registerPluginInfo

registerPluginInfo(plugin, handler, id)

Registers a handler to be called when a user asks for information on a plugin or command to which a plugin may respond. Commands are case-sensitive.

Parameters:
{string} plugin: The name of the plugin for which this handler is being registered.
{Function} handler: The function to be called when this event is fired.
{string} id Optional: An optional id to be assigned to this plugin.

Since:: 2.0.1

See:: #registerPlugin; #registerUrestrictedPlugin

registerUnhandledEventPlugin(event, handler)

Registers a restricted plugin which is called if/when no other plugins handle the specified event. Only one plugin of this type can be registered per event.

Parameters:
{string} event: The name of the event for which this handler is being registered.
{Function} handler: The function to be called when this event is fired.

Since:: 2.0.1

See:: #unregisterUnhandledEventPlugin

registerUnhandledPluginInfo(handler)

Registers a handler to be called when a no information handlers were called for a given information request.

Parameters:
{Function} handler: The function to be called when this event is fired.

Since:: 2.0.1

See:: #registerPluginInfo

registerUnrestrictedPlugin(event, handler, id)

Registers an unrestricted plugin for the speicifed event. Restricted plugins do not recieve the whole IRC line sent for some events, and may only be called if the the IRC line was intended for the bot. Unrestricted plugins are called every time this event is fired and are sent the whole line.

Parameters:
{string} event: The name of the event for which this handler is being registered.
{Function} handler: The function to be called when this event is fired.
{string} id Optional: An optional id to be assigned to this plugin.

Since:: 2.0.1

See:: #unregisterPlugin; #registerPlugin; #registerPluginInfo

setPassword(value)

Sets the password to be used when this bot attempts to join a server.

Parameters:
{string} value: The new password for this bot.

setScriptLoggingEnabled(value)

Sets whether or not to enabled this bot's own logging. Default is true.

For enabling or disabling PircBot based logging see #setVerbose.

Parameters:
{boolean} value: Whether or not to enable PircBot's logging.

Since:: 2.0.1

See:: #setVerbose

setVerbose(value)

Sets whether or not to enabled PircBot's included logging. Since this bot overwrites the function log, it must also keep track of logging-enabled status. Default is false.

For enabling or disabling ScriptBot based logging see #setScriptLoggingEnabled.

Parameters:
{boolean} value: Whether or not to enable PircBot's logging.

See:: #setScriptLoggingEnabled

{boolean} unregisterPlugin(plugin, info)

Unregisters a handler so it is no longer called on events. This removes all instances of the plugin it can find, and if an id is provided instead, all plugins and information entries with that id. Optionally, an array or string can be provided to aid in removal of information entries assotiated with this plugin, however this is ignored if an id is provided for the first argument. This entire process can be costly.

Parameters:
{string/Function} plugin: The handler or id of the plugin being removed.
{string/Array} info Optional: An optional string or array specifying which information entries to also remove.

Since:: 2.0.1

Returns:: true if anything was unregsitered, false otherwise.

See:: #unregisterPluginByEvent

{boolean} unregisterPluginByEvent(plugin, id, Whether)

Unregisters a handler so it is no longer called for the specified event. This does not remove any associated help entries. Nothing is removed if no id or function is specified or they do not match an valid registered entries. This is less costly than #unregisterPlugin.

Parameters:
{string} plugin: The name or id of the plugin being removed.
{string/Function} id: An function or id by which to determine what to remove.
{boolean} Whether: or not the plugin to be removed is unrestricted.