birdgrinder 0.1.0.0

data/bin/birdgrinder

@@ -0,0 +1,34 @@
+#!/usr/bin/env ruby
+require 'rubygems'
+require File.join(File.dirname(__FILE__), "..", "lib", "bird_grinder")
+
+BirdGrinder::Application.processing(ARGV) do |a|
+  
+  a.banner = "BirdGrinder v#{BirdGrinder.version}"
+
+  a.generator!
+
+  a.controller! :console, "Starts up a BirdGrinder friendly IRB instance"
+  a.controller! :client,  "Controls the current BirdGrinder instance"
+
+  a.option(:force, "force the creation of the application")
+  a.add("create PATH", "Creates a BirdGrinder instance at a specified location") do |path, options|
+    
+    path = File.expand_path(path)
+    if File.exists?(path) && !options[:force]
+      die! "The path you tried to use, #{path}, already exists. Please try another or use the --force option"
+    end
+    
+    setup_generator path
+    
+    folders 'tmp', 'config', 'handlers', 'test'
+    template 'boot.erb', 'config/boot.rb'
+    template 'setup.erb', 'config/setup.rb'
+    template 'settings.yml.erb', 'config/settings.yml'
+    template 'debug_handler.erb', 'handlers/debug_handler.rb'
+    template 'hello_world_handler.erb', 'handlers/hello_world_handler.rb'
+    template 'rakefile.erb', 'Rakefile'
+    
+  end
+
+end

data/examples/bird_grinder_client.rb

@@ -0,0 +1,45 @@
+require 'redis'
+require 'json' unless Hash.new.respond_to?(:to_json)
+
+# An example of using bird grinder with redis
+# to create a remote tweeting queue. In essence, it
+# lets you schedule up tweets to be sent by any
+# app on your system as a part of your birdgrinder
+# process, making it easier to do responses etc.
+class BirdGrinderClient
+  class Error < StandardError; end
+  
+  @@namespace = 'bg:messages'
+  
+  def self.namespace
+    @@namespace
+  end
+  
+  def self.namespace=(value)
+    @@namespace = value
+  end
+  
+  def initialize(*args)
+    begin
+      @redis = Redis.new(*args)
+    rescue Errno::ECONNREFUSED
+      raise Error, "Unable to connect to Redis"
+    end
+  end
+  
+  def dm(user, message)
+    send_action 'dm', [user, message]
+  end
+  
+  def tweet(message)
+    send_action 'tweet', [message]
+  end
+  
+  def send_action(name, args)
+    @redis.push_tail(@@namespace, {'action' => name.to_s, 'arguments' => args}.to_json)
+    return true
+  rescue Errno::ECONNREFUSED
+    raise Error, "Unable to connect to Redis to store message"
+  end
+  
+end

data/lib/bird_grinder/base.rb

@@ -0,0 +1,134 @@
+module BirdGrinder
+  # A generic base for building handlers. It makes
+  # it easy to implement the most common functionality (e.g.,
+  # clients, checking origin and the like) without
+  # having to reinvent the wheel. Typically used
+  # as a handler for Perennial::Dispatchable
+  #
+  # @see http://github.com/Sutto/perennial/blob/master/lib/perennial/dispatchable.rb
+  class Base
+    is :loggable
+    
+    cattr_accessor :handler_mapping
+    
+    @@handlers = Hash.new do |h,k|
+      h[k] = Hash.new { |h2,k2| h2[k2] = [] }
+    end
+    
+    class << self
+      
+      # Gets event handlers for a given event.
+      # @param [Symbol] name the name of the event
+      # @return [Array<Proc>] the resultant handlers
+      def event_handlers_for(name)
+        name = name.to_sym
+        handlers = []
+        klass = self
+        while klass != Object
+          handlers += @@handlers[klass][name]
+          klass = klass.superclass
+        end
+        return handlers
+      end
+      
+      # Appends a handler for the given event, either as a
+      # block / proc or as a symbol (for a method name) which
+      # will be called when the event is triggered.
+      #
+      # @param [Symbol] name the event name
+      # @param [Symbol] method_name if present, will call the given instance method
+      # @param [Proc] blk the block to call if method_name isn't given
+      def on_event(name, method_name = nil, &blk)
+        blk = proc { self.send(method_name) } if method_name.present?
+        @@handlers[self][name.to_sym] << blk
+      end
+      
+      # Registers the current handler instance to be used. If not
+      # registered, events wont be triggered
+      def register!
+        BirdGrinder::Client.register_handler(self.new)
+      end
+      
+    end
+    
+    attr_accessor :options, :client, :user
+    
+    # Handles a message / event from a dispatcher. This triggers
+    # each respective part of the client / lets us act on events.
+    #
+    # @param [Symbol] message the name of the event, e.g. :incoming_mention
+    # @param [Hash, BirdGrinder::Nash] options the options / params for the given event.
+    def handle(message, options)
+      begin
+        setup_details(message, options)
+        h = self.class.event_handlers_for(message)
+        h.each { |handle| self.instance_eval(&handle) }
+      rescue Exception => e
+        raise e if e.is_a?(BirdGrinder::HaltHandlerProcessing)
+        logger.fatal "Exception processing handlers for #{message}:"
+        logger.log_exception(e)
+      ensure
+        reset_details
+      end
+    end
+    
+    # Tweets a given message.
+    #
+    # @see BirdGrinder::Client#tweet
+    # @see BirdGrinder::Tweeter#tweet
+    def tweet(message, opts = {})
+      @client && @client.tweet(message, opts)
+    end
+    
+    # Direct Messages a specific user if the client exists.
+    #
+    # @see BirdGrinder::Client#dm
+    # @see BirdGrinder::Tweeter#dm
+    def dm(user, message, opts = {})
+      @client && @client.dm(user, message, opts)
+    end
+    
+    # Replies to the last received message in the correct format.
+    # if the last message direct, it will send a dm otherwise it
+    # will send a tweet with the correct @-prefix and :in_reply_to_status_id
+    # set correctly so twitter users can see what it is replying
+    # to.
+    #
+    # @param [String] message the message to reply with
+    # @see http://github.com/Sutto/perennial/blob/master/lib/perennial/dispatchable.rb
+    def reply(message)
+      message = message.to_s.strip
+      return if @user.blank? || @client.blank? || message.blank?
+      if @last_message_direct
+        @client.dm(@user, message)
+      else
+        opts = {}
+        opts[:in_reply_to_status_id] = @last_message_id.to_s if @last_message_id.present?
+        @client.reply(@user, message, opts)
+      end
+    end
+    
+    protected
+    
+    def reset_details
+      @direct_last_message = true
+      @last_message_origin = nil
+      @last_message_id     = nil
+      @options             = nil
+      @user                = nil
+    end
+    
+    def setup_details(message, options)
+      @options               = options.to_nash
+      @user                  = options.user.screen_name if options.user? && options.user.screen_name?
+      @user                ||= options.sender_screen_name if options.sender_screen_name?
+      @last_message_direct   = (message == :incoming_direct_message)
+      @last_message_id       = options.id
+    end
+    
+    def halt_handlers!
+      raise BirdGrinder::HaltHandlerProcessing
+    end
+    
+  end
+end

data/lib/bird_grinder/cacheable.rb

@@ -0,0 +1,66 @@
+require 'moneta'
+require 'moneta/memory'
+
+module BirdGrinder
+  
+  class << self
+    
+    # Gets the current cache store in use. Defaults
+    # to Moneta::Memory
+    #
+    # @see http://github.com/wycats/moneta
+    # @see Moneta::Redis
+    # @see Moneta::BasicFile
+    def cache_store
+      @@__cache_store__ ||= Moneta::Memory.new
+    end
+  
+    # Sets the cache store to a hash-like object.
+    #
+    # @param [Object] cs the cache store (must be hash-like with #[] and #[]=)
+    def cache_store=(cs)
+      @@__cache_store__ = cs
+    end
+  
+    alias use_cache cache_store=
+    
+  end
+  
+  module Cacheable
+    
+    # Gives the target class cache_set and cache_get
+    # on a class and instance level. triggered by:
+    #   include BirdGrinder::Cacheable
+    def self.included(parent)
+      parent.send(:include, Methods)
+      parent.send(:extend,  Methods)
+    end
+    
+    module Methods
+      
+      # Gets the value for the given key from the
+      # cache store if the cache store is set.
+      #
+      # @param [Symbol] key the key to get the value for
+      # @return [Object] the value for the given key
+      # @see BirdGrinder.cache_store
+      def cache_get(key)
+        cs = BirdGrinder.cache_store
+        cs && cs[key.to_s]
+      end
+      
+      # Attempts to set the value for a given key in the
+      # current cache_store.
+      #
+      # @param [Symbol] key the key to set the value for
+      # @param [Object] value the value for said key
+      # @see BirdGrinder.cache_store
+      def cache_set(key, value)
+        cs = BirdGrinder.cache_store
+        cs && cs[key.to_s] = value
+      end
+      
+    end
+    
+  end
+end

data/lib/bird_grinder/client.rb

@@ -0,0 +1,136 @@
+require 'ostruct'
+
+module BirdGrinder
+  # Glue between BirdGrinder::Tweeter and associated
+  # handlers to make it function in an evented fashion.
+  #
+  # The client basically brings it all together. It acts
+  # as a delegate for the tweeter and converts received
+  # results into dispatchable form for each handler.
+  #
+  # @see BirdGrinder::Tweeter
+  # @see BirdGrinder::Base
+  # @see http://github.com/Sutto/perennial/blob/master/lib/perennial/dispatchable.rb
+  class Client
+    is :loggable, :dispatchable, :cacheable
+    
+    cattr_accessor :current
+    attr_reader :tweeter
+    
+    # Initializes this client and creates a new, associated
+    # tweeter instance with this client set as the delegate.
+    # Also, for all of this clients handlers it will call
+    # client= if defined.
+    #
+    # Lastly, it updates BirdGrinder::Client.current to point
+    # to itself.
+    #
+    # @see BirdGrinder::Tweeter#initialize
+    # @see http://github.com/Sutto/perennial/blob/master/lib/perennial/dispatchable.rb
+    def initialize
+      logger.debug "Initializing client..."
+      @tweeter = BirdGrinder::Tweeter.new(self)
+      logger.debug "Notifying handlers of the client"
+      handlers.each { |h| h.client = self if h.respond_to?(:client=) }
+      self.current = self
+    end
+    
+    # Forwards a given message type (with options) to each handler,
+    # storing the current id if changed.
+    def receive_message(type, options = BirdGrinder::Nash.new)
+      logger.debug "receiving message: #{type.inspect} - #{options.id}"
+      dispatch(type.to_sym, options)
+      update_stored_id_for(type, options.id)
+    end
+    
+    # Fetches all direct messages and mentions and also schedules
+    # the next set of updates.
+    #
+    # @todo Schedule future fetch only when others are completed.
+    def update_all
+      fetch :direct_message, :mention
+      update_and_schedule_fetch
+    end
+    
+    # Searches for a given query
+    #
+    # @see BirdGrinder::Tweeter#search
+    def search(q, opts = {})
+      @tweeter.search(q, opts)
+    end
+    
+    # Tweets some text as the current user
+    #
+    # @see BirdGrinder::Tweeter#tweet
+    def tweet(text, opts = {})
+      @tweeter.tweet(text, opts)
+    end
+    
+    # Direct messages a given user with the given text
+    #
+    # @see BirdGrinder::Tweeter#dm
+    def dm(user, text, opts = {})
+      @tweeter.dm(user, text, opts)
+    end
+    
+    # Replies to a given user with the given text.
+    #
+    # @see BirdGrinder::Tweeter#reply
+    def reply(user, text, opts = {})
+      @tweeter.reply(user, text, opts)
+    end
+    
+    # Starts processing as a new client instance. The main
+    # entry point into the programs event loop.
+    # Once started, will invoke the once_running hook.    
+    def self.run
+      logger.info "Preparing to start BirdGrinder"
+      client = self.new
+      EventMachine.run do
+        client.update_all
+        BirdGrinder::Loader.invoke_hooks!(:once_running)
+      end
+    end
+    
+    # Stops the event loop so the program can be stopped.
+    def self.stop
+      EventMachine.stop_event_loop
+    end
+    
+    protected
+    
+    def update_and_schedule_fetch
+      @last_run_at ||= Time.now
+      next_run_time = @last_run_at + BirdGrinder::Settings.check_every
+      next_time_spacing = [0, (next_run_time - @last_run_at).to_i].max
+      @last_run_at = Time.now
+      EventMachine.add_timer(next_time_spacing) { update_all }
+    end
+    
+    def stored_id_for(type)
+      Integer(cache_get("#{type}-last-id"))
+    rescue ArgumentError
+      return -1
+    end
+    
+    def update_stored_id_for(type, id)
+      return if id.blank?
+      last_id = stored_id_for(type)
+      cache_set("#{type}-last-id", id) if last_id.blank? || id > last_id
+    end
+    
+    def fetch(*items)
+      items.each do |n|
+        fetch_latest :"#{n}s", :"incoming_#{n}"
+      end
+    end
+    
+    def fetch_latest(name, type)
+      options = {}
+      id = stored_id_for(type)
+      options[:since_id] = id unless id.blank?
+      @tweeter.send(name, options)
+    end
+    
+  end
+end

data/lib/bird_grinder/command_handler.rb

@@ -0,0 +1,84 @@
+require 'set'
+
+module BirdGrinder
+  # A simple, method to command mapping for handlers.
+  # E.g.
+  #
+  #   class X < BirdGrinder::CommandHandler
+  #     exposes :hello
+  #     def hello(name)
+  #       reply "Why hello there yourself!"
+  #     end
+  #   end
+  #
+  # When registerted, X will look for tweets that are of the form "@bot-name hello"
+  # or direct mentions with "hello" at the start (or if command_prefix is set to, 
+  # for example, !, "!hello") and reply.
+  #
+  # Used for implementing the most common cases of bots that respond to commands.
+  class CommandHandler < Base
+    
+    class_inheritable_accessor :exposed_methods, :command_prefix
+    self.command_prefix  = ""
+    self.exposed_methods = Set.new
+    
+    class << self
+      
+      # Marks a set of method names as being available
+      # @param [Array<Symbol>] args the method names to expose
+      def exposes(*args)
+        args.each { |name| exposed_methods << name.to_sym }
+      end
+      
+      # Gets a regexp for easy matching
+      # 
+      # @return [Regexp] BirdGrinder::CommandHandler.command_prefix in regexp-form
+      def prefix_regexp
+        /^#{command_prefix}/
+      end
+      
+    end
+    
+    # Default events
+    on_event :incoming_mention,        :check_for_commands
+    on_event :incoming_direct_message, :check_for_commands
+    
+    # Checks in incoming mentions and direct messages for those
+    # that correctly match the format. If it's found, it will
+    # call the given method with the result of the message,
+    # minus the command, as an argument.
+    def check_for_commands
+      data, command = nil, nil
+      if !@last_message_direct
+        logger.debug "Checking for command in mention"
+        split_message = options.text.split(" ", 3)
+        name, command, data = split_message
+        if name.downcase != "@#{BirdGrinder::Settings.username}".downcase
+          logger.debug "Command is a mention but doesn't start with the username"
+          return
+        end
+      else
+        logger.debug "Checking for command in direct message"
+        command, data = options.text.split(" ", 2)
+      end
+      if (command_name = extract_command_name(command)).present?
+        logger.info "Processing command '#{command_name}' for #{user}"
+        send(command_name, data.to_s) if respond_to?(command_name)
+      end
+    end
+    
+    # Given a prefix, e.g. "!awesome", will return the associated
+    # method name iff it is exposed.
+    #
+    # @param [String] the command to check
+    # @return [Symbol] the resultant method name or nil if not found.
+    def extract_command_name(command)
+      re = self.class.prefix_regexp
+      if command =~ re
+        method_name = command.gsub(re, "").underscore.to_sym
+        return method_name if exposed_methods.include?(method_name)
+      end
+    end
+    
+  end
+end