marvin 0.8.0.0

data/bin/marvin

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+require 'rubygems'
+require File.join(File.dirname(__FILE__), "..", "lib", "marvin")
+
+Marvin::Application.processing(ARGV) do |a|
+  
+  a.banner = "Marvin v#{Marvin::VERSION} - An IRC Library for Ruby"
+  
+  a.generator!
+  
+  a.option      :development, "Runs the app in development mode (handler reloading)", :shortcut => "D"
+  a.controller! :client, "Starts the actual Marvin client instance"
+  a.controller! :console, "Opens a friendly IRB prompt with Marvin pre-loaded"
+  a.controller! :distributed_client, "Starts a distributed client instance"
+  
+  a.option :force, "force the creation of the application"
+  a.add "create PATH", "Creates a marvin application at the given 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', 'lib', 'handlers', 'test'
+    template 'boot.erb',            'config/boot.rb'
+    template 'setup.erb',           'config/setup.rb'
+    template 'settings.yml.erb',    'config/settings.yml'
+    template 'connections.yml.erb', 'config/connections.yml'
+    template 'debug_handler.erb',   'handlers/debug_handler.rb'
+    template 'hello_world.erb',     'handlers/hello_world.rb'
+    template 'rakefile.erb',        'Rakefile'
+  end
+  
+end

data/handlers/debug_handler.rb

@@ -0,0 +1,5 @@
+# Use this class to debug stuff as you 
+# go along - e.g. dump events etc.
+class DebugHandler < Marvin::CommandHandler
+    
+end

data/handlers/hello_world.rb

@@ -0,0 +1,9 @@
+class HelloWorld < Marvin::CommandHandler
+  
+  exposes :hello
+  
+  def hello(data)
+    reply "Hola from process with pid #{Process.pid}!"
+  end
+  
+end

data/handlers/keiki_thwopper.rb

@@ -0,0 +1,21 @@
+class KeikiThwopper < Marvin::Base
+  
+  FROM_REGEXP  = /^(sutto)/i
+  THWOP_REGEXP = /(t+h+w+o+m*p+|stab|kill)/i
+  
+  MESSAGES = [
+    "mwahahahaha",
+    "you totally deserved it",
+    "oi! leave 'em alone!",
+    "say hello to my little friend",
+    "you know, they could have liked that?"
+  ]
+  
+  on_event :incoming_action,  :thwop_back
+  
+  def thwop_back
+    return if !from || from !~ FROM_REGEXP || options.message !~ THWOP_REGEXP
+    action "#{$1}s #{from} (#{MESSAGES[rand(MESSAGES.length)]})"
+  end
+  
+end

data/handlers/simple_logger.rb

@@ -0,0 +1,24 @@
+# A reference logger example
+class SimpleLogger < Marvin::LoggingHandler
+  
+  def setup_logging
+    logger.warn "Setting up the client"
+  end
+  
+  def teardown_logging
+    logger.warn "Tearing down the logger"
+  end
+  
+  def log_incoming(server, nick, target, message)
+    logger.fatal "[INCOMING] #{server} (#{target}) #{nick}: #{message}"
+  end
+
+  def log_outgoing(server, nick, target, message)
+    logger.fatal "[OUTGOING] #{server} (#{target}) #{nick}: #{message}"
+  end
+
+  def log_message(server, nick, target, message)
+    logger.fatal "[MESSAGE]  #{server} (#{target}) #{nick}: #{message}"
+  end
+  
+end

data/handlers/tweet_tweet.rb

@@ -0,0 +1,19 @@
+# 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.rb

@@ -0,0 +1,56 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'rubygems'
+require 'perennial'
+
+module Marvin
+  include Perennial
+  
+  VERSION = [0, 8, 0, 0]
+  
+  # Misc.
+  #autoload :Util,             'marvin/util'
+  # Client
+  #autoload :AbstractClient,   'marvin/abstract_client'
+  #autoload :IRC,              'marvin/irc'
+  autoload :TestClient,       'marvin/test_client'
+  # Console of DOOM.
+  autoload :Console,          'marvin/console'
+  # Distributed
+  autoload :Distributed,      'marvin/distributed'
+  autoload :Status,           'marvin/status'
+  # Handler
+  autoload :Base,             'marvin/base'
+  autoload :CommandHandler,   'marvin/command_handler'
+  autoload :LoggingHandler,   'marvin/logging_handler'
+  autoload :CoreCommands,     'marvin/core_commands'
+  autoload :MiddleMan,        'marvin/middle_man'
+  # These should be namespaced under IRC
+  #autoload :AbstractParser,   'marvin/abstract_parser'
+  autoload :Parsers,          'marvin/parsers'
+  
+  
+  manifest do |m, l|
+    Settings.root = File.dirname(File.dirname(__FILE__))
+    l.register_controller :client,             'Marvin::Settings.client'
+    l.register_controller :console,            'Marvin::Console'
+    l.register_controller :distributed_client, 'Marvin::Distributed::Client'
+    # Core Commands handily makes available a set
+    # of information about what is running etc.
+    
+    l.before_run do
+      if l.distributed_client?
+        Marvin::Settings.client = Marvin::Distributed::Client 
+      end
+    end
+    
+  end
+  
+  def self.version(include_minor = false)
+    VERSION[0, (include_minor ? 4 : 3)].join(".")
+  end
+  
+  has_library :util, :abstract_client, :abstract_parser, :irc, :exception_tracker
+  
+  extends_library :settings
+  
+end

data/lib/marvin/abstract_client.rb

@@ -0,0 +1,146 @@
+require "marvin/irc/event"
+
+module Marvin
+  class AbstractClient
+    
+    is :dispatchable, :loggable
+    
+    def initialize(opts)
+      opts = opts.to_nash if opts.is_a?(Hash)
+      @connection_config = opts.dup # Copy the options so we can use them to reconnect.
+      @server            = opts.server
+      @port              = opts.port
+      @default_channels  = opts.channels
+      @nicks             = opts.nicks || []
+      @pass              = opts.pass
+    end
+    
+    cattr_accessor :events, :configuration, :is_setup, :connections, :development
+    attr_accessor  :channels, :nickname, :server, :port, :nicks, :pass,
+                   :disconnect_expected, :connection_config
+    
+    # Set the default values for the variables
+    @@events        = []
+    @@configuration = Marvin::Nash.new
+    @@connections   = []
+    @@development   = false
+      
+    # 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.info "Initializing the current instance"
+      @channels = []
+      connections << self
+      logger.info "Setting the client for each handler"
+      setup_handlers
+      logger.info "Dispatching the default :client_connected event"
+      dispatch :client_connected
+    end
+    
+    def process_disconnect
+      logger.info "Handling disconnect for #{host_with_port}"
+      connections.delete(self)
+      dispatch :client_disconnected
+      unless @disconnect_expected
+        logger.warn "Unexpectly lost connection to server; adding reconnect"
+        self.class.add_reconnect @connection_config
+      else
+        Marvin::Loader.stop! if connections.blank?
+      end
+    end
+    
+    def setup_handlers
+      handlers.each { |h| h.client = self if h.respond_to?(:client=) }
+    end
+    
+    def process_development
+      if @@development
+        Marvin::Reloading.reload!
+        setup_handlers
+      end
+    end
+    
+    def dispatch(*args)
+      process_development
+      super
+    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)
+      config = Marvin::Nash.new(config.to_hash) unless config.is_a?(Marvin::Nash)
+      @@configuration = config.normalized
+    end
+    
+    def self.setup?
+      @setup ||= false
+    end
+    
+    def self.setup
+      return if setup?
+      configure
+    end
+    
+    def self.configure
+      config = Marvin::Nash.new
+      config.merge! Marvin::Settings.configuration
+      if block_given?
+        yield(nash = Marvin::Nash.new)
+        config.merge! nash
+      end
+      @@configuration = config
+      # Help is only currently available on an instance running
+      # distributed handler.
+      Marvin::CoreCommands.register! unless Marvin::Distributed::Handler.registered?
+      @setup = true
+    end
+    
+    ## Handling all of the the actual client stuff.
+    
+    def receive_line(line)
+      dispatch :incoming_line, :line => line
+      event = Marvin::Settings.parser.parse(line)
+      dispatch(event.to_incoming_event_name, event.to_hash) unless event.nil?  
+    end
+    
+    def default_channels
+      @default_channels ||= []
+    end
+    
+    def default_channels=(channels)
+      @default_channels = channels.to_a.map { |c| c.to_s }
+    end
+    
+    def host_with_port
+      @host_with_port ||= "#{server}:#{port}"
+    end
+    
+    def nicks
+      if @nicks.blank? && !@nicks_loaded
+        logger.info "Setting default nick list"
+        @nicks = []
+        @nicks << configuration.nick if configuration.nick?
+        @nicks += configuration.nicks.to_a if configuration.nicks?
+        @nicks.compact!
+        raise "No initial nicks for #{host_with_port}" if @nicks.blank?
+        @nicks_loaded = true
+      end
+      return @nicks
+    end
+    
+    # Break it down into a couple of different files.
+    require 'marvin/client/default_handlers'
+    require 'marvin/client/actions'
+    
+    protected
+    
+    def util
+      Marvin::Util
+    end
+    
+  end
+end

data/lib/marvin/abstract_parser.rb

@@ -0,0 +1,29 @@
+module Marvin
+  class AbstractParser
+    
+    attr_accessor :line, :command, :event
+    
+    # Instantiates a parser instance, attempts to 
+    # parse it for it's command and it's event.
+    def initialize(line)
+      @line    = line
+      @command = self.class.parse!(line)
+      @event   = @command.to_event unless @command.blank?
+    end
+    
+    def to_event
+      @event
+    end
+    
+    def self.parse(line)
+      new(line.strip).to_event
+    end
+    
+    protected
+    
+    def self.parse!(line)
+      raise NotImplementedError, "Must be implemented in a subclass"
+    end
+    
+  end
+end

data/lib/marvin/base.rb

@@ -0,0 +1,195 @@
+module Marvin
+  
+  def self.handler_parent_classes
+    @@handler_parent_classes ||= Hash.new { |h,k| h[k] = Set.new }
+  end
+  
+  class Base
+    is :loggable
+    
+    @@handlers = Hash.new do |h,k|
+      h[k] = Hash.new { |h2, k2| h2[k2] = [] }
+    end
+    
+    attr_accessor :client, :target, :from, :options
+    
+    class << self
+        
+      def registered?
+        @registered ||= false
+      end
+      
+      def registered=(value)
+        @registered = !!value
+      end
+      
+      # Returns an array of all handlers associated with
+      # a specific event name (e.g. :incoming_message)
+      def event_handlers_for(message_name)
+        message_name = message_name.to_sym
+        items = []
+        klass = self
+        while klass != Object
+          items += @@handlers[klass][message_name]
+          klass = klass.superclass
+        end
+        items
+      end
+      
+      # Registers a block to be used as an event handler. The first
+      # argument is always the name of the event and the second
+      # is either a method name (e.g. :my_awesome_method) or
+      # a block (which is instance_evaled)
+      def on_event(name, method_name = nil, &blk)
+        blk = proc { self.send(method_name) } if method_name.present?
+        @@handlers[self][name] << blk
+      end
+      
+      # Like on_event but instead of taking an event name it takes
+      # either a number or a name - corresponding to an IRC numeric
+      # reply.
+      def on_numeric(value, method_name = nil, &blk)
+        value = value.is_a?(Numeric) ? ("%03d" % value) : Marvin::IRC::Replies[value]
+        on_event(:"incoming_numeric_#{new_value}", method_name, &blk) if value.present?
+      end
+      
+      # Register this specific handler on the IRC handler.
+      def register!(parent = Marvin::Settings.client)
+        return if self == Marvin::Base # Only do it for sub-classes.
+        parent.register_handler self.new unless parent.handlers.any? { |h| h.class == self }
+        Marvin.handler_parent_classes[self.name] << parent
+      end
+    
+      def reloading!
+        Marvin.handler_parent_classes[self.name].each do |dispatcher|
+          parent_handlers = dispatcher.handlers
+          related = parent_handlers.select { |h| h.class == self }
+          related.each do |h|
+            h.handle(:reloading, {})
+            dispatcher.delete_handler(h)
+          end
+        end
+      end
+      
+      def reloaded!
+        Marvin.handler_parent_classes[self.name].each do |dispatcher|
+          before = dispatcher.handlers
+          register!(dispatcher)
+          after = dispatcher.handlers
+          (after - before).each { |h| h.handle(:reloaded, {}) }
+        end
+        
+      end
+    
+    end
+    
+    def handle(message, options)
+      dup._handle(message, options)
+    end
+    
+    # Given an incoming message, handle it appropriately by getting all
+    # associated event handlers. It also logs any exceptions (aslong as
+    # they raised by halt)
+    def _handle(message, options)
+      setup_details(options)
+      h = self.class.event_handlers_for(message)
+      h.each { |eh| self.instance_eval(&eh) }
+    rescue Exception => e
+      # Pass on halt_handler_processing events.
+      raise e if e.is_a?(Marvin::HaltHandlerProcessing)
+      logger.fatal "Exception processing handler for #{message.inspect}"
+      Marvin::ExceptionTracker.log(e)
+    ensure
+      reset_details
+    end
+    
+    # The default handler for numerics. mutates them into a more
+    # friendly version of themselves. It will also pass through
+    # the original incoming_numeric event.
+    def handle_incoming_numeric(opts)
+      handle(:incoming_numeric, opts)
+      handle(:"incoming_numeric_#{opts[:code]}", opts)
+    end
+    
+    # msg sends the given text to the current target, be it
+    # either a channel or a specific user.
+    def msg(message, target = self.target)
+      client.msg(target, message)
+    end
+    
+    alias say msg
+    
+    def action(message, target = self.target)
+      client.action(target, message)
+    end
+    
+    # A conditional version of message that will only send the message
+    # if the target / from is a user. To do this, it uses from_channel?
+    def pm(message, target)
+      say(message, target) unless from_channel?(target)
+    end
+    
+    # Replies to a message. if it was received in a channel, it will
+    # use the standard irc "Name: text" convention for replying whilst
+    # if it was in a direct message it sends it as is.
+    def reply(message)
+      if from_channel?
+        say("#{from}: #{message}")
+      else
+        say(message, from)
+      end
+    end
+    
+    def ctcp(message)
+      say("\01#{message}\01", from) if !from_channel?
+    end
+    
+    # Request information
+    
+    # reflects whether or not the current message / previous message came
+    # from a user via pm.
+    def from_user?
+      !from_channel?
+    end
+    
+    # Determines whether a given target (defaulting to the target of the
+    # last message was in a channel)
+    def from_channel?(target = self.target)
+      target.present? && target =~ /^[\&\#]/
+    end
+    
+    def addressed?
+      from_user? || options.message =~ /^#{client.nickname.downcase}:\s+/i
+    end
+    
+    # A Perennial automagical helper for dispatch
+    def registered=(value)
+      self.class.registered = value
+    end
+    
+    protected
+    
+    # Initializes details for the current cycle - in essence, this makes the
+    # details of the current request available.
+    def setup_details(options)
+      @options = options.is_a?(Marvin::Nash) ? options : Marvin::Nash.new(options.to_hash)
+      @target  = @options.target if @options.target?
+      @from    = @options.nick   if @options.nick?
+    end
+    
+    def reset_details
+      @options = nil
+      @target = nil
+      @from = nil
+    end
+    
+    # Halt can be called during the handle / process. Doing so
+    # prevents any more handlers in the handler chain from being
+    # called. It's kind of like return but it works across all
+    # handlers, not just the current one.
+    def halt!
+      raise Marvin::HaltHandlerProcessing
+    end
+    
+  end
+end