mattly-datagrammer 0.1.1 → 0.2

data/lib/datagrammer.rb

@@ -3,6 +3,7 @@ require 'socket'
 $:.unshift File.dirname(__FILE__)
 require 'datagrammer/packet'
 require 'datagrammer/packet_scanner'
+require 'datagrammer/generic_handler'
 
 # A Datagrammer object will listen on a given address and port for messages and
 # will decode the data (it's assumed to be in a OSC-style format) and perform
@@ -15,8 +16,9 @@ require 'datagrammer/packet_scanner'
 #   # OSC-style packet (f.e. from Max/MSP's udpsender) will be echoed back on port
 #   # 5001 in the string format given in the block.
 class Datagrammer
+  attr_accessor :thread, :socket, :speak_address, :speak_port
   
-  # creates a new Datagrammer object bound to the specified port. The following
+  # Creates a new Datagrammer object bound to the specified port. The following
   # options are available:
   # * (({:address})): IP to listen on. defaults to "0.0.0.0"
   # * (({:speak_address})): default IP to send to. defaults to "0.0.0.0"
@@ -24,18 +26,20 @@ class Datagrammer
   def initialize(port, opts={})
     @port          = port
     @address       = opts[:address] || "0.0.0.0"
-    @speak_address = opts[:speak_address] || "0.0.0.0"
+    @speak_address = opts[:speak_address] || @address
     @speak_port    = opts[:speak_port] || port + 1
     @socket        = UDPSocket.new
     @socket.bind(@address, @port)
   end
   
+  # Sets the default speak destination
   def speak_destination=(addr, port)
     @speak_address, @speak_port = addr, port
   end
   
-  attr_accessor :thread, :socket, :speak_address, :speak_port
-  
+  # Starts the thread to listen on the selected port. A block is required, that will get
+  # three arguments: the datagrammer object itself, the packet data (as an array), and the 
+  # address of the sender.
   def listen(&block)
     @thread = Thread.start do
       loop do
@@ -46,6 +50,7 @@ class Datagrammer
     end
   end
   
+  # Encodes and sends a packet to the specified address and port
   def speak(message, addr=@speak_address, port=@speak_port)
     @socket.send(Packet.encode([message]), 0, addr, port)
   end

data/lib/datagrammer/generic_handler.rb

@@ -0,0 +1,54 @@
+class Datagrammer
+  # A simple class for registering multiple "handlers" for messages that come from a Datagrammer object.
+  class GenericHandler
+    attr_accessor :rules
+    
+    # Takes a hash of key, proc values for an initial set of rules. Rule keys are matched
+    # against the first item in the "data" value passed in from Datagrammer, or the
+    # so-called "path" of the message. Data like (({['/foo/bar', 'baz', 'bee']})) would
+    # use "/foo/bar" as the path to match against.
+    #
+    # Rules are evaluated in this order:
+    # * If a rule key is a string and it matches the path exactly, that rule will be used.
+    # * If no string rule keys match, any rule keys that are regexes will be run against the 
+    #   path and ALL regexes that match will be called. The match(es) from the regex will be
+    #   prepended to the argument list passed to the proc.
+    # * If there is no match yet and a rule key called '\default' exists, that rule will be used.
+    # * If no match has been made at this point, nothing will happen, the data will be ignored.
+    def initialize(rules={})
+      @rules = rules
+    end
+    
+    # sets a proc to be called when a rule is matched. See #new for more information.
+    def register_rule(address, block)
+      @rules[address] = block
+    end
+    
+    # What Datagrammer calls. Runs the path against registered rules as described in #new
+    def handle(address, arguments=[])
+      list = if @rules.has_key?(address)
+        [[@rules[address], arguments]]
+      else
+        matches = @rules.select {|k,v| k.kind_of?(Regexp) && address =~ k }
+        if ! matches.empty?
+          matches.collect do |regex, p| 
+            msg = [address.scan(regex), arguments].flatten
+            msg.delete('')
+            [p, msg]
+          end
+        elsif @rules.has_key?('\default')
+          [[@rules['\default'], arguments]]
+        else
+          []
+        end
+      end
+      list.map {|callback, args| callback.call(args) }
+    end
+    
+    # returns a lambda for a Datagrammer object's listen method
+    def handler
+      lambda {|dg, args, sender| self.handle(args.shift, args) }
+    end
+    
+  end
+end

data/lib/datagrammer/packet.rb

@@ -1,36 +1,39 @@
 require 'strscan'
 
 class Datagrammer
+  
+  # Decodes and Encodes packets into a basic OSC (Open Sound Control)-like format.
   module Packet
     
+    # decodes packet data from f.e. (({"hello\000\000\000,s\000\000world\000\000\000"})) to 
+    # (({%w(hello world)}))
     def self.decode(packet_string='')
-      scanner = StringScanner.new(packet_string)
+      scanner = PacketScanner.new(packet_string)
       message = scanner.scan_string
       argument_types = scanner.scan_string.sub(/^,/,'').split('')
-      arguments = argument_types.inject([]) do |memo, type|
-        case type
-        when 's'; memo << scanner.scan_string
-        when 'i'; memo << scanner.scan_integer
-        when 'f'; memo << scanner.scan_float
-        end
-        memo
+      arguments = argument_types.collect do |type|
+        { 's' => lambda { scanner.scan_string },
+          'i' => lambda { scanner.scan_integer },
+          'f' => lambda { scanner.scan_float }
+        }[type].call()
       end
       arguments.unshift(message)
     end
     
-    def self.encode(message=[])
+    # Turns a list or array into an encoded string
+    def self.encode(*message)
       message = [message].flatten
       string = pad(message.shift)
       string += encode_arguments(message)
     end
     
+  protected
+
     def self.pad(string='')
       string += "\000"
       string + "\000" * ((4-string.size) % 4)
     end
     
-    protected
-    
     def self.encode_arguments(arguments)
       encode_argument_types(arguments) + encode_argument_data(arguments)
     end

data/lib/datagrammer/packet_scanner.rb

@@ -1,27 +1,28 @@
-class Datagrammer
-  module PacketScanner
-    
-    def skip_buffer
-      self.pos += 4 - (pos % 4)
-    end
-    
-    def scan_string
-      string = scan(/[^\000]+/)
-      skip_buffer
-      string
-    end
-    
-    def scan_integer
-      integer = scan(/.{4}/m).unpack('N').first
-      integer = -1 * (2**32 - integer) if integer > (2**31 - 1)
-      integer
-    end
-    
-    def scan_float
-      scan(/.{4}/).unpack('g').first
-    end
-    
+# Subclass of StringScanner to take the boring out of certain aspects of packet decoding.
+class PacketScanner < StringScanner
+  
+  # Moves the scan head to the next multiple of 4
+  def skip_buffer
+    self.pos += 4 - (pos % 4)
   end
+  
+  # Grabs all non-null characters and moves the scan head past the null buffer
+  def scan_string
+    string = scan(/[^\000]+/)
+    skip_buffer
+    string
+  end
+  
+  # Decodes an integer, adjusting for polarity
+  def scan_integer
+    integer = scan(/.{4}/m).unpack('N').first
+    integer = -1 * (2**32 - integer) if integer > (2**31 - 1)
+    integer
+  end
+  
+  # Decodes a 32-bit float
+  def scan_float
+    scan(/.{4}/).unpack('g').first
+  end
+  
 end
-
-StringScanner.send(:include, Datagrammer::PacketScanner)

data/spec/generic_handler_spec.rb

@@ -0,0 +1,60 @@
+require File.dirname(__FILE__) + '/spec_helper.rb'
+
+describe Datagrammer::GenericHandler do
+  
+  before do
+    @handler = Datagrammer::GenericHandler.new
+    @foo = lambda {|args| "foo: #{args.join(', ')}" }
+    @handler.register_rule('/foo', @foo)
+  end
+  
+  it "registers handlers" do
+    @handler.rules['/foo'].should == @foo
+  end
+  
+  it "calls the handler for a given address" do
+    @handler.handle('/foo', %w(bar baz)).should == ["foo: bar, baz"]
+  end
+  
+  it "spits out a lambda for calling the handler from DG" do
+    @handler.should_receive(:handle).with('/foo',%w(bar baz))
+    @handler.handler.call(nil, %w(/foo bar baz), nil)
+  end
+  
+  describe "regex handlers" do
+    before do
+      @i = Hash.new {|hash, key| hash[key] = [] }
+      @handler.register_rule(/^\/reg\/(.*)$/, lambda {|a| @i[a.shift] += a})
+    end
+
+    it "accepts regexes as hanlder keys and calls their values when matched" do
+      @handler.handle('/reg/foo', %w(bar baz))
+      @i.should == {'foo' => %w(bar baz)}
+    end
+    
+    it "handles values for ALL regexes that match given string" do
+      @handler.register_rule(/.*/, lambda {|a| @i['default'] += a })
+      @handler.handle('/reg/foo', %w(bar baz))
+      @i.should == {'foo' => %w(bar baz), 'default' => %w(/reg/foo bar baz)}
+    end
+    
+    it "does not use regexes if exact match from string" do
+      @handler.register_rule('/reg/foo', lambda {|a| @i['exact'] += a })
+      @handler.handle('/reg/foo', %w(bar baz))
+      @i.should == {'exact' => %w(bar baz)}
+    end
+  end
+  
+  describe "no handler found" do
+    it "uses 'default' if exists" do
+      default = lambda { 'default' }
+      @handler.register_rule('\default', default)
+      @handler.handle('/non-existant').should == ['default']
+    end
+  
+    it "does nothing if no default handler" do
+      @handler.handle('/non-existant').should == []
+    end
+  end
+  
+end

data/spec/packet_scanner_spec.rb

@@ -1,10 +1,10 @@
 require File.dirname(__FILE__) + '/spec_helper.rb'
 
-describe StringScanner do
+describe PacketScanner do
   
   describe "skip_buffer" do
     it "sets the position to the next multiple of four" do
-      s = StringScanner.new('more than four bytes')
+      s = PacketScanner.new('more than four bytes')
       [[4,8], [6,8], [1,4]].each do |pos, expected|
         s.pos = pos
         s.skip_buffer
@@ -16,7 +16,7 @@ describe StringScanner do
   describe "scan_string" do
     
     before do
-      @s = StringScanner.new("this is a string!\000\000\000end.")
+      @s = PacketScanner.new("this is a string!\000\000\000end.")
       @string = @s.scan_string
     end
     
@@ -33,7 +33,7 @@ describe StringScanner do
     [[1,"\000\000\000\001"], [-10, "\377\377\377\366"], [2147483647, "\177\377\377\377"]].each do |integer, encoded|
       describe "decdoing #{integer}" do
         before do
-          @s = StringScanner.new(encoded)
+          @s = PacketScanner.new(encoded)
           @int = @s.scan_integer
         end
         
@@ -52,7 +52,7 @@ describe StringScanner do
     [[1.0, "?\200\000\000"], [3.141593, "@I\017\333"], [-1.618034, "\277\317\e\275"]].each do |float, encoded|
       describe "decoding #{float}" do
         before do
-          @s = StringScanner.new(encoded)
+          @s = PacketScanner.new(encoded)
           @float = @s.scan_float
         end
         

data/spec/packet_spec.rb

@@ -41,13 +41,4 @@ describe Datagrammer::Packet do
     end
   end
   
-  describe "pad" do
-    it "fills out to the nearest word length" do
-      Datagrammer::Packet.pad("h").should == "h\000\000\000"
-    end
-    
-    it "appends nulls if string is already at wordlength" do
-      Datagrammer::Packet.pad("word").should == "word\000\000\000\000"
-    end
-  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: mattly-datagrammer
 version: !ruby/object:Gem::Version 
-  version: 0.1.1
+  version: "0.2"
 platform: ruby
 authors: 
 - Matthew Lyon
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-10-19 00:00:00 -07:00
+date: 2008-11-01 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -19,20 +19,22 @@ executables: []
 
 extensions: []
 
-extra_rdoc_files: []
-
+extra_rdoc_files: 
+- README.mkdn
 files: 
 - README.mkdn
 - Rakefile
 - spec/datagrammer_spec.rb
+- spec/generic_handler_spec.rb
 - spec/packet_scanner_spec.rb
 - spec/packet_spec.rb
 - spec/spec_helper.rb
 - lib/datagrammer
+- lib/datagrammer/generic_handler.rb
 - lib/datagrammer/packet.rb
 - lib/datagrammer/packet_scanner.rb
 - lib/datagrammer.rb
-has_rdoc: false
+has_rdoc: true
 homepage: http://github.com/mattly/datagrammer
 post_install_message: 
 rdoc_options: []