Plugin development

Plugin development

This documentation page needs to be improved. Contributions are welcomed.

##Overview ##

Gary continually scans the plugins/ directory for new or changed .py files. When it finds one, it runs it and examines each function to see whether it is a plugin hook.

All plugins need to from util import hook in order to be callable.

A simple example

plugins/echo.py:

from util import hook

@hook.command
def echo(inp):
    return inp + inp

usage:

<bears> .echo hots
<Gary> bears: hotshots

This plugin example defines a command that replies with twice its input. It can be invoked by saying phrases in a channel the bot is in, notably ".echo", "Gary: echo", and "Gary, echo" (assuming the bot's nick is "Gary").

Plugin hooks

There are four types of plugin hooks: commands, regexes, events, and sieves. The hook type is assigned to plugin functions using decorators found in util/hook.py.

There is also a secondary hook decorator: @hook.singlethread

It indicates that the function should run in its own thread. Note that, in that case, you can't use the existing database connection object.

Shared arguments

This section has to be verified.

These arguments are shared by functions of all hook types:

• nick -- string, the nickname of whoever sent the message.
• channel -- string, the channel the message was sent on. Equal to nick if it's a private message.
• msg -- string, the line that was sent.
• raw -- string, the raw full line that was sent.
• re -- the result of doing re.match(hook, msg).
• bot -- the running bot object.
• db -- the database connection object.
• input -- the triggering line of text

Commands hook

@hook.command @hook.command(command_name)

Commands run when the beginning of a normal chat line matches one of .command, botnick: command, or botnick, command, where command is the command name, and botnick is the bot's nick on the server.

Commands respond to abbreviated forms: a command named "dictionary" will be invoked on both ".dictionary" and ".dict". If an abbreviated command is ambiguous, the bot will return with a list of possibilities: given commands "dictionary" and "dice", attempting to run command ".di" will make the bot say "did you mean dictionary or dice?".

When @hook.command is used without arguments, the command name is set to the function name. When given an argument, it is used as the command name. This allows one function to respond to multiple commands:

from util import hook

@hook.command('hi')
@hook.command
def hello(inp):
    return "Hey there!"

Users can invoke this function with either ".hello" or ".hi".

Regexes hook

This section needs to be improved.

@hook.regex(pattern)

Each line of chat is matched against the provided regex pattern. If it is successful, the hook function will be called with the matched object.

from util import hook

@hook.regex("lame bot")
def hurtfulcomment(match):
    return "I have FEELINGS!"

Events hook

This section needs to be improved.

@hook.event(irc_command)

Event hooks are called whenever a specific IRC command is issued. For example, if you provide "*" as parameter, it will trigger on every line. If you provide "PRIVMSG", it will only trigger on actual lines of chat (not nick-changes).

The first argument in these cases will be a two-element list of the form ["#channel", "text"].

Sieves hook

This section needs to be improved.

@hook.sieve

Sieves can prevent commands, regexes, and events from running.

For instance, commands could be tagged as admin-only, and then a sieve would verify that the user invoking the command has the necessary privileges.

The function must take 5 arguments: (bot, input, func, type, args). To cancel a call, return None.

Available objects

This section needs to be written.

The bot object

The db object

The input object