robut 0.2.0

data/.gitignore

@@ -0,0 +1,6 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+doc/*
+coverage/*

data/Gemfile

@@ -0,0 +1,17 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in robut.gemspec
+gemspec
+gem 'rake'
+
+group :test do
+  gem 'simplecov'
+end
+
+group :plugin do
+  gem 'calc'
+  gem 'twss'
+  gem 'rdio'
+  gem 'sinatra'
+  gem 'meme_generator'
+end

data/README.rdoc

@@ -0,0 +1,124 @@
+= Robut
+
+The friendly plugin-enabled HipChat bot. 
+
+== Installation and usage
+
+Robut can be installed by running <tt>gem install robut</tt>. This
+installs the +robut+ binary. When run, +robut+ reads a Chatfile,
+connects to the specified HipChat server and chatroom, and feeds every
+line said in the chatroom through the plugins configured by the
+Chatfile.
+
+Once robut is running, the plugins listen to what's being said in the
+chatroom. Most plugins listen for @replies to robut:
+
+  @robut lunch? # => "Banh Mi!"
+  @robut calc 1 + 1 # => 2
+
+Others listen to everything, and don't require an @reply.
+
+Some of the included plugins require extra gems to be installed:
+
+[Robut::Plugin::TWSS] requires the <tt>twss</tt> gem
+[Robut::Plugin::Meme] requires the <tt>meme_generator</tt> gem
+[Robut::Plugin::Calc] requires the <tt>calc</tt> gem
+[Robut::Plugin::Rdio] requires the <tt>rdio</tt> and <tt>sinatra</tt> gems
+
+== The Chatfile
+
+When the +robut+ command runs, it looks for and evals ruby code in a
+file called +Chatfile+ in the current directory. You can override the
+configuration file by passing +robut+ a path to a Chatfile as the
+first parameter:
+
+  robut /path/to/Chatfile
+
+The Chatfile is just ruby code. A simple example can be found here: Chatfile[https://github.com/justinweiss/robut/blob/master/examples/Chatfile]
+
+=== Adding and configuring plugins
+
+Plugins are ruby classes, so enabling a plugin just requires requiring
+the plugin file, optionally configuring the plugin class, and adding
+the class to the global plugin list:
+
+  require 'robut/plugin/lunch'
+  Robut::Plugin::Lunch.places = ["Banh Mi", "Mad Oven", "Mod Pizza", "Taphouse"]
+  Robut::Plugin.plugins << Robut::Plugin::Lunch
+
+Each plugin can be configured differently, or not at all. It's best to
+look at the docs for the plugins you want to use to figure out what
+kind of configuration they support.
+
+Some plugins might require storage (like the `lunch` plugin).  You can
+configure the type of storage you want to use based on the need for
+persistence.  The default is the HashStore which is in-memory only.  Below
+is an example of using the YamlStore.  
+
+  Robut::Connection.configure do |config|
+    # ...
+    Robut::Storage::YamlStore.file = "~/.robut_store"
+    config.store = Robut::Storage::YamlStore
+  end
+
+
+=== Configuring the HipChat connection
+
+The Chatfile also configures the HipChat connection. This is done in a
+Robut::Connection.configure block:
+
+  # Configure the robut jabber connection and you're good to go!
+  Robut::Connection.configure do |config|
+    config.jid = '...@chat.hipchat.com/bot'
+    config.password = 'password'
+    config.nick = 'My Nick'
+    config.room = '...@conf.hipchat.com'
+    
+    # Example of the YamlStore which uses a yaml file for persistence
+    Robut::Storage::YamlStore.file = "~/.robut_store"
+    config.store = Robut::Storage::YamlStore
+    
+    # Add a logger if you want to debug the connection
+    # config.logger = Logger.new(STDOUT)
+  end
+
+This block usually goes at the end of the Chatfile.
+
+== Built-in plugins
+
+Robut includes a few plugins that we've found useful:
+
+[Robut::Plugin::Calc] a simple calculator. <br /> <br /> Example: <tt>@robut calc 1 + 1 # => 2</tt>
+[Robut::Plugin::Lunch] a random decider for lunch locations. <br /> <br /> Example: <tt>@robut lunch? # => "Banh Mi!"</tt>
+[Robut::Plugin::Meme] an interface to memegenerator.net. <br /> <br /> Example: <tt>@robut meme Y_U_NO FIX THE BUILD?</tt>
+[Robut::Plugin::Sayings] a simple regex listener and responder. <br /> <br /> Example: <tt>You're the worst robot ever, @robut. # => I know. </tt>
+[Robut::Plugin::TWSS] an interface to the TWSS gem. Listens to anything said in the chat room and responds "That's what she said!" where appropriate. <br /> <br /> Example: <tt>well hurry up, you're not going fast enough # => "That's what she said!" </tt>
+[Robut::Plugin::Echo] echo back whatever it gets. <br /> <br /> Example: <tt>@robut echo hello word</tt>
+[Robut::Plugin::Say] invokes the "say" command (text-to-speech). <br /> <br /> Example: <tt>@robut say this rocks</tt>
+[Robut::Plugin::Ping] responds with "pong". <br /> <br /> Example: <tt>@robut ping</tt>
+[Robut::Plugin::Later] performs the given command after waiting an arbitrary amount of time. <br /> <br /> Example: <tt>@robut in 5 minutes echo @justin wake up!</tt>
+[Robut::Plugin::Rdio] uses the Rdio[http://www.rdio.com] API and a simple web server to queue and play songs on Rdio. <br /> <br /> Example: <tt>@robut play ok computer</tt>
+
+== Writing custom plugins
+
+You can supply your own plugins to Robut. To create a plugin, subclass
+Robut::Plugin::Base and implement the <tt>handle(time, sender_nick,
+message)</tt> to perform any plugin-specific logic.
+
+Robut::Plugin::Base provides a few helper methods that are documented
+in its class definition.
+
+== Contributing
+
+Once you've made your great commits:
+
+1. Fork robut
+2. Create a topic branch - git checkout -b my_branch
+3. Push to your branch - git push origin my_branch
+4. Send me a pull request
+5. That's it!
+
+== Todo
+
+* Support connections to multiple rooms
+* More plugins!

data/Rakefile

@@ -0,0 +1,27 @@
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+task :default => :test
+task :build => :test
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+end
+
+Rake::TestTask.new(:coverage) do |t|
+  t.libs << "test"
+  t.ruby_opts = ["-rsimplecov_helper"]
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+end
+
+Rake::RDocTask.new do |rd|
+  rd.main = "README.rdoc"
+  rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+  rd.rdoc_dir = 'doc'
+end
+

data/bin/robut

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+require 'rubygems'
+require 'robut'
+require 'ostruct'
+require 'logger'
+
+load ARGV[0] || './Chatfile'
+
+Robut::Connection.new.connect

data/examples/Chatfile

@@ -0,0 +1,22 @@
+# Require your plugins here
+require 'robut/plugin/twss'
+require 'robut/storage/yaml_store'
+
+# Add the plugin classes to the Robut plugin list.
+# Plugins are handled in the order that they appear in this array.
+Robut::Plugin.plugins << Robut::Plugin::TWSS
+
+# Configure the robut jabber connection and you're good to go!
+Robut::Connection.configure do |config|
+  config.jid = '...@chat.hipchat.com/bot'
+  config.password = 'password'
+  config.nick = 'My Nick'
+  config.room = '...@conf.hipchat.com'
+  
+  # Some plugins require storage
+  Robut::Storage::YamlStore.file = ".robut"
+  config.store = Robut::Storage::YamlStore
+  
+  # Add a logger if you want to debug the connection
+  # config.logger = Logger.new(STDOUT)
+end

data/lib/robut.rb

@@ -0,0 +1,5 @@
+module Robut
+  autoload :Plugin, 'robut/plugin'
+  autoload :Connection, 'robut/connection'
+  autoload :Storage, 'robut/storage'
+end

data/lib/robut/connection.rb

@@ -0,0 +1,167 @@
+require 'xmpp4r'
+require 'xmpp4r/muc/helper/simplemucclient'
+require 'xmpp4r/roster/helper/roster'
+require 'ostruct'
+
+# Handles opening a connection to the HipChat server, and feeds all
+# messages through our Robut::Plugin list.
+class Robut::Connection
+  
+  # The configuration used by the Robut connection.
+  #
+  # Parameters:
+  #
+  # [+jid+, +password+, +nick+] The HipChat credentials given on
+  #                             https://www.hipchat.com/account/xmpp
+  #
+  # [+room+] The chat room to join, in the format <tt>jabber_name</tt>@<tt>conference_server</tt>
+  #
+  # [+logger+] a logger instance to use for debug output.
+  attr_accessor :config
+
+  # The Jabber::Client that's connected to the HipChat server.
+  attr_accessor :client
+
+  # The MUC that wraps the Jabber Chat protocol.
+  attr_accessor :muc
+
+  # The storage instance that's available to plugins
+  attr_accessor :store
+
+  # The roster of currently available people
+  attr_accessor :roster
+
+  class << self
+    # Class-level config. This is set by the +configure+ class method,
+    # and is used if no configuration is passed to the +initialize+
+    # method.
+    attr_accessor :config
+  end
+
+  # Configures the connection at the class level. When the +robut+ bin
+  # file is loaded, it evals the file referenced by the first
+  # command-line parameter. This file can configure the connection
+  # instance later created by +robut+ by setting parameters in the
+  # Robut::Connection.configure block.
+  def self.configure
+    self.config = OpenStruct.new
+    yield config
+  end
+
+  # Sets the instance config to +config+, converting it into an
+  # OpenStruct if necessary.
+  def config=(config)
+    @config = config.kind_of?(Hash) ? OpenStruct.new(config) : config
+  end
+  
+  # Initializes the connection. If no +config+ is passed, it defaults
+  # to the class_level +config+ instance variable.
+  def initialize(_config = nil)
+    self.config = _config || self.class.config
+    
+    self.client = Jabber::Client.new(self.config.jid)
+    self.muc = Jabber::MUC::SimpleMUCClient.new(client)
+    self.store = self.config.store || Robut::Storage::HashStore # default to in-memory store only
+
+    if self.config.logger
+      Jabber.logger = self.config.logger
+      Jabber.debug = true
+    end
+  end
+  
+  # Send +message+ to the room we're currently connected to, or
+  # directly to the person referenced by +to+. +to+ can be either a
+  # jid or the string name of the person.
+  def reply(message, to = nil)
+    if to
+      unless to.kind_of?(Jabber::JID)
+        to = find_jid_by_name(to)
+      end
+      
+      msg = Jabber::Message.new(to || muc.room, message)
+      msg.type = :chat
+      client.send(msg)
+    else
+      muc.send(Jabber::Message.new(muc.room, message))
+    end
+  end
+
+  # Sends the chat message +message+ through +plugins+. 
+  def handle_message(plugins, time, nick, message)
+    plugins.each do |plugin|
+      begin
+        rsp = plugin.handle(time, nick, message)
+        break if rsp == true
+      rescue => e
+        reply("I just pooped myself trying to run #{plugin.class.name}. AWK-WAAAARD!")
+        if config.logger
+          config.logger.error e
+          config.logger.error e.backtrace.join("\n")
+        end
+      end
+    end
+  end
+
+  # Connects to the specified room with the given credentials, and
+  # enters an infinite loop. Any messages sent to the room will pass
+  # through all the included plugins.
+  def connect
+    client.connect
+    client.auth(config.password)
+    client.send(Jabber::Presence.new.set_type(:available))
+
+    self.roster = Jabber::Roster::Helper.new(client)
+    roster.wait_for_roster
+
+    # Add the callback from messages that occur inside the room
+    muc.on_message do |time, nick, message|
+      plugins = Robut::Plugin.plugins.map { |p| p.new(self, nil) }
+      handle_message(plugins, time, nick, message)
+    end
+
+    # Add the callback from direct messages. Turns out the
+    # on_private_message callback doesn't do what it sounds like, so I
+    # have to go a little deeper into xmpp4r to get this working.
+    client.add_message_callback(200, self) { |message|
+      if !muc.from_room?(message.from) && message.type == :chat && message.body
+        time = Time.now # TODO: get real timestamp? Doesn't seem like
+                        # jabber gives it to us
+        sender_jid = message.from
+        plugins = Robut::Plugin.plugins.map { |p| p.new(self, sender_jid) }
+        handle_message(plugins, time, self.roster[sender_jid].iname, message.body)
+        true
+      else
+        false
+      end
+    }
+        
+    muc.join(config.room + '/' + config.nick)
+
+    trap_signals
+    loop { sleep 1 }
+  end
+
+  private
+  
+  # Since we're entering an infinite loop, we have to trap TERM and
+  # INT. If something like the Rdio plugin has started a server that
+  # has already trapped those signals, we want to run those signal
+  # handlers first.
+  def trap_signals
+    old_signal_callbacks = {}
+    signal_callback = Proc.new do |signal|
+      old_signal_callbacks[signal].call if old_signal_callbacks[signal]
+      exit
+    end
+    
+    [:INT, :TERM].each do |sig|
+      old_signal_callbacks[sig] = trap(sig) { signal_callback.call(sig) }
+    end
+  end
+
+  # Find a jid in the roster with the given name, case-insensitively
+  def find_jid_by_name(name)
+    name = name.downcase
+    roster.items.detect {|jid, item| item.iname.downcase == name}.first
+  end
+end

data/lib/robut/plugin.rb

@@ -0,0 +1,16 @@
+# Robut plugins implement a simple interface to listen for messages
+# and optionally respond to them. All plugins inherit from
+# Robut::Plugin::Base.
+module Robut::Plugin
+  autoload :Base, 'robut/plugin/base'
+
+  class << self
+    # A list of all available plugin classes. When you require a new
+    # plugin class, you should add it to this list if you want it to
+    # respond to messages.
+    attr_accessor :plugins
+  end
+
+  self.plugins = []
+
+end

data/lib/robut/plugin/base.rb

@@ -0,0 +1,70 @@
+# All Robut plugins inherit from this base class. Plugins should
+# implement the +handle+ method to implement their functionality.
+class Robut::Plugin::Base
+
+  # A reference to the connection attached to this instance of the
+  # plugin. This is mostly used to communicate back to the server.
+  attr_accessor :connection
+
+  # If we are handling a private message, holds a reference to the
+  # sender of the message. +nil+ if the message was sent to the entire
+  # room.
+  attr_accessor :private_sender
+
+  # Creates a new instance of this plugin that references the
+  # specified connection.
+  def initialize(connection, private_sender = nil)
+    self.connection = connection
+    self.private_sender = private_sender
+  end
+
+  # Send +message+ back to the HipChat server. If +to+ == +:room+,
+  # replies to the room. If +to+ == nil, responds in the manner the
+  # original message was sent. Otherwise, PMs the message to +to+.
+  def reply(message, to = nil)
+    if to == :room
+      connection.reply(message, nil)
+    else
+      connection.reply(message, to || private_sender)
+    end
+  end
+
+  # An ordered list of all words in the message with any reference to
+  # the bot's nick stripped out. If +command+ is passed in, it is also
+  # stripped out. This is useful to separate the 'parameters' from the
+  # 'commands' in a message.
+  def words(message, command = nil)
+    reply = at_nick
+    command = command.downcase if command
+    message.split.reject {|word| word.downcase == reply || word.downcase == command }
+  end
+
+  # The bot's nickname, for @-replies.
+  def nick
+    connection.config.nick.split.first
+  end
+
+  # #nick with the @-symbol prepended
+  def at_nick
+    "@#{nick.downcase}"
+  end
+
+  # Was +message+ sent to Robut as an @reply?
+  def sent_to_me?(message)
+    message =~ /(^|\s)@#{nick}(\s|$)/i
+  end
+
+  # Do whatever you need to do to handle this message.
+  # If you want to stop the plugin execution chain, return +true+ from this
+  # method.  Plugins are handled in the order that they appear in
+  # Robut::Plugin.plugins
+  def handle(time, sender_nick, message)
+    raise NotImplementedError, "Implement me in #{self.class.name}!"
+  end
+  
+  # Accessor for the store instance
+  def store
+    connection.store
+  end
+  
+end