ircbot

An irc bot framework that offers easy-to-use by plugins

Config

Edit "config/xxx.yml" as your environment.

* host: irc server host
* port: irc server port
* nick: nick name for this bot
* user: user name for this bot
* real: real name for this bot
* help: help message for this bot
* channels: startup channel names
* plugins: plugin names
* timeout: bot will exit when no new pings come for this sec

Usage

(installed gem)
% ircbot -f config/xxx.yml

(in source dir)
% ruby -Ku -rubygems -Ilib bin/ircbot -f config/xxx.yml

Plugin

In ircbot world, we define functions as plugin (Ircbot::Plugin).

Instance methods:
* reply : this method is called when privmsg event is fired,
          and reply message(the returned string) to the channel.
          args: [text, nick, message object]
* setup : used for initializer
* help  : used from "plugins" plugin
* [ANY] : any methods can be invoked by "<NICK>.<PLUGN_NAME>.<METHOD_NAME>"

Accessor methods:

* message : message object same as 3rd argument
* direct? : whether the message is directly toward to the bot or not
* config  : hash of given config file

Setup

Install gems via bundler like this.

% bundle install --path vendor

Example

When you want echo bot, define the function as plugin first.

plugins/echo.rb:

class EchoPlugin < Ircbot::Plugin
  def reply(text)
    text
  end
end

Advanced

Messages are passed into plugins automatically.
If you don't want this plugin chain, throw :done will help you.  

config:
  plugins: a b

class APlugin < Ircbot::Plugin
  def reply(text)
    throw :done, "This is A"
  end
end

class BPlugin < Ircbot::Plugin
  def reply(text)
    "This is B"
  end
end

BPlugin#reply will be never invoked.

Daemons

Plugin initializer automatically calls "setup" method.
So you can start daemon in it.

plugins/time_signal.rb:

class TimeSignalPlugin < Ircbot::Plugin
  def setup
    @daemon = Thread.new {
      sleep 60
      self.bot.broadcast Time.now
    }
  end

  def stop
    @daemon.kill
    return "Stopped time signal"
  end
end

When the bot name is 'airi', this will act as following.

05:11 <airi> Mon Apr 09 05:11:22 +0900 2012
05:12 <airi> Mon Apr 09 05:12:22 +0900 2012
05:12 <maiha> airi.time_signal.stop
05:12 <airi> Stopped time signal

PluginAttributes

When you want to give options or attributes to plugins,
write it into config.plugins as Array(Hash)

config/xxx.yml
plugins:
  - irc
  -
    name: watchdog
    db: "postgres://localhost/ircbot"

This will generate two plugins
1. Ircbot::Plugin(name:irc)
2. Ircbot::Plugin(name:watchdog, attrs=>{name=>watchdog,db=>postgres...})

And the given options can be found in plugin by [] method.

class Watchdog < Ircbot::Plugin
  def setup
    db = self[:db]
    puts "connecting to #{db}"
    ...

Required

• irc-net gem

Authors: maiha@wota.jp Links: http://github.com/maiha/ircbot