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"
        # or simply use "done(text)" method
      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