This is the documentation for plugin api v1

Plugins are coded in Python and imported by forkb0t

Pick a name for your plugin, then do the following, in order. Anyone with common sense will be able to print "Hello, World!".

1. On IRC, do "!forkdev new <foo>" (<foo> is name for your plugin)
2. On IRC, do "!forkdev login"
3. Navigate to <foo> directory on server. Will need to drill down a few levels to get there.
4. Edit <foo>.py
5. Edit <foo>.conf
6. On IRC, ask a superuser (krushia, guzzlefry, or ed-209) to review your code and do "!forkdev up <foo>"

See other thingy

forkb0t development is done online in a shared code repository. All plugin code - current, past, and in progress - is available here. To prevent abuse, the details are not printed here. To see the information required to mount the share, type "!forkdev login" on IRC.

Below, we see an example of what the source tree would look like. All plugins are stored in a separate directory under the aptly named "plugins" directory. Here we see two plugins, one named "_template" and another named "calc".

"_template" shows what you would see immediately after envoking "!forkdev new". It contains three files, which are described later in this manual. Files in the root of a plugin's directory are the "working set" or "trunk". These are the files that are being edited.

"calc" shows a plugin that has been through two revisions. When you run "!forkdev commit" for the first time, the subdirectory "revisions" is created, and all files from the base (our working set) are saved in yet another subdirectory with the revision number appended. In this case, "calc.0001". The next "!forkdev commit" created version 2.

Now draw your attention to the "current" symlink. This link is created when one runs "!forkdev version", and points to the code that forkb0t is currently looking at himself.

~/forkdev/
`-- plugins
    |-- _template
    |   |-- __init__.py
    |   |-- _template.conf
    |   `-- _template.py
    `-- calc
        |-- __init__.py
        |-- calc.conf
        |-- calc.py
        |-- current -> revisions/calc.0002
        `-- revisions
            |-- calc.0001
            |   |-- __init__.py
            |   |-- calc.conf
            |   `-- calc.py
            `-- calc.0002
                |-- __init__.py
                |-- calc.conf
                `-- calc.py

There are a total of 3 files that are present in the current plugin skeleton.

You will never need to edit this file. In fact, there is nothing in it! It is merely present because Python will refuse to load your code otherwise.

Here is where your main code is. forkb0t loads this file and looks at two functions. One is the help function, which is called when a user wants to know how to use your plugin. The other is the <foo> function, which contains the code you want to run.

When a user needs help with a function, forkb0t attempts to execute help(keyword) from your module. keyword will be a string with the specific trigger the user invoked.

def help(msgtext):
    return "Converts a set of earth coordinates into a zoneinfo time zone\nUSAGE: " + msgtext + " <latitude> <longitude>"

In the above example, if a user were to send the text "!coord2tz –help" to forkb0t, and "!coord2tz" was a registered keyword for this plugin, the resulting reply from forkb0t would be:

Converts a set of earth coordinates into a zoneinfo time zone
USAGE: !coord2tz <latitude> <longitude>

coming soon… for now, just read the comments in template

This file tells forkb0t how to run your plugin code. It is an "ini file" format, with all variables in one section named <foo>.

coming soon… for now, just study existing plugins

Since forkb0t is a live system on a remote server, debugging your code is a bit different than what you may be familiar with. Nevertheless, he has an assortment of functions to help you out. But first, one important reminder:

If you crash forkb0t, there is a bug in his core. Meaning, you should never have to worry about crashing him entirely. No need to cower in fear over potential problems in your plugins. Just go at it. In the rare event that he dies, it isn't your fault!

forkb0t will catch any unhandled exceptions in your code. When this happens, he will print a description of the problem and a short stack trace in his debug channel, #b0tcage on Freenode. The user will then get a message telling him something went wrong. This is the extent of debugging by default.

You can get an extensive report every time your plugin runs if you set the option "debug=True" in your plugin's .conf file. When enabled, an assortment of files in the "debug" directory for your plugin on the forkdev share are populated.