rubybits 0.1.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,15 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "rspec", "~> 2.1.0"
+  gem "yard", "~> 0.6.0"
+  gem "bluecloth", "~> 2.0.9"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.5.1"
+  gem "rcov", ">= 0"
+end

data/Gemfile.lock

@@ -0,0 +1,32 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    bluecloth (2.0.9)
+    diff-lcs (1.1.2)
+    git (1.2.5)
+    jeweler (1.5.1)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    rake (0.8.7)
+    rcov (0.9.9)
+    rspec (2.1.0)
+      rspec-core (~> 2.1.0)
+      rspec-expectations (~> 2.1.0)
+      rspec-mocks (~> 2.1.0)
+    rspec-core (2.1.0)
+    rspec-expectations (2.1.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.1.0)
+    yard (0.6.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bluecloth (~> 2.0.9)
+  bundler (~> 1.0.0)
+  jeweler (~> 1.5.1)
+  rcov
+  rspec (~> 2.1.0)
+  yard (~> 0.6.0)

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Micah Wylde
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,7 @@
+# RubyBits
+
+RubyBits is a library that makes dealing with binary formats easier. In
+particular, it provides the Structure class, which allows for easy parsing
+and creation of binary strings according to specific formats. More usage
+information can be found in the docs (generated by `rake yard`) or by looking
+at the specs.

data/Rakefile

@@ -0,0 +1,45 @@
+require 'rubygems'
+require 'bundler'
+begin
+	Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+	$stderr.puts e.message
+	$stderr.puts "Run `bundle install` to install missing gems"
+	exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+	# gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+	gem.name = "rubybits"
+	gem.homepage = "http://github.com/mwylde/rubybits"
+	gem.license = "MIT"
+	gem.summary = %Q{A library that makes dealing with bit strings and binary formats easier, inspired by BitStruct}
+	gem.description = %Q{RubyBits simplifies the task of parsing and generating binary strings in particular formats.}
+	gem.email = "mwylde@wesleyan.edu"
+	gem.authors = ["Micah Wylde"]
+	# Include your dependencies below. Runtime dependencies are required when using your gem,
+	# and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+	#	 gem.add_runtime_dependency 'jabber4r', '> 0.1'
+	#	 gem.add_development_dependency 'rspec', '> 1.2.3'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+	spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+	spec.pattern = 'spec/**/*_spec.rb'
+	spec.rcov = true
+end
+
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new do |t|
+	t.options = ['--no-private']
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/rubybits.rb

@@ -0,0 +1,309 @@
+# Provides various utilities for working with binary formats.
+module RubyBits
+	# Raised when you set a field to a value that is invalid for the type of
+	# the field (i.e., too large or the wrong type)
+	class FieldValueException < Exception; end
+		
+	# You can subclass RubyBits::Strcuture to define new binary formats. This
+	# can be used for lots of purposes: reading binary data, communicating in
+	# binary formats (like TCP/IP, http, etc).
+	# 
+	# Currently, three field types are supported: unsigned, signed and variable. Unsigned
+	# and signed fields are big-endian and can be any number of bits in size. Unsigned
+	# integers are assumed to be encoded with two's complement. Variable fields are binary
+	# strings with their size defined by the value of another field (given by passing that
+	# field's name to the :length option). This size is assumed to be in bits; if it is
+	# in fact in bytes, you should pass :byte to the :unit option (see the example).
+	# 
+	# @example
+	# 	class NECProjectorFormat < RubyBits::Structure
+	# 	  unsigned :id1,     8,    "Identification data assigned to each command"
+	# 	  unsigned :id2,     8,    "Identification data assigned to each command"
+	# 	  unsigned :p_id,    8,    "Projector ID"
+	# 	  unsigned :m_code,  4,    "Model code for projector"
+	# 	  unsigned :len,     12,   "Length of data in bytes"
+	# 	  variable :data,    8,    "Packet data", :length => :len, :unit => :byte
+	# 	  unsigned :checksum,8,    "Checksum"
+	# 
+	# 	  checksum :checksum do |bytes|
+	# 	    bytes[0..-2].inject{|sum, byte| sum += byte} & 255
+	# 	  end
+	#   end
+	#  	
+	#   NECProjectorFormat.parse(buffer)
+	#   # => [[<NECProjectorFormat>, <NECProjectorFormat>], rest]
+	#   
+	#   NECProjectorFormat.new(:id1 => 0x44, :id2 => 2, :p_id => 0, :m_code => 0, :len => 5, :data => "hello").to_s.bytes.to_a
+	#   # => [0x44, 0x2, 0x05, 0x00, 0x68, 0x65, 0x6C, 0x6C, 0x6F, 0x5F]
+	class Structure < Object
+		class << self
+			private
+			#@private
+			FIELD_TYPES = {
+				:unsigned => {
+					:validator => proc{|val, size, options| val.is_a?(Fixnum) && val < 2**size},
+					:unpack => proc {|s, offset, length, options|
+						number = 0
+						s_iter = s.bytes
+						byte = 0
+						# advance the iterator by the number of whole or partial bytes in the offset (offset div 8)
+						((offset.to_f/8).ceil).times{|i| byte = s_iter.next}
+						
+						length.times{|bit|
+							byte = s_iter.next if offset % 8 == 0
+							src_bit = (7-offset%8)
+							number |= (1 << (length-1-bit)) if (byte & (1 << src_bit)) > 0
+							#puts "Reading: #{src_bit} from #{"%08b" % byte} => #{(byte & (1 << src_bit)) > 0 ? 1 : 0}"
+							offset += 1
+						}
+						number
+					}
+				},
+				:signed => {
+					:validator => proc{|val, size, options| val.is_a?(Fixnum) && val.abs < 2**(size-1)},
+					:unpack => proc{|s, offset, length, options|
+						number = 0
+						s_iter = s.bytes
+						byte = 0
+						# advance the iterator by the number of whole bytes in the offset (offset div 8)
+						((offset.to_f/8).ceil).times{|i| byte = s_iter.next}
+						# is this a positive number? yes if the most significant bit is 0
+						byte = s_iter.next if offset % 8 == 0
+						pos = byte & (1 << 7 - offset%8) == 0
+						#puts "String: #{s.bytes.to_a.collect{|x| "%08b" % x}.join(" ")}"
+						#puts "Byte: #{"%08b" % byte}, offset: #{offset}"
+						
+						length.times{|bit|
+							byte = s_iter.next if offset % 8 == 0 && bit > 7
+							src_bit = (7-offset%8)
+							number |= (1 << (length-1-bit)) if ((byte & (1 << src_bit)) > 0) ^ (!pos)
+							offset += 1
+						}
+						#puts "Pos #{pos}, number: #{number}"
+						pos ? number : -number-1
+					}
+				},
+				:variable => {
+					:validator => proc{|val, size, options| val.is_a?(String)},
+					:unpack => proc{|s, offset, length, options|
+						output = []
+						s_iter = s.bytes
+						byte = 0
+						# advance the iterator by the number of whole bytes in the offset (offset div 8)
+						((offset.to_f/8).ceil).times{|i| byte = s_iter.next}
+						length.times{|bit|
+							byte = s_iter.next if offset % 8 == 0
+							output << 0 if bit % 8 == 0
+							
+							src_bit = (7-offset%8)
+							output[-1] |= (1 << (7-bit%8)) if (byte & (1 << src_bit)) > 0
+							offset += 1
+						}
+						output.pack("c*")
+					}
+				}
+			}
+			FIELD_TYPES.each{|kind, field|
+				define_method kind do |name, size, description, *options|
+					field(kind, name, size, description, field[:validator], options[0])
+				end
+			}
+			
+			define_method :variable do |name, description, *options|
+				field(:variable, name, nil, description, FIELD_TYPES[:variable][:validator], options[0])
+			end
+			
+			public 
+			# Sets the checksum field. Setting a checksum field alters the functionality
+			# in several ways: the checksum is automatically calculated and set, and #parse
+			# will only consider a bitstring to be a valid instance of the structure if it
+			# has a checksum appropriate to its data.
+			# @param field [Symbol] the field that contains the checksum data
+			# @yield [bytes] block that should calculate the checksum given bytes, which is
+			# 	an array of bytes representing the full structure, with the checksum field
+			# 	set to 0
+			def checksum field, &block
+				@_checksum_field = [field, block]
+				self.class_eval %{
+					def #{field}
+						calculate_checksum unless @_calculating_checksum || @_checksum_cached
+						@__#{field}
+					end
+				}
+			end
+			
+			# A list of the fields in the class
+			def fields; @_fields; end
+			
+			# The checksum field
+			def checksum_field; @_checksum_field; end
+			
+			# Determines whether a string is a valid message
+			# @param string [String] a binary string to be tested
+			# @return [Boolean] whether the string is in fact a valid message
+			def valid_message? string
+				!!from_string(string)[0]
+			end
+			
+			# Parses a message from the binary string assuming that the message starts at the first byte
+			# of the string
+			# @param string [String] a binary string to be interpreted
+			# @return [Array<Structure, string>] a pair with the first element being a structure object with 
+			# 	the data from the input string (or nil if not a valid structure) and the second being the
+			# 	left-over bytes from the string (those after the message or the entire string if no valid
+			# 	message was found)
+			def from_string(string)
+				message = self.new
+				iter = 0
+				checksum = nil
+				fields.each{|field|
+					kind, name, size, description, options = field
+					options ||= {}
+					size = (kind == :variable) ? message.send(options[:length]) : size
+					size *= 8 if options[:unit] == :byte
+					begin
+						value = FIELD_TYPES[kind][:unpack].call(string, iter, size, options)
+						message.send("#{name}=", value)
+						checksum = value if checksum_field && name == checksum_field[0]
+					rescue StopIteration, FieldValueException => e
+						return [nil, string]
+					end
+					iter += size
+				}
+				# if there's a checksum, make sure the provided one is valid
+				return [nil, string] unless message.checksum == checksum if checksum_field
+				[message, string[((iter/8.0).ceil)..-1]]
+			end
+			
+			# Parses out all of the messages in a given string assuming that the first message
+			# starts at the first byte, and there are no bytes between messages (though messages
+			# are not allowed to span bytes; i.e., all messages must be byte-aligned).
+			# @param string [String] a binary string containing the messages to be parsed
+			# @return [Array<Array<Structure>, String>] a pair with the first element being an
+			# 	array of messages parsed out of the string and the second being whatever part of
+			# 	the string was left over after parsing.
+			def parse(string)
+				messages = []
+				last_message = true
+				while last_message
+					last_message, string = from_string(string)
+					#puts "Found message: #{last_message.to_s.bytes.to_a}, string=#{string.bytes.to_a.inspect}"
+					messages << last_message if last_message
+				end
+				[messages, string]
+			end
+
+			private
+			def field kind, name, size, description, validator, options
+				@_fields ||= []
+				@_fields << [kind, name, size, description, options]
+				self.class_eval do
+					define_method "#{name}=" do |val|
+						raise FieldValueException unless validator.call(val, size, options)
+						self.instance_variable_set("@__#{name}", val)
+						@_checksum_cached = false
+					end
+				end
+				unless checksum_field && checksum_field[0] == name
+					self.class_eval %{
+						def #{name}
+							@__#{name}
+						end
+					}
+				end
+			end
+		end
+		
+		# Creates a new instance of the class. You can pass in field names to initialize to
+		# set their values.
+		# @example
+		# 	MyStructure.new(:field1 => 44, :field2 => 0x70, :field3 => "hello")
+		def initialize(values={})
+			values.each{|key, value|
+				self.send "#{key}=", value
+			}
+			@_checksum_cached = false
+		end
+				
+		# Returns a binary string representation of the structure according to the fields defined
+		# and their current values.
+		# @return [String] bit string representing struct
+		def to_s
+			if self.class.checksum_field && !@_checksum_cached
+				self.calculate_checksum
+			end
+			to_s_without_checksum
+		end
+		
+		# Calculates and sets the checksum bit according to the checksum field defined by #checksum
+		def calculate_checksum
+			if self.class.checksum_field
+				@_calculating_checksum = true
+				self.send("#{self.class.checksum_field[0]}=", 0)
+				checksum = self.class.checksum_field[1].call(self.to_s_without_checksum.bytes.to_a)
+				self.send("#{self.class.checksum_field[0]}=", checksum)
+				@_checksum_cached = true
+				@_calculating_checksum = false
+			end
+		end
+		
+		protected				
+		# Returns the input number with the specified bit set to the specified value
+		# @param byte [Fixnum] Number to be modified
+		# @param bit [Fixnum] Bit number to be set 
+		# @param value [Fixnum: {0, 1}] Value to set (either 0 or 1)
+		# @return [Fixnum] byte with bit set to value
+		def set_bit(byte, bit, value)
+			#TODO: this can probably be made more efficient
+			byte & (1<<bit) > 0 == value > 0 ? byte : byte ^ (1<<bit)
+		end
+		
+		# Returns the value at position bit of byte
+		# @param number [Fixnum] Number to be queried
+		# @param bit [Fixnum] bit of interest
+		# @return [Fixnum: {0, 1}] 0 or 1, depending on the value of the bit at position bit of number
+		def get_bit(number, bit)
+			number & (1<<bit) > 0 ? 1 : 0
+		end
+		
+		def to_s_without_checksum
+			offset = 0
+			buffer = []
+			# This method works by iterating through each bit of each field and setting the bits in
+			# the current output byte appropriately.
+			self.class.fields.each{|field|
+				kind, name, size, description, options = field
+				data = self.send(name)
+				options ||= {}
+				case kind
+				when :variable
+					data ||= ""
+					size = options[:length] && self.send(options[:length]) ? self.send(options[:length]) : data.size
+					size *= 8 if options[:unit] == :byte
+					byte_iter = data.bytes
+					if offset % 8 == 0
+						buffer += data.bytes.to_a + [0] * (size - data.size)
+					else
+						size.times{|i|
+							byte = byte_iter.next rescue 0
+							8.times{|bit|
+								buffer << 0 if offset % 8 == 0
+								buffer[-1] |= get_bit(byte, 7-bit) << 7-(offset % 8)
+								offset += 1
+							}
+						}
+					end
+				else
+					data ||= 0
+					size.times do |bit|
+						buffer << 0 if offset % 8 == 0
+						buffer[-1] |= get_bit(data, size-bit-1) << 7-(offset % 8)
+						offset += 1
+					end
+				end
+			}
+			buffer.pack("c*")	
+		end
+	end
+	
+end

data/rubybits.gemspec

@@ -0,0 +1,71 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{rubybits}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Micah Wylde"]
+  s.date = %q{2010-11-27}
+  s.description = %q{RubyBits simplifies the task of parsing and generating binary strings in particular formats.}
+  s.email = %q{mwylde@wesleyan.edu}
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.md"
+  ]
+  s.files = [
+    ".document",
+    ".rspec",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.txt",
+    "README.md",
+    "Rakefile",
+    "VERSION",
+    "lib/rubybits.rb",
+    "rubybits.gemspec",
+    "spec/rubybits_spec.rb",
+    "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/mwylde/rubybits}
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{A library that makes dealing with bit strings and binary formats easier, inspired by BitStruct}
+  s.test_files = [
+    "spec/rubybits_spec.rb",
+    "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rspec>, ["~> 2.1.0"])
+      s.add_development_dependency(%q<yard>, ["~> 0.6.0"])
+      s.add_development_dependency(%q<bluecloth>, ["~> 2.0.9"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.5.1"])
+      s.add_development_dependency(%q<rcov>, [">= 0"])
+    else
+      s.add_dependency(%q<rspec>, ["~> 2.1.0"])
+      s.add_dependency(%q<yard>, ["~> 0.6.0"])
+      s.add_dependency(%q<bluecloth>, ["~> 2.0.9"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.5.1"])
+      s.add_dependency(%q<rcov>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<rspec>, ["~> 2.1.0"])
+    s.add_dependency(%q<yard>, ["~> 0.6.0"])
+    s.add_dependency(%q<bluecloth>, ["~> 2.0.9"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.5.1"])
+    s.add_dependency(%q<rcov>, [">= 0"])
+  end
+end
+

data/spec/rubybits_spec.rb

@@ -0,0 +1,298 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "Structure" do
+	it "should allow definition of a format with unsigned fields" do
+		class TestFormat1 < RubyBits::Structure
+			unsigned :field1,  8, "Field1"
+			unsigned :field2,  4, "Field2"
+			unsigned :flag,    1,  "Flag"
+			unsigned :field3,  16, "Field3"
+		end
+	end
+	
+	it "should allow accessing fields created" do
+		class TestFormat2 < RubyBits::Structure
+			unsigned :field1,  8, "Field1"
+			unsigned :field2,  4, "Field2"
+			unsigned :flag,    1,  "Flag"
+			unsigned :field3,  16, "Field3"
+		end
+		
+		tf = TestFormat2.new
+		tf.field1 = 0x40
+		tf.field1.should == 0x40
+	end
+	
+	it "should allow initialization with data" do
+		class TestFormat3 < RubyBits::Structure
+			unsigned :field1,  8,  "Field1"
+			unsigned :field2,  4,  "Field2"
+			unsigned :field3,  4,  "Flag"
+			unsigned :field4,  16, "Field3"
+		end
+		
+		tf = TestFormat3.new(:field1 => 0x77, :field2 => 0x06, :field3 => 0x0F, :field4 => 0x726b)
+		tf.field1.should == 0x77
+		tf.field2.should == 0x06
+		tf.field3.should == 0x0F
+		tf.field4.should == 0x726b
+	end
+	
+	it "should allow creation of bitstrings from structure spec" do
+		class TestFormat4 < RubyBits::Structure
+			unsigned :field1,  8,  "Field1"
+			unsigned :field2,  4,  "Field2"
+			unsigned :field3,  4,  "Flag"
+			unsigned :field4,  16, "Field3"
+		end
+		
+		tf = TestFormat4.new(:field1 => 0x77, :field2 => 0x06, :field3 => 0x0F, :field4 => 0x726b)
+		tf.to_s.should == "work"
+	end
+	
+	it "should allow weird field sizes" do
+		class TestFormat5 < RubyBits::Structure
+			unsigned :field1,  5,  "Field1"
+			unsigned :field2,  3,  "Field2"
+			unsigned :field3,  6,  "Flag"
+			unsigned :field4,  4, "Field3"
+			unsigned :field5, 11, "Field5"
+			unsigned :field6,  2, "Field6"
+		end
+		
+		tf = TestFormat5.new(:field1 => 0b11010, :field2 => 0b001, :field3 => 0b101010, :field4 => 0b1011, :field5 => 0b11101010001, :field6 => 0b11)
+		tf.to_s.bytes.to_a.should == [0b11010001, 0b10101010, 0b11111010, 0b10001110]
+	end
+	
+	it "should allow signed integers" do
+		class TestFormat6 < RubyBits::Structure
+			signed :field1, 8, "Field1"
+			signed :field2, 4, "Field2"
+			signed :field3, 4, "Field3"
+		end
+		
+		tf = TestFormat6.new(:field1 => -10, :field2 => -4, :field3 => -7)
+		tf.to_s.bytes.to_a.should == [0b11110110, 0b11001001]
+	end
+	
+	it "should calculate checksum correctly" do
+		class TestFormat7 < RubyBits::Structure
+			unsigned :field1,  8,  "Field1"
+			unsigned :field2,  4,  "Field2"
+			unsigned :field3,  4,  "Flag"
+			unsigned :field4,  16, "Field3"
+			unsigned :checksum, 8, "Checksum (sum of all previous fields)"
+			
+			checksum :checksum do |bytes|
+				bytes[0..-2].inject{|sum, byte| sum += byte} & 255
+			end
+		end
+		
+		tf = TestFormat7.new(:field1 => 0x77, :field2 => 0x06, :field3 => 0x0F, :field4 => 0x726b)
+		tf.to_s.bytes.to_a.should == "work".bytes.to_a << ((0x77 + 0x6F + 0x72 + 0x6B) & 255)
+	end
+	
+	it "should calculate checksum when accessed" do
+		class TestFormat8 < RubyBits::Structure
+			unsigned :field1,  8,  "Field1"
+			unsigned :field2,  4,  "Field2"
+			unsigned :field3,  4,  "Flag"
+			unsigned :field4,  16, "Field3"
+			unsigned :checksum, 8, "Checksum (sum of all previous fields)"
+			
+			checksum :checksum do |bytes|
+				bytes[0..-2].inject{|sum, byte| sum += byte} & 255
+			end
+		end
+		
+		tf = TestFormat8.new(:field1 => 0x77, :field2 => 0x06, :field3 => 0x0F, :field4 => 0x726b)
+		tf.checksum.should == (0x77 + 0x6F + 0x72 + 0x6B) & 255
+	end
+	
+	it "should allow variable length fields" do
+		class TestFormat9 < RubyBits::Structure
+			unsigned :field1,   8, "Field1"
+			unsigned :field2,   4, "Field2"
+			unsigned :field3,   4, "Flag"
+			variable :field4,      "text"
+			unsigned :checksum, 8, "Checksum (sum of all previous fields)"
+			
+			checksum :checksum do |bytes|
+				bytes[0..-2].inject{|sum, byte| sum += byte} & 255
+			end
+		end
+		
+		tf = TestFormat9.new(:field1 => 0x77, :field2 => 0x06, :field3 => 0x0F, :field4 => "hello")
+		checksum = (0x77 + 0x6F + "hello".bytes.to_a.reduce(:+)) & 255
+		tf.checksum.should == checksum
+		
+		tf.to_s.bytes.to_a.should == [0x77, 0x6F] + "hello".bytes.to_a << checksum
+	end
+	
+	it "should allow variable length fields that are not byte aligned" do
+		class TestFormat10 < RubyBits::Structure
+			unsigned :field1,   8, "Field1"
+			unsigned :field2,   4, "Field2"
+			unsigned :field3,   4, "Flag"
+			unsigned :field4,   6, "Not byte aligned"
+			variable :text,        "text"
+			unsigned :checksum, 8, "Checksum (sum of all previous fields)"
+			
+			checksum :checksum do |bytes|
+				bytes[0..-2].inject{|sum, byte| sum += byte} & 255
+			end
+		end
+		
+		string = [119, 111, 201, 133, 137, 140]
+		tf = TestFormat10.new(:field1 => 0x77, :field2 => 0x06, :field3 => 0x0F, :field4 => 0x32, :text => "abc")
+		checksum = string.reduce(:+) & 255
+		tf.checksum.should == checksum
+		
+		tf.to_s.bytes.to_a.should == [119, 111, 201, 133, 137, 141, 36]
+	end
+	
+	it "should allow variable length fields whose lengths are specified by another field" do
+		class TestFormat11 < RubyBits::Structure
+			unsigned :field1,   8, "Field1"
+			unsigned :field2,   4, "Field2"
+			unsigned :field3,   4, "Flag"
+			variable :text,        "text", :length => :field2
+			unsigned :checksum, 8, "Checksum (sum of all previous fields)"
+			
+			checksum :checksum do |bytes|
+				bytes[0..-2].inject{|sum, byte| sum += byte} & 255
+			end
+		end
+		
+		tf = TestFormat11.new(:field1 => 0x77, :field2 => 0x04, :field3 => 0x0F, :text => "abc")
+		checksum = (0x77 + 0x4F + "abc".bytes.to_a.reduce(:+)) & 255
+		tf.checksum.should == checksum
+		
+		tf.to_s.bytes.to_a.should == [0x77, 0x4F, 0x61, 0x62, 0x63, 0, checksum]
+	end
+	
+	it "should fail when setting an invalid value for a field" do
+		class TestFormat12 < RubyBits::Structure
+			unsigned :field1,   8,  "Field1"
+			unsigned :field2,   4,  "Field2"
+			unsigned :field3,   16, "Flag"
+			variable :text,         "text"
+		end
+		
+		expect {TestFormat12.new(:field1 => 257, :field2 => 0x4, :field3 => 500)}.to raise_error(RubyBits::FieldValueException)
+		tf = TestFormat12.new
+		expect {tf.field2 = 0x44}.to raise_error(RubyBits::FieldValueException)
+		expect {tf.field3 = 0x44122}.to raise_error(RubyBits::FieldValueException)
+		expect {tf.text = 55}.to raise_error(RubyBits::FieldValueException)
+	end
+end
+
+describe "parsing" do
+	it "should correctly determine a valid message" do
+		class TestFormat13 < RubyBits::Structure
+			unsigned :field1,   8,  "Field1"
+			unsigned :field2,   4,  "Field2"
+			unsigned :field3,   4,  "Field3"
+			signed   :field4,   8,  "Field4"
+			signed   :field5,   8,  "Field5"
+			unsigned :field6,  16,  "Short field"
+		end
+		TestFormat13.valid_message?([0x34, 0x41, 0b11001001, 0x24, 0x44, 0x55].pack("c*")).should == true
+		TestFormat13.valid_message?([0x34, 0x41, 0b11001001, 0x24, 0x44, 0x55, 0x44].pack("c*")).should == true
+		TestFormat13.valid_message?([0x11, 0x11, 0x44, 0x24, 0x11].pack("c*")).should == false
+		TestFormat13.valid_message?("").should == false
+		
+		tf, string = TestFormat13.from_string([0x34, 0x41, 0b11001001, 0b00110011, 0x55, 0x11].pack("c*") + "ab")
+		tf.field1.should == 0x34
+		tf.field2.should == 0x04
+		tf.field3.should == 0x01
+		tf.field4.should == -55
+		tf.field5.should == 0b00110011
+		tf.field6.should == 0x5511
+		string.should == "ab"
+	end
+	it "should correctly determine a valid message with variable length fields" do
+		class TestFormat14 < RubyBits::Structure
+			unsigned :field1,   8, "Field1"
+			unsigned :size,     4, "Length"
+			unsigned :field3,   4, "Field3"
+			variable :text,        "text", :length => :size, :unit => :byte
+		end
+		TestFormat14.valid_message?([0x44, 0x3F].pack("cc") + "abc").should == true
+		TestFormat14.valid_message?([0x33, 0x1C].pack("cc") + "ab").should == true
+		TestFormat14.valid_message?([0x11, 0x5C].pack("cc") + "abc").should == false
+		
+		tf, string = TestFormat14.from_string([0x34, 0x3F].pack("c*") + "abcdefg")
+		tf.field1.should == 0x34
+		tf.size.should == 0x03
+		tf.field3.should == 0x0F
+		tf.text.should == "abc"
+		string.should == "defg"
+	end
+	it "should correctly determine a valid message with variable length fields and checksum" do
+		class TestFormat15 < RubyBits::Structure
+			unsigned :field1,   8, "Field1"
+			unsigned :size,     4, "size"
+			variable :text,        "text", :length => :size, :unit => :byte
+			unsigned :checksum, 8, "checksum"
+		
+			checksum :checksum do |bytes|
+				bytes.reduce(:+) & 255
+			end
+		end
+		
+		TestFormat15.valid_message?([0x5C, 0x36, 0x16, 0x26, 0x3F, 0xE0].pack("c*")).should == true
+		TestFormat15.valid_message?([0x5C, 0x36, 0x16, 0x26, 0x3F, 0xD0].pack("c*")).should == false
+		TestFormat15.valid_message?([0x5C, 0x36, 0x16, 0x26, 0x30, 0xE0].pack("c*")).should == false
+		
+		tf, string = TestFormat15.from_string([0x5C, 0x36, 0x16, 0x26, 0x3F, 0xE0].pack("c*") + "BC")
+		tf.field1.should == 0x5C
+		tf.size.should == 3
+		tf.text.should == "abc"
+		tf.checksum.should == 254
+		string.should == "BC"
+	end
+	it "should parse fix-width format" do 
+		class TestFormat16 < RubyBits::Structure
+			unsigned :field1,   8,  "Field1"
+			unsigned :field2,   4,  "Field2"
+			unsigned :field3,   4,  "Field3"
+			signed   :field4,   8,  "Field4"
+		end
+
+		messages, string = TestFormat16.parse([0x34, 0x41, 0b11001001, 0x55, 0xCF, 0b00110110].pack("c*") + "ab")
+		messages[0].field1.should == 0x34
+		messages[0].field2.should == 0x04
+		messages[0].field3.should == 0x01
+		messages[0].field4.should == -55
+		
+		messages[1].field1.should == 0x55
+		messages[1].field2.should == 0xC
+		messages[1].field3.should == 0xF
+		messages[1].field4.should == 0b00110110
+		
+		string.should == "ab"
+	end
+	it "should parse variable-width format" do 
+		class TestFormat17 < RubyBits::Structure
+			unsigned :field1,   8, "Field1"
+			unsigned :size,     4, "Length"
+			unsigned :field3,   4, "Field3"
+			variable :text,        "text", :length => :size, :unit => :byte
+		end
+
+		messages, string = TestFormat17.parse([0x44, 0x24].pack("c*") + "hi" + [0x55, 0x62].pack("c*") + "hello! friend")
+		messages[0].field1.should == 0x44
+		messages[0].size.should == 0x02
+		messages[0].field3.should == 0x04
+		messages[0].text.should == "hi"
+		
+		messages[1].field1.should == 0x55
+		messages[1].size.should == 0x6
+		messages[1].field3.should == 0x2
+		messages[1].text.should == "hello!"
+		
+		string.should == " friend"
+	end
+	
+end

data/spec/spec_helper.rb

@@ -0,0 +1,12 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'rspec'
+require 'rubybits'
+
+# Requires supporting files with custom matchers and macros, etc,
+# in ./support/ and its subdirectories.
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each {|f| require f}
+
+RSpec.configure do |config|
+  
+end

metadata

@@ -0,0 +1,165 @@
+--- !ruby/object:Gem::Specification 
+name: rubybits
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Micah Wylde
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-11-27 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 1
+        - 0
+        version: 2.1.0
+  type: :development
+  prerelease: false
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: yard
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 6
+        - 0
+        version: 0.6.0
+  type: :development
+  prerelease: false
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: bluecloth
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 0
+        - 9
+        version: 2.0.9
+  type: :development
+  prerelease: false
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 0
+        - 0
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: jeweler
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 5
+        - 1
+        version: 1.5.1
+  type: :development
+  prerelease: false
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: rcov
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id006
+description: RubyBits simplifies the task of parsing and generating binary strings in particular formats.
+email: mwylde@wesleyan.edu
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE.txt
+- README.md
+files: 
+- .document
+- .rspec
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- VERSION
+- lib/rubybits.rb
+- rubybits.gemspec
+- spec/rubybits_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/mwylde/rubybits
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 1583675054934852324
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: A library that makes dealing with bit strings and binary formats easier, inspired by BitStruct
+test_files: 
+- spec/rubybits_spec.rb
+- spec/spec_helper.rb