Sutto-marvin 0.1.20081115 → 0.1.20081120

data/README.textile

@@ -7,39 +7,24 @@ 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):
+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:
 
@@ -52,30 +37,47 @@ You can create a new marvin folder:
 Then simply edit your settings in the +config/settings.yml+
 
   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
-
-You can use the defaults or configure it. By default your marvin bot will not 
-do any logging. You will need to set that up. From this point you can begin
-running the bot as a daemon or as a console application:
-
-  $ ./script/run
-
-The bot should join the specified channel and will resond to some simple
+    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!
+  *YourName*: MarvinBot3000: hello
+  *MarvinBot3000*: YourName: Hola!
+  
+As defined in handlers/hello_world.rb
 
 h2. Marvin::Base - A handler starting point
 
@@ -98,13 +100,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
@@ -120,7 +124,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
 
@@ -128,9 +140,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
 
@@ -149,7 +162,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

@@ -10,5 +10,6 @@ Marvin::Loader.before_connecting do
   # LoggingHandler.register! if Marvin::Settings.use_logging
   
   HelloWorld.register!
+  DebugHandler.register!
   
 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!"
   end
   
 end

data/lib/marvin.rb

@@ -22,6 +22,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'

data/lib/marvin/abstract_client.rb

@@ -7,8 +7,16 @@ module Marvin
     
     include Marvin::Dispatchable
     
+    def initialize(opts = {})
+      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
     
     # Set the default values for the variables
     self.events                 = []
@@ -22,16 +30,17 @@ 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?
@@ -51,11 +60,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 +84,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 +129,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,7 +178,7 @@ 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
     
@@ -166,13 +203,13 @@ module Marvin
     end
     
     def quit(reason = nil)
-      logger.debug "Preparing to part from #{self.channels.size} channels"
+      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)