Nanobot code help

Writing plugins for nanobot

If you cannot find a plugin with the functionality you need you may decide you want to write a plugin yourself.

The demo plugin

By far the best place to start is with the demo plugin. It has a short description and example for every special function and examples of some common constructions you may use when writing your own plugin. Besides that hand full of special functions it's just plain Ruby.

Global objects

There are a few global objects that a plugin gets access to when it's loaded, these are defined in the initialize function. We will be describing functions using the following conventions:

function(): name of a function so in ruby this would be 'def function'

argument: required argument to a function.

<argument>: optional argument to a function.

arg1|arg2: A specific set of options that are accepted. The function expects either 'arg1' or 'arg2' but not both or neither.

<arg1|arg2>: A specific set of options that are accepted. Unlike the previous, the function may also be called without any arguments. When called without arguments it will return the current value.

@status

This object contains most of the runtime state of the bot. Functions exist to interact with the status objects:

output( <0|1> ): Enable or disable output (-q option on the commandline)

colour( <0|1> ): Enable or disable colour in console output (-c option on the commandline)

debug( <0|1|2|3> ): Controls the debug level (-d option on the commandline)

login( <0|1> ): Switch so the bot knows if it's past it's login sequence. (Ident with nickserv and wait for ping if configured to do so.) Normally not something you want to manipulate yourself

threads( <0|1> ): Controls if threading is enabled. Not something you'd want to normally change at runtime. Things may break horribly if you do. (-t/-nt options on the commandline)

tabcomplete( <0|1> ): Enable or disable tab completion on the console

ssl( <0|1> ): Control use of SSL on connect. No reason to ever change this after you've connected. (-s option on the commandline)

console( <0|1> ): Enable or disable the interactive console (-n option on the commandline)

reconnect( <0|1> ): Control if we should attempt to reconnect automatically if the connection to the IRC server is lost.

autoload( <0|1> ): Status bit to see if we've completed the autoload on startup. No reason to change this yourself.

showconfig( <0|1> ): Used to check if the -p option is given on the commandline. Does nothing after startup.

plugins( <plugin array> ): Used to set or retrieve or set the whole list of plugins references. Not something you'd normally want to get and certainly not something you'd want to set yourself.

addplugin( plugin_name, plugin_object ): Add a plugin to the plugins list. Not something you need unless you're loading in ruby objects yourself.

delplugin( plugin_name ): Removes a plugin from the list of active plugins. Normally only done by the !unload command.

checkplugin( plugin_name ): Check if a plugin by that name is loaded.

getplugin( plugin_name ): Retrieve the reference to a plugin so we can execute it's functions.

startup(): Returns the time object of when the bot was started.

uptime( <current_time_object>, <old_time_object> ): Returns a human readable string of how much time is between the two time objects. The first defaults to Time.now the second defaults to the bots startup time.

giveconfig( config_object ): Set the config object used by the status object. Normally done by the bot on startup after the config is parsed.

getBaseComplete(): Returns a list of the built in functions and loaded plugin names. Used by the tab-complete functionality of the interactive console.

getPluginComplete( plugin_name ): Returns a list of a plugins' functions . Used by the tab-complete functionality of the interactive console.

@config

The object contains the static configuration held in config.rb. Any changes made to the contents of the @config object will be lost when the bot is stopped.

nick( <nickname> ): Stores the bot's own nickname. Note that changing this value does not send the 'NICK' command to the IRC server.

pass( <password> ): Stores the bot's nickserv password.

user( <username> ): Stores the username portion of the bot's identification.

version(): Returns the string containing the current version of the bot.

command( <cmd_string> ): Stores the character used to prefix commands in IRC.

server(): Returns the address/hostname of the server the bot is connecting to.

port(): Returns the port number the bot is connecting to.

ssl( <true|false> ): Stores if we should connect using ssl.

verifyssl( <true|false> ): Stores if we should attempt to see if the SSL certificate is valid. (Not self-signed, expired, revoked etc.)

rootcert(): Returns the location where it looks for SSL root certificates when trying to verify the server's SSL certificate.

ipv6( <true|false> ): Stores if the bot uses @server or @server6 to connect.

serverpass( <password> ): Stores the password used to connect to the IRC server.

connectoptions( <connect string> ): Stores any other string you want to send right when the bot connects. I have no idea why you'd want to do such a thing though.

threads( <true|false> ): Stores if the bot uses threads or not.

threadingfallback(): Returns if we're allowed to fall back to not using threads if they're not available.

connecttimeout(): Returns the socket timeout on connecting to the IRC server

pingtimeout(): Returns the ping timeout after which we will assume we lost connection with the server.

antiflood( <true|false> ): Stores if we should throttle users sending commands to the bot.

floodtime( <seconds> ): Stores the limit for how much time there should be between commands.

floodcut( <seconds> ): Stores how long the delay should become before we just start dropping commands.

throttleoutput( <true|false> ): Stores if we should throttle our own output so the server does not ban us for spamming when there is a lot of output.

rejoin( <true|false> ): Stores if we should try to rejoin a channel when kicked.

rejointime( <seconds> ): Stores how many seconds we should wait before trying to rejoin after being kicked.

waitforping( <true|false> ): Stores if we should wait for the server to send a PING before trying to join channels.

opers( <list_of_opres ): Stores the list of hosts that are bot admins.

channels( <list_of_channels ): Stores the list of channels that we automatically join on connect.

autoload( <list_of_plugin_names> ): Stores the list of plugins to load on startup.

datadir( <directory_name> ): Stores the name of the directory where data may be stored.

plugindir( <directory_name ): Stores the name of the directory where the bot looks for plugins.

auth( hostname, console_bool ): Check if you are authorized to execute a command either because your hostname is in the opers list or because the command is executed from the interactive console.

show(): Called on startup to see if the -p option is set. Do not call manually since it calls 'Process.exit' at the end of the function.

yn( variable ): Helper function for 'show()'. Returns 'Yes' if a variable is true, 'No' if false.