tools/rubuildius/matzbot/README

   1 **********************
   2    Plugin API Howto
   3  (so we don't forget)
   4 **********************
   5
   6 Typical plugin:
   7
   8   module MatzBot::Commands
   9     needs_gem 'hpricot' => [ :tinyurl, :get_tinyurl ]
  10
  11     def tinyurl(data)
  12       say "Here it is! #{get_tinyurl(data.first)}"
  13     rescue
  14       say "No, no that's not gonna work."
  15     end
  16
  17   private
  18     def get_tinyurl(url)
  19       return if url.empty?
  20
  21       res = Net::HTTP.post_form(URI.parse('http://tinyurl.com/create.php'), { 'url' => url })
  22       doc = Hpricot(res.body)
  23       ((doc/:blockquote).last/:b).innerHTML
  24     end
  25   end
  26
  27 - New methods added to MatzBot::Commands show up as commands
  28
  29 - If you want to add methods which aren't bot commands, make them protected or private.
  30
  31 - Methods must accept one argument, an array of words said after the command.
  32
  33 - If you need to require a gem, use needs_gem like above.  Pass it the gem name and all
  34   the methods that depend on it.
  35
  36 - If you need to keep around data, use the `session' hash.
  37     session[:my_plugin] = true
  38     session[:my_plugin]
  39
  40 - You can use `reply' like say, except it will prefix your command with the user's name.
  41     <defunkt> hey bot
  42     <matzbot> defunkt: hey  # => using reply 'hey'
  43
  44 - You can use `pm' to send a private message to whoever made a request of you.  Use it like `say.'
  45
  46 - The above plugin would be triggered like this:
  47     <irc_dude> tinyurl http://myurl.com
  48     <matzbot> Here it is!  http://tinyurl.com/fz3
  49
  50 - You get these methods in the Commands API:
  51   - puts(string to say)
  52   - reply(string to say)
  53   - pm(sting to pm) [your bot must be ident'd on most networks for this to work]
  54   - action(string to emote)
  55   - config -- hash of runtime configuration options
  56   - socket -- direct access to the socket, if you need it
  57
  58 - Put plugins in ~/.matzbot and name them whatever.rb.
  59
  60 => Evan Weaver && Chris Wanstrath
  61 >> %w[ http://blog.evanweaver.com http://errtheblog.com ]