jeffrafter-marvin 0.1.20081115 → 0.1.20081120

data/README.textile

@@ -7,30 +7,85 @@ 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.
+The library is designed to be event driven in that it:
+  
+  # Uses the EventMachine library for all network connections
+  # It uses an architecture based on event listeners - called 'handlers'
+
+It's been heavily influenced by rack in terms of design, making it easy
+to do things like chain handlers, write your own functionality and most
+of all making it easy to implement.
+
+h2. Getting Started
+
+The easiest way to get started with Marvin is by installing the Marvin gem. To
+do this, make sure Github is added to your gem sources (and you are using
+rubygems >= 1.2.0) (by default, substitute username for Sutto):
+
+  $ gem sources -a http://gems.github.com 
+  $ sudo gem install username-marvin
+  
+
+Once you have installed the gem, you should have access to the "marvin" command:
+
+  $ marvin --help
+  
+You can create a new marvin folder:
+
+  $ marvin create my_marvin_project
+  
+Then simply edit your settings in the +config/settings.yml+
+
+  default:
+    name: Marvin
+    use_logging: false
+    datastore_location: tmp/datastore.json
+  development:
+    user: MarvinBot
+    name: MarvinBot
+    nick:  Marvin
+
+You can use the defaults or configure it. The datastore location
+specifies a relative path where a simple json-backed key value
+store will store persistent information for your client (if chosen).
+Once that's been done, you'll want to setup some connections by editing
++config/connections.yml+, using the following format:
+
+  "server-address":
+    post: 6667 # Defaults to 6667
+    channels:
+      - "#marvin-testing"
+      - "#relayrelay"
+    nicks:
+      - List
+      - Of
+      - Alternative
+      - Nicks
+  "another-server-address":
+    post: 6667 # Defaults to 6667
+    channels:
+      - "#helloworld"
+
+Which will let marvin connect to multiple servers - autojoining the specific rooms.
+Next, to get started you can simply type:
+
+  $ ./script/client
+
+The bot should join the specified channel and will respond to some simple
+commands by default:
+
+  *YourName*: MarvinBot3000: hello
+  *MarvinBot3000*: YourName: Hola!
+  
+As defined in handlers/hello_world.rb
+
+h2. Thanks
+
+Thanks goes out to the following people / projects:
+
+* Jeff Rafter - contributed code and doc changes, now one of the co-developers.
+* epitron / halogrium - For the ragel state machine used in Marvin::Parsers::RagelParser
+* The creator of Ruby-IRCD - the server component is heavily influenced by / part derivative of said work.
 
 h2. Marvin::Base - A handler starting point
 
@@ -53,13 +108,15 @@ openstruct version of the details. e.g.
 Or the like. Also, the halt! method can be called in any subclass to
 halt the handler callback chain.
 
+You also get access to the class method +on_numeric+ which makes
+it relatively easy to respond to a specific numeric reply.
+
 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 make it as easy as possible to make a simple bot
 
 To write a CommandHandler, you simply create a subclass
 (ala ActiveRecord::Base), define a few methods and then
@@ -75,7 +132,15 @@ just use the "exposes" class method. e.g.
 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>
+  Botname: *exposed-method* *space-seperated-list-meaning-data*
+  
+i.e., the above handler could be called in IRC as such:
+
+  YourBotsName: hello
+  
+or, even easier, by PM'ing the bot with:
+  
+  hello
 
 h2. Marvin::MiddleMan - Introducing middleware
 
@@ -83,9 +148,10 @@ 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.
+the MiddleMan itself), using a middle man is easy - you simply
+call the register! class method with an option argument. e.g:
+
+  HelloWorld.register! Marvin::MiddleMan
 
 h2. Marvin::DataStore - A dead simple persistent hash store
 
@@ -104,7 +170,14 @@ If you're inside a Marvin::Base subclass it's even easier. You can get a cattr_a
 style accessor for free - just use the "uses_datastore" method. e.g:
 
   class X < Marvin::Base
-    uses_datastore "datastore-global-key", :cattr_name
+    uses_datastore "datastore-global-key", :something
+  end
+  
+Then, self.something will point to the data store - letting you do
+things like:
+
+  def hello(data)
+    (self.something[from] ||= 0) += 1
   end
   
-Then, self.cattr_name will point to the data store instance.
+which will persist the count between each session.

data/VERSION.yml

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

data/bin/marvin

@@ -39,17 +39,21 @@ if ARGV.length >= 1 && !["start", "stop", "run", "restart"].include?(ARGV[0])
   puts "Writing Settings file"
   copy "config/settings.yml.sample", "config/settings.yml"
   
+  puts "Writing Connections file"
+  copy "config/connections.yml.sample", "config/connections.yml"
+  
   puts "Writing setup.rb"
   copy "config/setup.rb"
   
-  puts "Copying start script - script/run"
-  copy "script/run"
+  puts "Copying start scripts"
+  copy "script/client"
   copy "script/daemon-runner"
-  FileUtils.chmod 0755, j(DEST, "script/run")
+  FileUtils.chmod 0755, j(DEST, "script/client")
   FileUtils.chmod 0755, j(DEST, "script/daemon-runner")
   
-  puts "Copying example handler"
+  puts "Copying example handlers"
   copy "handlers/hello_world.rb"
+  copy "handlers/debug_handler.rb"
   
   puts "Done!"
 elsif ARGV.length >= 1
@@ -59,9 +63,9 @@ elsif ARGV.length >= 1
   end
   exec "script/daemon-runner #{ARGV.map {|a| a.include?(" ") ? "\"#{a}\"" : a }.join(" ")}"
 else
-  if !File.exist?("script/run")
+  if !File.exist?("script/client")
     puts "Woops! This isn't a marvin directory."
     exit(1)
   end
-  exec "script/run"
+  exec "script/client"
 end

data/config/connections.yml.sample

@@ -0,0 +1,5 @@
+"irc.freenode.net":
+    port: 6667
+    channels:
+      - "#marvin-testing"
+      - "#relayrelay"

data/config/settings.yml.sample

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

data/config/setup.rb

@@ -9,6 +9,11 @@ Marvin::Loader.before_connecting do
   # Example Handler use.
   # LoggingHandler.register! if Marvin::Settings.use_logging
   
-  HelloWorld.register!
+  if Marvin::Loader.type == :client
+    Marvin::Distributed::DispatchHandler.register!
+  else
+    HelloWorld.register!
+    DebugHandler.register!
+  end
   
 end

data/handlers/debug_handler.rb

@@ -0,0 +1,5 @@
+# Used for debugging stuff - trying
+# adding misc stuff to play around with it
+class DebugHandler < Marvin::Base
+  
+end

data/handlers/hello_world.rb

@@ -3,7 +3,7 @@ class HelloWorld < Marvin::CommandHandler
   exposes :hello
   
   def hello(data)
-    reply "Hola!" unless target == "#all"
+    reply "Hola from process with pid #{Process.pid}!"
   end
   
 end

data/lib/marvin.rb

@@ -8,8 +8,17 @@ require 'marvin/core_ext'
 require 'marvin/exceptions'
 
 module Marvin
+  module VERSION
+    MAJOR = 0
+    MINOR = 1
+    PATCH = 20081120
+    
+    STRING = [MAJOR, MINOR, PATCH].join(".")
+  end
+  
   autoload :Util,             'marvin/util'
   autoload :Dispatchable,     'marvin/dispatchable'
+  autoload :Distributed,      'marvin/distributed'
   autoload :AbstractClient,   'marvin/abstract_client'
   autoload :Base,             'marvin/base'
   autoload :ClientMixin,      'marvin/client_mixin'
@@ -22,6 +31,7 @@ module Marvin
   autoload :DRBHandler,       'marvin/drb_handler'
   autoload :DataStore,        'marvin/data_store'
   autoload :ExceptionTracker, 'marvin/exception_tracker'
+  autoload :Options,          'marvin/options'
   # Parsers
   autoload :AbstractParser,   'marvin/abstract_parser'
   autoload :Parsers,          'marvin/parsers.rb'
@@ -31,14 +41,8 @@ module Marvin
   
   Settings.setup # Load Settings etc.
   
-end
-
-def p(text)
-  res = Marvin::Parsers::SimpleParser.parse(text)
-  if res.blank?
-    puts "Unrecognized Result"
-  else
-    STDOUT.puts "Event: #{res.to_incoming_event_name}"
-    STDOUT.puts "Args:  #{res.to_hash.inspect}"
+  def self.version
+    VERSION::STRING
   end
+  
 end

data/lib/marvin/abstract_client.rb

@@ -7,8 +7,17 @@ module Marvin
     
     include Marvin::Dispatchable
     
+    def initialize(opts = {})
+      self.original_opts    = opts.dup # Copy the options so we can use them to reconnect.
+      self.server           = opts[:server]
+      self.port             = opts[:port]
+      self.default_channels = opts[:channels]
+      self.nicks            = opts[:nicks] || []
+      self.pass             = opts[:pass]
+    end
+    
     cattr_accessor :events, :configuration, :logger, :is_setup, :connections
-    attr_accessor  :channels, :nickname
+    attr_accessor  :channels, :nickname, :server, :port, :nicks, :pass, :disconnect_expected, :original_opts
     
     # Set the default values for the variables
     self.events                 = []
@@ -22,19 +31,25 @@ module Marvin
     # call #client= on each handler if they respond to it.
     def process_connect
       self.class.setup
-      logger.debug "Initializing the current instance"
+      logger.info "Initializing the current instance"
       self.channels = []
       self.connections << self
-      logger.debug "Setting the client for each handler"
+      logger.info "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"
+      logger.info "Dispatching the default :client_connected event"
       dispatch :client_connected
     end
     
     def process_disconnect
+      logger.info "Handling disconnect for #{self.server}:#{self.port}"
       self.connections.delete(self) if self.connections.include?(self)
       dispatch :client_disconnected
-      Marvin::Loader.stop! if self.connections.blank?
+      unless self.disconnect_expected
+        logger.warn "Lost connection to server - adding reconnect"
+        self.class.add_reconnect self.original_opts
+      else
+        Marvin::Loader.stop! if self.connections.blank?
+      end
     end
     
     # Sets the current class-wide settings of this IRC Client
@@ -51,11 +66,6 @@ module Marvin
     # 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
@@ -80,40 +90,39 @@ module Marvin
     # 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"
+      logger.info "About to handle client connected"
+      # If the pass is set
+      unless self.pass.blank?
+        logger.info "Sending pass for connection"
+        command :pass, self.pass
+      end
       # 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
+      logger.info "Setting default nickname"
+      default_nickname = self.nicks.shift
       nick default_nickname
-      logger.debug "sending user command"
+      logger.info "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
+    
+    def default_channels
+      @default_channels ||= []
+    end
+    
+    def default_channels=(channels)
+      @default_channels = channels.to_a.map { |c| c.to_s }
+    end
+    
+    def nicks
+      if @nicks.blank? && !@nicks_loaded
+        logger.info "Setting default nick list"
+        @nicks = []
+        @nicks << self.configuration.nick
+        @nicks += self.configuration.nicks.to_a unless self.configuration.nicks.blank?
+        @nicks_loaded
       end
+      return @nicks
     end
     
     # The default response for PING's - it simply replies
@@ -126,9 +135,43 @@ module Marvin
     # TODO: Get the correct mapping for a given
     # Code.
     def handle_incoming_numeric(opts = {})
+      case opts[:code]
+        when Marvin::IRC::Replies[:RPL_WELCOME]
+          handle_welcome
+        when Marvin::IRC::Replies[:ERR_NICKNAMEINUSE]
+          handle_nick_taken
+      end
       code = opts[:code].to_i
       args = Marvin::Util.arguments(opts[:data])
-      dispatch :incoming_numeric_processed, {:code => code, :data => args}
+      dispatch :incoming_numeric_processed, :code => code, :data => args
+    end
+    
+    def handle_welcome
+      logger.info "Say hello to my little friend - Got welcome"
+      # 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 IF they're already set
+      # Note that Marvin::IRC::Client.connect will set them AFTER this stuff is run.
+      self.default_channels.each { |c| self.join(c) }
+    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_nick_taken
+      logger.info "Nickname '#{self.nickname}' on #{self.server} taken, trying next." 
+      logger.info "Available Nicknames: #{self.nicks.empty? ? "None" : self.nicks.join(", ")}"
+      if !self.nicks.empty?
+        logger.info "Getting next nickname to switch"
+        next_nick = self.nicks.shift # Get the next nickname
+        logger.info "Attemping to set nickname to '#{next_nick}'"
+        nick next_nick
+      else
+        logger.fatal "No Nicknames available - QUITTING"
+        quit
+      end
     end
     
     ## General IRC Functions
@@ -141,13 +184,14 @@ module Marvin
       # First, get the appropriate command
       name = name.to_s.upcase
       args = args.flatten.compact
-      irc_command = "#{name} #{args.join(" ").strip} \r\n"
+      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.
+      # TODO: Refactor to only add the channel when we receive confirmation we've joined.
       self.channels << channel
       command :JOIN, channel
       logger.info "Joined channel #{channel}"
@@ -166,13 +210,14 @@ module Marvin
     end
     
     def quit(reason = nil)
-      logger.debug "Preparing to part from #{self.channels.size} channels"
+      self.disconnect_expected = true
+      logger.info "Preparing to part from #{self.channels.size} channels"
       self.channels.to_a.each do |chan|
-        logger.debug "Parting from #{chan}"
+        logger.info "Parting from #{chan}"
         self.part chan, reason
       end
-      logger.debug "Parted from all channels, quitting"
-      command :quit
+      logger.info "Parted from all channels, quitting"
+      command  :quit
       dispatch :quit
       # Remove the connections from the pool
       self.connections.delete(self)