Overview

Erkbot

Erkbot is a simple irc bot, written in erlang. The project is a fork of John Begeman's erlang-ircbot project. Its goal is to provide a simple to configure, easy to use, extensible irc bot. It's heavily influenced by the OpenACD project, as well as the precursors-server project.

Status

Currently, I'd consider it 'beta' quality, with the external API being 'alpha' at best. This should change soon.

Design

Erkbot is designed with simplicity in mind. It handles the raw irc semmantics, allow its plugins to simply respond to events in order to handle commands. Implementing a new plugin is as simple as writing an erlang application that implements the plugin interface.

Plugins

Note: Currently, the intention is for plugins to be their own applications. That support isn't done yet, but should be finished shortly.

A plugin is any module that implements the following four functions:

handle_event(Msg, Pid) ->
    ok.


handle_command(Msg, Pid) ->
    ok.


handle_parsed(Msg, Pid) ->
    ok.


handle_raw(Msg, Pid) ->
    ok.

That's all there is to it. Erkbot doesn't care if it's a gen_server, runs in its own pid, or anything else; all that is needs is to implement those four functions. Granted, you will probably want to at least run it in a pid, if not make it a full fledged gen_server. But, the choice is entirely yours, to fit your situation.

Building a plugin

While those four interface functions are pretty self explanitory, there's a couple details you may want to know, as well as a couple resources to make your life easier. First and foremost, you will probably want to import the erkbot_event.hrl file. This file defines the record being sent as Msg to all the itnerface functions, as well as defining server_info, a record that gets passed as args on a connected event, to the handle_event function.

You are not required to use this file; it's simply available for your use. Should the plugin interface ever change, this file will be changed as well, since it's used internally in the event dispatching code.

Here's a rundown of each of the interface functions:

  • handle_event - This function handles irc events, such as server connected, channel joined, etc. (More documentation on events will be available later.)
  • handle_command - This function is called whenever ErkBot successfully parses a message as a command. This means it found a ! or a # as the first character in the message, and that the message was an PRIVMSG type. (This means it was said by a user in either a channel, or a private chat.)
  • handle_parsed - This function is called when ErkBot was able to parse the message, but it wasn't an event or a command. For most plugins, you will have a simple return here, and ignore these messages. However, if you wanted to support commands in the middle of messages, or responding to the bot's nick, etc, you would need to do your parsing in response to this message.
  • handle_raw - This function is a catch-all for messages not handled by the other messages. This rarely happens, and is only available, for the rare case a plugin needs to handle something special. Most plugins will ignore this.

Registering a plugin

Plugins are registered with the erkbot_event module. Simple call add_plugin with the module and pid:

erkbot_event:add_plugin(?MODULE, self()).

Controling the bot

Plugins are allowed full control over Erkbot; all you need to do is call the appropriate function in the erkbot_server module. This includes say.

License

This code is all MIT licensed.