mattly-datagrammer 0.1.1

data/README.mkdn

@@ -0,0 +1,38 @@
+# Datagrammer
+
+by Matthew Lyon <matt@flowerpowered.com>
+
+## DESCRIPTION:
+
+Datagrammer helps take the pain out of UDP by mitigating some of the packet
+encoding/decoding stuff, as well as providing a non-blocking listening thread.
+
+## FEATURES
+
+- Encodes/Decodes OSC-style packets (where a main 'address' is given along 
+  with typed arguments)
+- Listens for messages in its own thread, performs a callback when a 
+  message is received.
+- Has a default "speaking" address / port for talkback. the IP of the sender
+  of a received packet is also made available to the callback.
+  
+# SYNOPSIS
+
+    require 'datagrammer'
+    
+    server = Datagrammer.new(5000)
+    server.listen do |serv, msg, sender| 
+      serv.speak("thanks for your message #{sender}, I received: #{msg.join(', ')}")
+    end
+    
+    # set to speak at server's default speak destination
+    client = Datagrammer.new(5001, :speak_port => 5000) 
+    client.listen {|serv, msg| puts "rec'd #{msg}"}
+    
+    client.speak(%w(hey joe))
+    sleep 0.1
+    # rec'd thanks for your message 127.0.0.1, I received: hey, joe
+
+## REQUIREMENTS
+
+* Rspec, if you wish to run the spec suite

data/Rakefile

@@ -0,0 +1,5 @@
+require "rake"
+Dir['tasks/**/*.rake'].each { |rake| load rake }
+
+desc "Run the specs."
+task :default => :spec

data/lib/datagrammer/packet.rb

@@ -0,0 +1,60 @@
+require 'strscan'
+
+class Datagrammer
+  module Packet
+    
+    def self.decode(packet_string='')
+      scanner = StringScanner.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
+      end
+      arguments.unshift(message)
+    end
+    
+    def self.encode(message=[])
+      message = [message].flatten
+      string = pad(message.shift)
+      string += encode_arguments(message)
+    end
+    
+    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
+    
+    def self.encode_argument_types(arguments)
+      str = ','
+      str += arguments.collect do |argument|
+        case argument
+        when String; 's' 
+        when Integer; 'i'
+        when Float; 'f'
+        end
+      end.join
+      pad(str)
+    end
+    
+    def self.encode_argument_data(arguments)
+      arguments.collect do |argument|
+        case argument
+        when String; pad(argument)
+        when Integer; [argument].pack('N')
+        when Float; [argument].pack('g')
+        end
+      end.join
+    end
+  end
+end

data/lib/datagrammer/packet_scanner.rb

@@ -0,0 +1,27 @@
+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
+    
+  end
+end
+
+StringScanner.send(:include, Datagrammer::PacketScanner)

data/lib/datagrammer.rb

@@ -0,0 +1,53 @@
+require 'socket'
+
+$:.unshift File.dirname(__FILE__)
+require 'datagrammer/packet'
+require 'datagrammer/packet_scanner'
+
+# 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
+# a callback when data is received:
+#
+#   dg = Datagrammer.new(5000)
+#   dg.listen {|d, message, sender| d.speak %|rec'd "#{message.join(', ')}" at #{Time.now.to_s} from #{sender}|}
+#   dg.thread.join
+#   # now, anything sent to port 5000 on 0.0.0.0 that conforms to a basic
+#   # 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
+  
+  # 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"
+  # * (({:speak_port})): default port to speak on, defaults to port + 1
+  def initialize(port, opts={})
+    @port          = port
+    @address       = opts[:address] || "0.0.0.0"
+    @speak_address = opts[:speak_address] || "0.0.0.0"
+    @speak_port    = opts[:speak_port] || port + 1
+    @socket        = UDPSocket.new
+    @socket.bind(@address, @port)
+  end
+  
+  def speak_destination=(addr, port)
+    @speak_address, @speak_port = addr, port
+  end
+  
+  attr_accessor :thread, :socket, :speak_address, :speak_port
+  
+  def listen(&block)
+    @thread = Thread.start do
+      loop do
+        IO.select([@socket])
+        data, info = @socket.recvfrom(65535)
+        block.call(self, Packet.decode(data), info.last)
+      end
+    end
+  end
+  
+  def speak(message, addr=@speak_address, port=@speak_port)
+    @socket.send(Packet.encode([message]), 0, addr, port)
+  end
+  
+end

data/spec/datagrammer_spec.rb

@@ -0,0 +1,36 @@
+require File.dirname(__FILE__) + '/spec_helper.rb'
+
+describe Datagrammer do
+  
+  before do
+    @serv = Datagrammer.new(10000)
+  end
+  
+  after do
+    @serv.socket.close
+  end
+  
+  def setup_socket(port, addr="0.0.0.0")
+    s = UDPSocket.new
+    s.bind(addr, port)
+    s
+  end
+  
+  it "should send an encoded packet out to its speaking port" do
+    Thread.start { sleep 0.1; @serv.speak("hi") }
+    sock = setup_socket(10001)
+    IO.select [sock]
+    data, info = sock.recvfrom(1024)
+    sock.close
+    data.should == "hi\000\000,\000\000\000"
+  end
+  
+  it "should receive encoded packets while listening and feed it to the callback" do
+    @serv.listen {|dg, msg| @foo = msg }
+    s = UDPSocket.new
+    s.send("hi\000\000,\000\000\000", 0, '0.0.0.0', 10000)
+    sleep 0.1
+    @foo.should == ['hi']
+  end
+  
+end

data/spec/packet_scanner_spec.rb

@@ -0,0 +1,70 @@
+require File.dirname(__FILE__) + '/spec_helper.rb'
+
+describe StringScanner do
+  
+  describe "skip_buffer" do
+    it "sets the position to the next multiple of four" do
+      s = StringScanner.new('more than four bytes')
+      [[4,8], [6,8], [1,4]].each do |pos, expected|
+        s.pos = pos
+        s.skip_buffer
+        s.pos.should == expected
+      end
+    end
+  end
+  
+  describe "scan_string" do
+    
+    before do
+      @s = StringScanner.new("this is a string!\000\000\000end.")
+      @string = @s.scan_string
+    end
+    
+    it "extracts the string" do
+      @string.should == "this is a string!"
+    end
+    
+    it "sets the position to the next word" do
+      @s.pos.should == 20
+    end
+  end
+  
+  describe "scan_integer" 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)
+          @int = @s.scan_integer
+        end
+        
+        it "decodes the integer correctly" do
+          @int.should == integer
+        end
+        
+        it "sets the position at the end of the word" do
+          @s.pos.should == 4
+        end
+      end
+    end
+  end
+  
+  describe "scan_float" 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)
+          @float = @s.scan_float
+        end
+        
+        it "decodes the float value correctly" do
+          (@float * 100000).round.should == (float * 100000).round
+        end
+        
+        it "sets the position to the end of the word" do
+          @s.pos.should == 4
+        end
+      end
+    end
+  end
+  
+end

data/spec/packet_spec.rb

@@ -0,0 +1,53 @@
+require File.dirname(__FILE__) + '/spec_helper.rb'
+
+describe Datagrammer::Packet do
+  describe "decode" do
+    it "handles a message with no arguments" do
+      Datagrammer::Packet.decode("hello\000\000\000,\000\000\000").should == ['hello']
+    end
+    
+    it "handles a generic message with many arguments" do
+      encoded = "message\000,sifii\000\000str1\000\000\000\000\000\000\000\001@I\016V\177\377\377\377\377\377\377\366"
+      msg = Datagrammer::Packet.decode(encoded)
+      msg.shift.should == 'message'
+      msg.shift.should == 'str1'
+      msg.shift.should == 1
+      (msg.shift * 10000).round.should == 31415
+      msg.shift.should == 2147483647
+      msg.shift.should == -10
+    end
+    
+    it "handes a message with only integer arguments" do
+      encoded = "/tick\000\000\000,iiii\000\000\000\000\000\000\252\000\000\000\002\000\000\001\245\000\004\367\006"
+      Datagrammer::Packet.decode(encoded).should == ['/tick', 170, 2, 421, 325382]
+    end
+    
+    it "handles encoded newlines correctly" do
+      encoded = "tick\n\000\000\000,ii\000\000\000\000\n\000\000\334\n"
+      Datagrammer::Packet.decode(encoded).should == ["tick\n", 10, 56330]
+    end
+  end
+  
+  describe "encode" do
+    [ [['hello'], "hello\000\000\000,\000\000\000"],
+      [['hello','world'], "hello\000\000\000,s\000\000world\000\000\000"],
+      [['hello', 'world', 1, 2.0], "hello\000\000\000,sif\000\000\000\000world\000\000\000\000\000\000\001@\000\000\000"]
+    ].each do |message, expected|
+      describe "message: #{message.join(', ')}" do
+        it "properly formats" do
+          Datagrammer::Packet.encode(message).should == expected
+        end
+      end
+    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

data/spec/spec_helper.rb

@@ -0,0 +1,15 @@
+require 'rubygems'
+
+begin
+  require 'spec'
+rescue LoadError
+  gem 'rspec'
+  require 'spec'
+end
+
+gem 'ruby-debug'
+require 'ruby-debug'
+
+require "#{File.dirname(__FILE__)}/../lib/datagrammer"
+
+Debugger.start

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification 
+name: mattly-datagrammer
+version: !ruby/object:Gem::Version 
+  version: 0.1.1
+platform: ruby
+authors: 
+- Matthew Lyon
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-10-19 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: Sends and receives UDP packets in an OSC-compatable encoded format.
+email: matt@flowerpowered.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.mkdn
+- Rakefile
+- spec/datagrammer_spec.rb
+- spec/packet_scanner_spec.rb
+- spec/packet_spec.rb
+- spec/spec_helper.rb
+- lib/datagrammer
+- lib/datagrammer/packet.rb
+- lib/datagrammer/packet_scanner.rb
+- lib/datagrammer.rb
+has_rdoc: false
+homepage: http://github.com/mattly/datagrammer
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: 1.8.6
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: UDP without the pain
+test_files: []
+