twibot 0.1.0

data/History.txt

@@ -0,0 +1,4 @@
+== 1.0.0 / 2009-03-04
+
+* 1 major enhancement
+  * Birthday!

data/Rakefile

@@ -0,0 +1,30 @@
+# Look in the tasks/setup.rb file for the various options that can be
+# configured in this Rakefile. The .rake files in the tasks directory
+# are where the options are used.
+
+begin
+  require 'bones'
+  Bones.setup
+rescue LoadError
+  begin
+    load 'tasks/setup.rb'
+  rescue LoadError
+    raise RuntimeError, '### please install the "bones" gem ###'
+  end
+end
+
+ensure_in_path 'lib'
+require 'twibot'
+
+task :default => 'test:run'
+
+PROJ.name = 'twibot'
+PROJ.authors = 'Christian Johansen'
+PROJ.email = 'christian@cjohansen.no'
+PROJ.url = 'http://github.com/cjohansen/twibot/'
+PROJ.version = Twibot::VERSION
+PROJ.rubyforge.name = 'twibot'
+PROJ.readme_file = 'Readme.rdoc'
+PROJ.rdoc.remote_dir = 'twibot'
+
+depend_on "twitter4r", "0.3.1"

data/Readme.rdoc

@@ -0,0 +1,158 @@
+=Twibot
+Official URL: http://github.com/cjohansen/twibot/tree/master
+Christian Johansen (http://www.cjohansen.no)
+
+== DESCRIPTION
+
+Twibot (pronounced like "Abbot"), is a Ruby microframework for creating Twitter
+bots, heavily inspired by Sinatra.
+
+== USAGE
+
+=== Simple example
+
+  require 'twibot'
+
+  # Receive messages, and tweet them publicly
+  #
+  message do |message, params|
+    post_tweet message
+  end
+
+  # Respond to @replies if they come from the right crowd
+  #
+  reply :from => [:cjno, :irbno] do |message, params|
+    post_tweet "@#{message.sender.screen_name} I agree"
+  end
+
+  # Listen in and log tweets
+  #
+  tweet do |message, params|
+    MyApp.log_tweet(message)
+  end
+
+=== Running the bot
+
+To run the bot, simply do:
+
+  ruby bot.rb
+
+=== Configuration
+
+Twibot looks for a configuration file in ./config/bot.yml. It should contain
+atleast:
+
+  login: twitter_login
+  password: twitter_password
+
+You can also pass configuration as command line arguments:
+
+  ruby bot.rb --login myaccount
+
+...or configure with Ruby:
+
+  configure do |conf|
+    conf.login = "my_account"
+  do
+
+If you don't specify login and/or password in any of these ways, Twibot will
+prompt you for those.
+
+If you want to change how Twibot is configured, you can setup the bot instance
+manually and give it only the configuration options you want:
+
+  # Create bot only with default configuration
+  require 'twibot'
+  bot = Twibot::Bot.new(Twibot::Config.default)
+
+  # Application here...
+
+If you want command line arguments you can do:
+
+  require 'twibot'
+  bot = Twibot::Bot.new(Twibot::Config.default << Twibot::CliConfig.new)
+
+=== "Routes"
+
+Like Sinatra, and other web app frameworks, Twibot supports "routes": patterns
+to match incoming tweets and messages:
+
+  require 'twibot'
+
+  tweet "time :country :city" do |message,params|
+    time = MyTimeService.lookup(params[:country], params[:city])
+    client.message :post, "Time is #{time} in #{params[:city]}, #{params[:country]}"
+  end
+
+You can have several "tweet" blocks (or "message" or "reply"). The first one to
+match an incoming tweet/message will handle it.
+
+=== Working with the Twitter API
+
+The DSL gives you access to your Twitter client instance through "client" (or "twitter"):
+
+  message do
+    twitter.status :post, "Hello world" # Also: client.status :post, "Hello world"
+  end
+
+== REQUIREMENTS
+
+Twitter4r. You'll need atleast 0.3.1, which is currently only available from GitHub.
+Versions of Twitter4r prior to 0.3.1 does not allow for the since_id parameter to be
+appended to URLs to the REST API. Twibot needs these to only fetch fresh messages
+and tweets.
+
+== INSTALLATION
+
+gem install twibot
+
+== Is it Ruby 1.9?
+
+Unfortunately no. Context, used for Twibots tests is not Ruby 1.9 compliant, which
+makes it hard to figure out which part is causing trouble. Will be fixed soon. Fork
+away if you want to help out!
+
+== Polling
+
+Twitter pulled the plug on it's xmpp service last year. This means that Twibot backed
+bots needs to poll the Twitter service to keep up. Twitter has a request limit on 70
+reqs/hour, so you should configure your bot not to make more than that, else it will
+fail. You can ask for your bot account to be put on the whitelist which allows you to
+make 20.000 reqs/hour, and shouldn't be a problem so long as your intentions are good
+(I think).
+
+Twibot polls like this:
+  * Poll messages if any message handlers exist
+  * Poll tweets if any tweet or reply handlers exist
+  * Sleep for +interval+ seconds
+  * Go over again
+
+As long as Twibot finds any messages and/or tweets, the interval stays the same
+(min_interval configuration switch). If nothing was found however, the interval to
+sleep is increased by interval_step configuration option. This happens until it
+reaches max_interval, where it will stay until Twibot finds anything.
+
+== LICENSE
+
+(The MIT License)
+
+Copyright (c) 2009 Christian Johansen
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/lib/hash.rb

@@ -0,0 +1,8 @@
+class Hash
+  def symbolize_keys!
+    replace(inject({}) do |hash,(key,value)|
+      hash[key.to_sym] = value.is_a?(Hash) ? value.symbolize_keys! : value
+      hash
+    end)
+  end
+end

data/lib/twibot/bot.rb

@@ -0,0 +1,201 @@
+require 'logger'
+require File.join(File.expand_path(File.dirname(__FILE__)), 'macros')
+require File.join(File.expand_path(File.dirname(__FILE__)), 'handlers')
+
+module Twibot
+  #
+  # Main bot "controller" class
+  #
+  class Bot
+    include Twibot::Handlers
+    attr_reader :twitter
+    attr_writer :prompt
+
+    def initialize(options = nil, prompt = false)
+      @prompt = prompt
+      @conf = nil
+      @config = options || Twibot::Config.default << Twibot::FileConfig.new << Twibot::CliConfig.new
+      @twitter = Twitter::Client.new :login => config[:login], :password => config[:password]
+      @log = nil
+      @abort = false
+
+      @processed = {
+        :message => nil,
+        :reply => nil,
+        :tweet => nil
+      }
+    rescue Exception => krash
+      raise SystemExit.new krash.message
+    end
+
+    def prompt?
+      @prompt
+    end
+
+    #
+    # Run application
+    #
+    def run!
+      puts "Twibot #{Twibot::VERSION} imposing as @#{login}"
+
+      trap(:INT) do
+        puts "\nAnd it's a wrap. See ya soon!"
+        exit
+      end
+
+      # Make sure we don't process messages and tweets received prior to bot launch
+      messages = @twitter.messages(:received, { :count => 1 })
+      @processed[:message] = messages.first.id if messages.length > 0
+
+      handle_tweets = @handlers[:tweet].length + @handlers[:reply].length > 0
+      tweets = handle_tweets ? @twitter.timeline_for(:me, { :count => 1 }) : []
+      @processed[:tweet] = tweets.first.id if tweets.length > 0
+      @processed[:reply] = tweets.first.id if tweets.length > 0
+
+      poll
+    end
+
+    #
+    # Poll Twitter API in a loop and pass on messages and tweets when they appear
+    #
+    def poll
+      max = max_interval
+      step = interval_step
+      interval = min_interval
+
+      while !@abort do
+        message_count = 0
+        message_count += receive_messages || 0
+        message_count += receive_replies || 0
+        message_count += receive_tweets || 0
+
+        interval = message_count > 0 ? min_interval : [interval + step, max].min
+
+        log.debug "Sleeping for #{interval}s"
+        sleep interval
+      end
+    end
+
+    #
+    # Receive direct messages
+    #
+    def receive_messages
+      type = :message
+      return false unless handlers[type].length > 0
+
+      options = { :since_id => @processed[type] } if @processed[type]
+      dispatch_messages(type, @twitter.messages(:received, options), %w{message messages})
+    end
+
+    #
+    # Receive tweets
+    #
+    def receive_tweets
+      type = :tweet
+      return false unless handlers[type].length > 0
+
+      options = { :id => @processed[type] } if @processed[type]
+      dispatch_messages(type, @twitter.timeline_for(:me, options), %w{tweet tweets})
+    end
+
+    #
+    # Receive tweets that start with @<login>
+    #
+    def receive_replies
+      type = :reply
+      return false unless handlers[type].length > 0
+
+      options = { :id => @processed[type] } if @processed[type]
+      messages = @twitter.timeline_for(:me, options)
+
+      # Pick only messages that start with our name
+      num = dispatch_messages(type, messages.find_all { |t| t.text =~ /^@#{@twitter.send :login}/ }, %w{reply replies})
+
+      # Avoid picking up messages over again
+      @processed[type] = messages.first.id if messages.length > 0
+      num
+    end
+
+    #
+    # Dispatch a collection of messages
+    #
+    def dispatch_messages(type, messages, labels)
+      messages.each { |message| dispatch(type, message) }
+      @processed[type] = messages.first.id if messages.length > 0
+
+      num = messages.length
+      log.info "Received #{num} #{num == 1 ? labels[0] : labels[1]}"
+      num
+    end
+
+    #
+    # Return logger instance
+    #
+    def log
+      return @log if @log
+      os = config[:log_file] ? File.open(config[:log_file], "a") : $stdout
+      @log = Logger.new(os)
+      @log.level = Logger.const_get(config[:log_level] ? config[:log_level].upcase : "INFO")
+      @log
+    end
+
+    #
+    # Configure bot
+    #
+    def configure
+      yield @config
+      @conf = nil
+    end
+
+   private
+    #
+    # Map configuration settings
+    #
+    def method_missing(name, *args, &block)
+      return super unless config.key?(name)
+
+      self.class.send(:define_method, name) { config[name] }
+      config[name]
+    end
+
+    #
+    # Return configuration
+    #
+    def config
+      return @conf if @conf
+      @conf = @config.to_hash
+
+      if prompt? && (!@conf[:login] || !@conf[:password])
+        # No need to rescue LoadError - if the gem is missing then config will
+        # be incomplete, something which will be detected elsewhere
+        begin
+          require 'highline'
+          hl = HighLine.new
+
+          @config.login = hl.ask("Twitter login: ") unless @conf[:login]
+          @config.password = hl.ask("Twitter password: ") { |q| q.echo = '*' } unless @conf[:password]
+          @conf = @config.to_hash
+        rescue LoadError
+          raise SystemExit.new <<-HELP
+Unable to continue without login and password. Do one of the following:
+  1) Install the HighLine gem (gem install highline) to be prompted for credentials
+  2) Create a config/bot.yml with login: and password:
+  3) Put a configure { |conf| conf.login = "..." } block in your bot application
+  4) Run bot with --login and --password options
+          HELP
+        end
+      end
+
+      @conf
+    end
+  end
+end
+
+# Expose DSL
+include Twibot::Macros
+
+# Run bot if macros has been used
+at_exit do
+  raise $! if $!
+  @@bot.run! if run?
+end

data/lib/twibot/config.rb

@@ -0,0 +1,136 @@
+require 'optparse'
+
+module Twibot
+  #
+  # Twibot configuration. Use either Twibot::CliConfig.new or
+  # TwibotFileConfig.new setup a new bot from either command line or file
+  # (respectively). Configurations can be chained so they override each other:
+  #
+  #   config = Twibot::FileConfig.new
+  #   config << Twibot::CliConfig.new
+  #   config.to_hash
+  #
+  # The preceding example will create a configuration which is based on a
+  # configuration file but have certain values overridden from the command line.
+  # This can be used for instance to store everything but the Twitter account
+  # password in your configuration file. Then you can just provide the password
+  # when running the bot.
+  #
+  class Config
+    attr_reader :settings
+
+    DEFAULT = {
+      :min_interval => 30,
+      :max_interval => 300,
+      :interval_step => 10,
+      :log_level => "info",
+      :log_file => nil,
+      :login => nil,
+      :password => nil,
+      :prompt => false,
+      :daemonize => false
+    }
+
+    def initialize(settings = {})
+      @configs = []
+      @settings = settings
+    end
+
+    #
+    # Add a configuration object to override given settings
+    #
+    def add(config)
+      @configs << config
+      self
+    end
+
+    alias_method :<<, :add
+
+    #
+    # Makes it possible to access configuration settings as attributes
+    #
+    def method_missing(name, *args, &block)
+      regex = /=$/
+      attr_name = name.to_s.sub(regex, '').to_sym
+      return super if name == attr_name && !@settings.key?(attr_name)
+
+      if name != attr_name
+        @settings[attr_name] = args.first
+      end
+
+      @settings[attr_name]
+    end
+
+    #
+    # Merges configurations and returns a hash with all options
+    #
+    def to_hash
+      hash = {}.merge(@settings)
+      @configs.each { |conf| hash.merge!(conf.to_hash) }
+      hash
+    end
+
+    def self.default
+      Config.new({}.merge(DEFAULT))
+    end
+  end
+
+  #
+  # Configuration from command line
+  #
+  class CliConfig < Config
+
+    def initialize(args = $*)
+      super()
+
+      @parser = OptionParser.new do |opts|
+        opts.banner += "Usage: #{File.basename(Twibot.app_file)} [options]"
+
+        opts.on("-m", "--min-interval SECS", Integer, "Minimum poll interval in seconds") { |i| @settings[:min_interval] = i }
+        opts.on("-x", "--max-interval SECS", Integer, "Maximum poll interval in seconds") { |i| @settings[:max_interval] =  i }
+        opts.on("-s", "--interval-step SECS", Integer, "Poll interval step in seconds") { |i| @settings[:interval_step] =  i }
+        opts.on("-f", "--log-file FILE", "Log file") { |f| @settings[:log_file] =  f }
+        opts.on("-l", "--log-level LEVEL", "Log level (err, warn, info, debug), default id info") { |l| @settings[:log_level] =  l }
+        opts.on("-u", "--login LOGIN", "Twitter login") { |l| @settings[:login] =  l }
+        opts.on("-p", "--password PASSWORD", "Twitter password") { |p| @settings[:password] =  p }
+        opts.on("-h", "--help", "Show this message") { puts opts; exit }
+
+        begin
+          require 'daemons'
+          opts.on("-d", "--daemonize", "Run as background process (Not implemented)") { |t| @settings[:daemonize] = true }
+        rescue LoadError
+        end
+
+      end.parse!(args)
+    end
+  end
+
+  #
+  # Configuration from files
+  #
+  class FileConfig < Config
+
+    #
+    # Accepts a stream or a file to read configuration from
+    # Default is to read configuration from ./config/bot.yml
+    #
+    # If a stream is passed it is not closed from within the method
+    #
+    def initialize(fos = File.expand_path("config/bot.yml"))
+      stream = fos.is_a?(String) ? File.open(fos, "r") : fos
+
+      begin
+        config = YAML.load(stream.read)
+        config.symbolize_keys! if config
+      rescue Exception => err
+        puts err.message
+        puts "Unable to load configuration, aborting"
+        exit
+      ensure
+        stream.close if fos.is_a?(String)
+      end
+
+      super config.is_a?(Hash) ? config : {}
+    end
+  end
+end

data/lib/twibot/handlers.rb

@@ -0,0 +1,103 @@
+module Twibot
+  module Handlers
+    #
+    # Add a handler for this bot
+    #
+    def add_handler(type, handler)
+      handlers[type] << handler
+      handler
+    end
+
+    def dispatch(type, message)
+      handlers[type].each { |handler| handler.dispatch(message) }
+    end
+
+    def handlers
+      @handlers ||= {
+        :message => [],
+        :reply => [],
+        :tweet => []
+      }
+    end
+
+    def handlers=(hash)
+      @handlers = hash
+    end
+  end
+
+  #
+  # A Handler object is an object which can handle a direct message, tweet or
+  # at reply.
+  #
+  class Handler
+    def initialize(pattern = nil, options = {}, &blk)
+      if pattern.is_a?(Hash)
+        options = pattern
+        pattern = nil
+      end
+
+      @options = options
+      @options[:from].collect! { |s| s.to_s } if @options[:from] && @options[:from].is_a?(Array)
+      @options[:from] = [@options[:from].to_s] if @options[:from] && @options[:from].is_a?(String)
+      @handler = nil
+      @handler = block_given? ? blk : nil
+      self.pattern = pattern
+    end
+
+    #
+    # Parse pattern string and set options
+    #
+    def pattern=(pattern)
+      return if pattern.nil? || pattern == ""
+
+      words = pattern.split.collect { |s| s.strip }          # Get all words in pattern
+      @options[:tokens] = words.inject([]) do |sum, token|   # Find all tokens, ie :symbol :like :names
+        next sum unless token =~ /^:.*/                      # Don't process regular words
+        sym = token.sub(":", "").to_sym                      # Turn token string into symbol, ie ":token" => :token
+        regex = @options[sym] || '[^\s]+'                    # Fetch regex if configured, else use any character but space matching
+        pattern.sub!(/(^|\s)#{token}(\s|$)/, '\1(' + regex.to_s + ')\2') # Make sure regex captures named switch
+        sum << sym
+      end
+
+      @options[:pattern] = /#{pattern}(\s.+)?/
+    end
+
+    #
+    # Determines if this handler is suited to handle an incoming message
+    #
+    def recognize?(message)
+      return false if @options[:pattern] && message.text !~ @options[:pattern] # Pattern check
+
+      users = @options[:from] ? @options[:from] : nil
+      return false if users && !users.include?(message.sender.screen_name) # Check allowed senders
+      true
+    end
+
+    #
+    # Process message to build params hash and pass message along with params of
+    # to +handle+
+    #
+    def dispatch(message)
+      return unless recognize?(message)
+      @params = {}
+
+      if @options[:pattern]
+        matches = message.text.match(@options[:pattern])
+        @options[:tokens].each_with_index { |token, i| @params[token] = matches[i+1] }
+        @params[:text] = (matches[@options[:tokens].length+1] || "").strip
+      else
+        @params[:text] = message.text
+      end
+
+      handle(message, @params)
+    end
+
+    #
+    # Handle a message. Calls the internal Proc with the message and the params
+    # hash as parameters.
+    #
+    def handle(message, params)
+      @handler.call(message, params) if @handler
+    end
+  end
+end

data/lib/twibot/macros.rb

@@ -0,0 +1,66 @@
+module Twibot
+  @@prompt = false
+
+  def self.prompt=(p)
+    @@prompt = f
+  end
+
+  module Macros
+    def self.included(mod)
+      @@bot = nil
+    end
+
+    def configure(&blk)
+      bot.configure(&blk)
+    end
+
+    def message(pattern = nil, options = {}, &blk)
+      add_handler(:message, pattern, options, &blk)
+    end
+
+    def reply(pattern = nil, options = {}, &blk)
+      add_handler(:reply, pattern, options, &blk)
+    end
+
+    def tweet(pattern = nil, options = {}, &blk)
+      add_handler(:tweet, pattern, options, &blk)
+    end
+
+    def twitter
+      bot.twitter
+    end
+
+    alias_method :client, :twitter
+
+    def post_tweet(msg)
+      message = msg.respond_to?(:text) ? msg.text : msg
+      puts message
+      client.status(:post, message)
+    end
+
+    def run?
+      !@@bot.nil?
+    end
+
+   private
+    def add_handler(type, pattern, options, &blk)
+      bot.add_handler(type, Twibot::Handler.new(pattern, options, &blk))
+    end
+
+    def bot
+      return @@bot unless @@bot.nil?
+
+      begin
+        @@bot = Twibot::Bot.new nil, true
+      rescue Exception
+        @@bot = Twibot::Bot.new(Twibot::Config.default << Twibot::CliConfig.new, true)
+      end
+
+      @@bot
+    end
+
+    def self.bot=(bot)
+      @@bot = bot
+    end
+  end
+end