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: github.com/maiha/ircbot