jeffrafter-marvin 0.1.20081115

data/README.textile

@@ -0,0 +1,110 @@
+h1. Marvin
+
+Marvin is a simple IRC Framework for Rails suitable for building things
+such as simple IRC bots. Extracted from real use - we'd originally used
+a heavily modified version of MatzBot - it's been built to service a
+particular need.
+
+h2. Background
+
+Marvin is an event driven framework in two ways - for one, it uses
+EventMachine for all networking purposes - as a result, it's both
+relatively stable / reliable and also powerful.
+
+Following on from this, the irc library is event driven. At the base
+level, you choose a client (By Default, Marvin::IRC::Client.) and then you register
+any number of handlers. Whenever an event happens e.g. an incoming message,
+a connection unbinding or event just post_init, each handler is notified
+and given a small set of details about the event.
+
+Handlers are very simple - in fact, you could get away with registering
+Object.new as a handler.
+
+To function, handlers only require one method: handle - which takes
+two options. an event name (e.g. :incoming_message) and a hash
+of the aforementioned attributes / details. This data can then be processed.
+Alternatively, if a handler has a "handle_[event_name]" method (e.g.
+handle_incoming_message), it will instead be called. Also, if client=
+is implemented this will be called when the client is setup containing
+a reference to said client. This is used to that the handler can
+respond to actions.
+
+Like Rack for HTTP, Marvin provides a fair amount of example
+handlers for simple stuff inside IRC.
+
+h2. Marvin::Base - A handler starting point
+
+The first, Marvin::Base provides a base set of methods (e.g. say,
+reply etc etc.) which make writing a client easier. You can simply
+inherit from Marvin::Base, write some logic and then use the class
+method on_event to define responses to events. The passed in meta
+data for each event is then usable via options.attribute_name - an
+openstruct version of the details. e.g.
+
+  class NinjaStuff < Marvin::Base
+    on_event :incoming_message do
+      do_something
+    end
+    def do_something
+      reply options.message # Will echo back the message
+    end
+  end
+    
+Or the like. Also, the halt! method can be called in any subclass to
+halt the handler callback chain.
+
+h2. Marvin::CommandHandler - Ridiculously easy Bots
+
+With Marvin::CommandHandler, you get to define seriously
+simple classes which can act as a simple bot. It takes
+great inspiration from "MatzBot":http://github.com/defunkt/matzbot/tree/master
+which was actually one of the main inspirations for
+creating marvin.
+
+To write a CommandHandler, you simply create a subclass
+(ala ActiveRecord::Base), define a few methods and then
+just use the "exposes" class method. e.g.
+
+  class MySecondExample < Marvin::CommandHandler
+    exposes :hello
+    def hello(data)
+      reply "Hello!"
+    end
+  end
+    
+Where data is an array of parameters. exposed methods will be called
+when they match the following pattern:
+
+  Botname: <exposed-method> <space-seperated-list-meaning-data>
+
+h2. Marvin::MiddleMan - Introducing middleware
+
+Marvin::MiddleMan lets you insert middleware between handlers
+and you're client - letting you do things such as translating
+all messages on the fly. It's build to be extensible and is
+relatively simple to use. On any Marvin::Base subclass (baring
+the MiddleMan itself), you can simple use the normal methods
+of registering a handler with one exception - you now pass
+one argument, the class reference to your middleman class.
+
+h2. Marvin::DataStore - A dead simple persistent hash store
+
+Want to save data between when you stop and start your IRC
+Client? With Marvin, it's really, really simple - Marvin::DataStore
+offers a simple syntax for persistent data stores.
+
+New datastores can be created with Marvin::DataStore.new("global-store-key").
+From there, you have a hash to do whatever the hell you want. Just
+make sure the data you store is JSON-serializable.
+
+When you start - stop a server (via Marvin::Loader.run! and Marvin::Loader.stop!)
+you're data will be loaded from and written to disk accordingly.
+
+If you're inside a Marvin::Base subclass it's even easier. You can get a cattr_access
+style accessor for free - just use the "uses_datastore" method. e.g:
+
+  class X < Marvin::Base
+    uses_datastore "datastore-global-key", :cattr_name
+  end
+  
+Then, self.cattr_name will point to the data store instance.

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+patch: 20081115
+major: 0
+minor: 1

data/bin/marvin

@@ -0,0 +1,67 @@
+#!/usr/bin/env ruby
+require 'rubygems'
+require 'fileutils'
+
+LOCATION_ROOT = File.join(File.dirname(__FILE__), "..")
+DEST = ARGV[1] || "./marvin"
+
+def j(*args); File.join(*args); end
+
+def copy(f, t = nil)
+  t = f if t.nil?
+  File.open(j(DEST, t), "w+") do |file|
+    file.puts File.read(j(LOCATION_ROOT, f))
+  end
+end
+
+puts "Marvin - A Ruby IRC Library / Framework"
+if ARGV.include?("-h") || ARGV.include?("--help")
+  puts "Usage: marvin create <name> - Creates a marvin directory at name or ./marvin"
+  puts "       marvin (in a Marvin dir) - Starts it, equiv. to script/marvin"
+  exit
+end
+
+if ARGV.length >= 1 && !["start", "stop", "run", "restart"].include?(ARGV[0])
+  if ARGV[0].to_s.downcase != "create"
+    puts "'#{ARGV[0]}' isn't a valid command. - Please use #{__FILE__} --help"
+    exit(1)
+  end
+  if File.exist?(DEST) && File.directory?(DEST)
+    puts "The folder '#{DEST}' already exists."
+    exit(1)
+  end
+  # Generate it.
+  FileUtils.mkdir(DEST)
+  ["log", "tmp", "config", "handlers", "script"].each do |folder|
+    FileUtils.mkdir(j(DEST, folder))
+  end
+  
+  puts "Writing Settings file"
+  copy "config/settings.yml.sample", "config/settings.yml"
+  
+  puts "Writing setup.rb"
+  copy "config/setup.rb"
+  
+  puts "Copying start script - script/run"
+  copy "script/run"
+  copy "script/daemon-runner"
+  FileUtils.chmod 0755, j(DEST, "script/run")
+  FileUtils.chmod 0755, j(DEST, "script/daemon-runner")
+  
+  puts "Copying example handler"
+  copy "handlers/hello_world.rb"
+  
+  puts "Done!"
+elsif ARGV.length >= 1
+  if !File.exist?("script/daemon-runner")
+    puts "Woops! This isn't a marvin directory."
+    exit(1)
+  end
+  exec "script/daemon-runner #{ARGV.map {|a| a.include?(" ") ? "\"#{a}\"" : a }.join(" ")}"
+else
+  if !File.exist?("script/run")
+    puts "Woops! This isn't a marvin directory."
+    exit(1)
+  end
+  exec "script/run"
+end

data/config/settings.yml.sample

@@ -0,0 +1,13 @@
+default:
+  name: "My Marvin Bot"
+  server: irc.freenode.net
+  port: 6667
+  channel: "#marvin-testing"
+  use_logging: false
+  datastore_location: tmp/datastore.json
+development:
+  user: MarvinBot
+  name: MarvinBot
+  nick:  MarvinBot3000
+production:
+  deployed: false

data/config/setup.rb

@@ -0,0 +1,14 @@
+# Register all of the handlers you wish to use
+# when the clien connects.
+Marvin::Loader.before_connecting do
+  
+  # E.G.
+  # MyHandler.register! (Marvin::Base subclass) or
+  # Marvin::Settings.default_client.register_handler my_handler (a handler instance)
+  
+  # Example Handler use.
+  # LoggingHandler.register! if Marvin::Settings.use_logging
+  
+  HelloWorld.register!
+  
+end

data/handlers/hello_world.rb

@@ -0,0 +1,9 @@
+class HelloWorld < Marvin::CommandHandler
+  
+  exposes :hello
+  
+  def hello(data)
+    reply "Hola!" unless target == "#all"
+  end
+  
+end

data/handlers/logging_handler.rb

@@ -0,0 +1,87 @@
+# A Simple Channel Logger, built for the 
+# #offrails community. Please note that this
+# relies on models etc. inside the Rails App.
+# it's suited for modification of subclassing
+# if you wish to write your own Channel Logger.
+# I plan on open sourcing the app sometime in
+# the near future.
+class LoggingHandler < Marvin::CommandHandler
+  
+  class_inheritable_accessor :connection, :setup
+  attr_accessor :listening, :users
+  
+  def initialize
+    super
+    logger.debug "Setting up LoggingHandler"
+    self.setup!
+    self.users = {}
+  end
+  
+  # Control
+  
+  exposes :listen, :earmuffs
+  
+  def listen(data)
+    unless listening?
+      @listening = true
+      reply "Busted! I heard _everything_ you said ;)"
+    else
+      reply "Uh, You never asked me to put my earmuffs on?"
+    end
+  end
+  
+  def earmuffs(data)
+    if listening?
+      @listening = false
+      reply "Oh hai, I'm not listening anymore."
+    else
+      reply "I've already put the earmuffs on!"
+    end
+  end
+  
+  def listening?
+    @listening
+  end
+  
+  # The actual logging
+  
+  on_event :incoming_message do
+    log_message(options.nick, options.target, options.message)
+  end
+  
+  on_event :outgoing_message do
+    log_message(client.nickname, options.target, options.message)
+  end
+  
+  on_event :incoming_action do
+    log_message(options.nick, options.target, "ACTION \01#{options.message}\01")
+  end
+  
+  def log_message(from, to, message)
+    return unless listening?
+    ensure_connection_is_alive # Before Logging, ensure that the connection is alive.
+    self.users[from.strip] ||= IrcHandle.find_or_create_by_name(from.strip)
+    self.users[from.strip].messages.create :message => message, :target => to
+  end
+  
+  # Our General Tasks
+  
+  def setup!
+    return true if self.setup
+    load_prerequisites
+    self.setup = true
+    self.listening = true
+  end
+  
+  def load_prerequisites
+    require File.join(Marvin::Settings.rails_root, "config/environment")
+  end
+  
+  def ensure_connection_is_alive
+    unless ActiveRecord::Base.connection.active?
+      ActiveRecord::Base.connection.reconnect!
+    end
+  end
+  
+  
+end

data/handlers/tweet_tweet.rb

@@ -0,0 +1,21 @@
+# Not Yet Complete: Twitter Client in Channel.
+class TweetTweet < Marvin::Base
+  
+  on_event :client_connected do
+    start_tweeting
+  end
+  
+  def start_tweeting
+    client.periodically 180, :check_tweets
+  end
+  
+  def handle_check_tweets
+    logger.debug ">> Check Tweets"
+  end
+  
+  def show_tweet(tweet)
+  end
+  
+  
+  
+end

data/lib/marvin/abstract_client.rb

@@ -0,0 +1,210 @@
+require 'ostruct'
+require 'active_support'
+require "marvin/irc/event"
+
+module Marvin
+  class AbstractClient
+    
+    include Marvin::Dispatchable
+    
+    cattr_accessor :events, :configuration, :logger, :is_setup, :connections
+    attr_accessor  :channels, :nickname
+    
+    # Set the default values for the variables
+    self.events                 = []
+    self.configuration          = OpenStruct.new
+    self.configuration.channels = []
+    self.connections            = []
+    
+    # Initializes the instance variables used for the
+    # current connection, dispatching a :client_connected event
+    # once it has finished. During this process, it will
+    # call #client= on each handler if they respond to it.
+    def process_connect
+      self.class.setup
+      logger.debug "Initializing the current instance"
+      self.channels = []
+      self.connections << self
+      logger.debug "Setting the client for each handler"
+      self.handlers.each { |h| h.client = self if h.respond_to?(:client=) }
+      logger.debug "Dispatching the default :client_connected event"
+      dispatch :client_connected
+    end
+    
+    def process_disconnect
+      self.connections.delete(self) if self.connections.include?(self)
+      dispatch :client_disconnected
+      Marvin::Loader.stop! if self.connections.blank?
+    end
+    
+    # Sets the current class-wide settings of this IRC Client
+    # to either an OpenStruct or the results of #to_hash on
+    # any other value that is passed in.
+    def self.configuration=(config)
+      @@configuration = config.is_a?(OpenStruct) ? config : OpenStruct.new(config.to_hash)
+    end
+    
+    # Initializes class-wide settings and those that
+    # are required such as the logger. by default, it
+    # will convert the channel option of the configuration
+    # to be channels - hence normalising it into a format
+    # that is more widely used throughout the client.
+    def self.setup
+      return if self.is_setup
+      # Default the logger back to a new one.
+      self.configuration.channels ||= []
+      unless self.configuration.channel.blank? || self.configuration.channels.include?(self.configuration.channel)
+        self.configuration.channels.unshift(self.configuration.channel)
+      end
+      if configuration.logger.blank?
+        require 'logger'
+        configuration.logger = Marvin::Logger.logger
+      end
+      self.logger = self.configuration.logger
+      self.is_setup = true
+    end
+    
+    ## Handling all of the the actual client stuff.
+    
+    def receive_line(line)
+      dispatch :incoming_line, :line => line
+      event = Marvin::Settings.default_parser.parse(line)
+      dispatch(event.to_incoming_event_name, event.to_hash) unless event.nil?
+    end
+    
+    # Default handlers
+    
+    # The default handler for all things initialization-related
+    # on the client. Usually, this will send the user command,
+    # set out nick, join all of the channels / rooms we wish
+    # to be in and if a password is specified in the configuration,
+    # it will also attempt to identify us.
+    def handle_client_connected(opts = {})
+      logger.debug "About to handle post init"
+      # IRC Connection is establish so we send all the required commands to the server.
+      logger.debug "Setting default nickname"
+      default_nickname = self.configuration.nick || self.configuration.nicknames.shift
+      nick default_nickname
+      logger.debug "sending user command"
+      command :user, self.configuration.user, "0", "*", Marvin::Util.last_param(self.configuration.name)
+      # If a password is specified, we will attempt to message
+      # NickServ to identify ourselves.
+      say ":IDENTIFY #{self.configuration.password}", "NickServ" unless self.configuration.password.blank?
+      # Join the default channels
+      self.configuration.channels.each { |c| self.join c }
+    rescue Exception => e
+      Marvin::ExceptionTracker.log(e)
+    end
+   
+    # The default handler for when a users nickname is taken on
+    # on the server. It will attempt to get the nicknickname from
+    # the nicknames part of the configuration (if available) and
+    # will then call #nick to change the nickname.
+    def handle_incoming_nick_taken(opts = {})
+      logger.info "Nick Is Taken"
+      logger.debug "Available Nicknames: #{self.configuration.nicknames.to_a.join(", ")}"
+      available_nicknames = self.configuration.nicknames.to_a 
+      if available_nicknames.length > 0
+        logger.debug "Getting next nickname to switch"
+        next_nick = available_nicknames.shift # Get the next nickname
+        self.configuration.nicknames = available_nicknames
+        logger.info "Attemping to set nickname to #{new_nick}"
+        nick next_nick
+      else
+        logger.info "No Nicknames available - QUITTING"
+        quit
+      end
+    end
+    
+    # The default response for PING's - it simply replies
+    # with a PONG.
+    def handle_incoming_ping(opts = {})
+      logger.info "Received Incoming Ping - Handling with a PONG"
+      pong(opts[:data])
+    end
+    
+    # TODO: Get the correct mapping for a given
+    # Code.
+    def handle_incoming_numeric(opts = {})
+      code = opts[:code].to_i
+      args = Marvin::Util.arguments(opts[:data])
+      dispatch :incoming_numeric_processed, {:code => code, :data => args}
+    end
+    
+    ## General IRC Functions
+    
+    # Sends a specified command to the server.
+    # Takes name (e.g. :privmsg) and all of the args.
+    # Very simply formats them as a string correctly
+    # and calls send_data with the results.
+    def command(name, *args)
+      # First, get the appropriate command
+      name = name.to_s.upcase
+      args = args.flatten.compact
+      irc_command = "#{name} #{args.join(" ").strip} \r\n"
+      send_line irc_command
+    end
+    
+    def join(channel)
+      channel = Marvin::Util.channel_name(channel)
+      # Record the fact we're entering the room.
+      self.channels << channel
+      command :JOIN, channel
+      logger.info "Joined channel #{channel}"
+      dispatch :outgoing_join, :target => channel
+    end
+    
+    def part(channel, reason = nil)
+      channel = Marvin::Util.channel_name(channel)
+      if self.channels.include?(channel)
+        command :part, channel, Marvin::Util.last_param(reason)
+        dispatch :outgoing_part, :target => channel, :reason => reason
+        logger.info "Parted from room #{channel}#{reason ? " - #{reason}" : ""}"
+      else
+        logger.warn "Tried to disconnect from #{channel} - which you aren't a part of"
+      end
+    end
+    
+    def quit(reason = nil)
+      logger.debug "Preparing to part from #{self.channels.size} channels"
+      self.channels.to_a.each do |chan|
+        logger.debug "Parting from #{chan}"
+        self.part chan, reason
+      end
+      logger.debug "Parted from all channels, quitting"
+      command :quit
+      dispatch :quit
+      # Remove the connections from the pool
+      self.connections.delete(self)
+      logger.info  "Quit from server"
+    end
+    
+    def msg(target, message)
+      command :privmsg, target, Marvin::Util.last_param(message)
+      logger.info "Message sent to #{target} - #{message}"
+      dispatch :outgoing_message, :target => target, :message => message
+    end
+    
+    def action(target, message)
+      action_text = Marvin::Util.last_param "\01ACTION #{message.strip}\01"
+      command :privmsg, target, action_text
+      dispatch :outgoing_action, :target => target, :message => message
+      logger.info "Action sent to #{target} - #{message}"
+    end
+    
+    def pong(data)
+      command :pong, data
+      dispatch :outgoing_pong
+      logger.info "PONG sent to #{data}"
+    end
+    
+    def nick(new_nick)
+      logger.info "Changing nickname to #{new_nick}"
+      command :nick, new_nick
+      self.nickname = new_nick
+      dispatch :outgoing_nick, :new_nick => new_nick
+      logger.info "Nickname changed to #{new_nick}"
+    end
+    
+  end
+end

data/lib/marvin/abstract_parser.rb

@@ -0,0 +1,19 @@
+module Marvin
+  # An abstract class for an IRC protocol
+  # Parser. Used as a basis for expirimentation.
+  class AbstractParser
+    
+    def self.parse(line)
+      return self.new(line.strip).to_event
+    end
+    
+    def initialize(line)
+      raise NotImplementedError, "Not implemented in an abstract parser"
+    end
+    
+    def to_event
+      raise NotImplementedError, "Not implemented in an abstract parser"
+    end
+    
+  end
+end

data/lib/marvin/base.rb

@@ -0,0 +1,121 @@
+require 'ostruct'
+
+module Marvin
+  # A Client Handler
+  class Base
+    
+    cattr_accessor :logger
+    # Set the default logger
+    self.logger ||= Marvin::Logger
+    
+    attr_accessor :client, :target, :from, :options, :logger
+    class_inheritable_accessor :registered_handlers
+    self.registered_handlers = {}
+    
+    def initialize
+      self.registered_handlers ||= {}
+      self.logger ||= Marvin::Logger
+    end
+    
+    class << self
+      
+      def event_handlers_for(message_name, direct = true)
+        return [] if self == Marvin::Base
+        rh = (self.registered_handlers ||= {})
+        rh[self.name] ||= {}
+        rh[self.name][message_name] ||= []
+        if direct
+          found_handlers = rh[self.name][message_name]
+          found_handlers += self.superclass.event_handlers_for(message_name)
+          return found_handlers
+        else
+          return rh[self.name][message_name]
+        end
+      end
+      
+      def on_event(name, &blk)
+        self.event_handlers_for(name, false) << blk
+      end
+      
+      # Register's in the IRC Client callback chain.
+      def register!(parent = Marvin::Settings.default_client)
+        return if self == Marvin::Base # Only do it for sub-classes.
+        parent.register_handler self.new
+      end
+      
+      def uses_datastore(datastore_name, local_name)
+        cattr_accessor local_name.to_sym
+        self.send("#{local_name}=", Marvin::DataStore.new(datastore_name))
+        rescue Exception => e
+          logger.debug "Exception in datastore declaration - #{e.inspect}"
+      end
+      
+    end
+    
+    # Given an incoming message, handle it appropriatly.
+    def handle(message, options)
+      begin
+        self.setup_defaults(options)
+        h = self.class.event_handlers_for(message)
+        h.each do |handle|
+          self.instance_eval &handle
+        end
+      rescue Exception => e
+        logger.fatal "Exception processing handle #{message}"
+        Marvin::ExceptionTracker.log(e)
+      end
+    end
+    
+    def say(message, target = self.target)
+      client.msg target, message
+    end
+    
+    def pm(target, message)
+      say(target, message)
+    end
+    
+    def reply(message)
+      if from_channel?
+        say "#{self.from}: #{message}"
+      else
+        say message, self.from # Default back to pm'ing the user
+      end
+    end
+    
+    def ctcp(message)
+      return if from_channel? # Must be from user
+      say "\01#{message}\01", self.from
+    end
+    
+    # Request information
+    
+    # reflects whether or not the current message / previous message came
+    # from a user via pm.
+    def from_user?
+      self.target && !from_channel?
+    end
+    
+    # Determines whether the previous message was inside a channel.
+    def from_channel?
+      self.target && self.target[0] == ?#
+    end
+    
+    def addressed?
+      self.from_user? || options.message.split(" ").first.downcase == "#{self.client.nickname.downcase}:"
+    end
+    
+    def setup_defaults(options)
+      self.options = options.is_a?(OpenStruct) ? options : OpenStruct.new(options)
+      self.target  = options[:target] if options.has_key?(:target)
+      self.from    = options[:nick]   if options.has_key?(:nick)
+    end
+    
+    # Halt's on the handler, used to prevent
+    # other handlers also responding to the same
+    # message more than once.
+    def halt!
+      raise HaltHandlerProcessing
+    end
+    
+  end
+end