bindata 0.5.0

data/spec/array_spec.rb

@@ -0,0 +1,121 @@
+#!/usr/bin/env ruby
+
+require File.expand_path(File.dirname(__FILE__)) + '/spec_common'
+require 'bindata/array'
+require 'bindata/int'
+require 'bindata/struct'
+
+context "Instantiating an Array" do
+  specify "should ensure mandatory parameters are supplied" do
+    args = {}
+    lambda { BinData::Array.new(args) }.should raise_error(ArgumentError)
+    args = {:type => :int8}
+    lambda { BinData::Array.new(args) }.should raise_error(ArgumentError)
+    args = {:initial_length => 3}
+    lambda { BinData::Array.new(args) }.should raise_error(ArgumentError)
+  end
+
+  specify "should fail if a given type is unknown" do
+    args = {:type => :does_not_exist, :initial_length => 3}
+    lambda { BinData::Array.new(args) }.should raise_error(TypeError)
+  end
+end
+
+context "An Array with several elements" do
+  setup do
+    type = [:int16le, {:initial_value => lambda { index + 1 }}]
+    @data = BinData::Array.new(:type => type, :initial_length => 5)
+  end
+
+  specify "should return a correct snapshot" do
+    @data.snapshot.should == [1, 2, 3, 4, 5]
+  end
+
+  specify "should have correct num elements" do
+    @data.length.should == 5
+    @data.size.should == 5
+  end
+
+  specify "should have correct num_bytes" do
+    @data.num_bytes.should == 10
+  end
+
+  specify "should have correct num_bytes for individual elements" do
+    @data.num_bytes(0).should == 2
+  end
+
+  specify "should have no field_names" do
+    @data.field_names.should be_empty
+  end
+
+  specify "should be able to directly access elements" do
+    @data[1] = 8
+    @data[1].should == 8
+  end
+
+  specify "should be able to use methods from Enumerable" do
+    @data.select { |x| (x % 2) == 0 }.should == [2, 4]
+  end
+
+  specify "should clear" do
+    @data[1] = 8
+    @data.clear
+    @data.collect.should == [1, 2, 3, 4, 5]
+  end
+
+  specify "should clear a single element" do
+    @data[1] = 8
+    @data.clear(1)
+    @data[1].should == 2
+  end
+
+  specify "should be clear upon creation" do
+    @data.clear?.should be_true
+  end
+
+  specify "should be clear if all elements are clear" do
+    @data[1] = 8
+    @data.clear(1)
+    @data.clear?.should be_true
+  end
+
+  specify "should test clear status of individual elements" do
+    @data[1] = 8
+    @data.clear?(0).should be_true
+    @data.clear?(1).should be_false
+  end
+
+  specify "should read and write correctly" do
+    io = StringIO.new
+    @data[1] = 8
+    @data.write(io)
+
+    @data.clear
+    io.rewind
+    @data[1].should == 2
+
+    @data.read(io)
+    @data[1].should == 8
+  end
+end
+
+context "An Array containing structs" do
+  setup do
+    type = [:struct, {:fields => [[:int8, :a,
+                                   {:initial_value => lambda { parent.index }}],
+                                  [:int8, :b]]}]
+    @data = BinData::Array.new(:type => type, :initial_length => 5)
+  end
+
+  specify "should access elements, not values" do
+    @data[3].a.should == 3
+  end
+
+  specify "should not be able to modify elements" do
+    lambda { @data[1] = 3 }.should raise_error(NoMethodError)
+  end
+
+  specify "should interate over each element" do
+    @data.collect { |s| s.a }.should == [0, 1, 2, 3, 4]
+  end
+end

data/spec/base_spec.rb

@@ -0,0 +1,194 @@
+#!/usr/bin/env ruby
+
+require File.expand_path(File.dirname(__FILE__)) + '/spec_common'
+require 'bindata/base'
+
+context "A data object with mandatory option" do
+  context_setup do
+    eval <<-END
+      class Mandatory < BinData::Base
+        mandatory_parameter :p1
+      end
+    END
+  end
+  specify "should ensure that those options are present" do
+    lambda { Mandatory.new(:p1 => "a") }.should_not raise_error
+  end
+
+  specify "should fail when those options are not present" do
+    lambda { Mandatory.new(:p2 => "a") }.should raise_error(ArgumentError)
+  end
+end
+
+context "A data object with mutually exclusive options" do
+  context_setup do
+    eval <<-END
+      class MutexParam < BinData::Base
+        optional_parameters :p1, :p2
+        def initialize(params = {}, env = nil)
+          super(params, env)
+          ensure_mutual_exclusion(:p1, :p2)
+        end
+      end
+    END
+  end
+
+  specify "should not fail when neither of those options is present" do
+    lambda { MutexParam.new }.should_not raise_error
+  end
+
+  specify "should not fail when only one of those options is present" do
+    lambda { MutexParam.new(:p1 => "a") }.should_not raise_error
+    lambda { MutexParam.new(:p2 => "a") }.should_not raise_error
+  end
+
+  specify "should fail when both those options are present" do
+    lambda { MutexParam.new(:p1 => "a", :p2 => "b") }.should raise_error(ArgumentError)
+  end
+end
+
+context "A data object with parameters" do
+  context_setup do
+    eval <<-END
+      class WithParam < BinData::Base
+        mandatory_parameter :p1
+        optional_parameters :p2, :p3
+        public :has_param?, :eval_param, :param
+      end
+    END
+  end
+
+  specify "should not allow nil parameters" do
+    lambda { WithParam.new(:p1 => 1, :p2 => nil) }.should raise_error(ArgumentError)
+  end
+
+  specify "should identify extra parameters" do
+    env = mock("env")
+    env.should_receive(:params=).with(:p4 => 4, :p5 => 5)
+    env.should_receive(:data_object=)
+    obj = WithParam.new({:p1 => 1, :p3 => 3, :p4 => 4, :p5 => 5}, env)
+  end
+
+  specify "should only recall mandatory and optional parameters" do
+    obj = WithParam.new(:p1 => 1, :p3 => 3, :p4 => 4, :p5 => 5)
+    obj.should     have_param(:p1)
+    obj.should_not have_param(:p2)
+    obj.should     have_param(:p3)
+    obj.should_not have_param(:p4)
+    obj.should_not have_param(:p5)
+  end
+
+  specify "should evaluate mandatory and optional parameters" do
+    obj = WithParam.new(:p1 => 1, :p3 => lambda {1 + 2}, :p4 => 4, :p5 => 5)
+    obj.eval_param(:p1).should == 1
+    obj.eval_param(:p2).should_be_nil
+    obj.eval_param(:p3).should == 3
+    obj.eval_param(:p4).should_be_nil
+    obj.eval_param(:p5).should_be_nil
+  end
+
+  specify "should be able to access without evaluating" do
+    obj = WithParam.new(:p1 => :asym, :p3 => lambda {1 + 2})
+    obj.param(:p1).should == :asym
+    obj.param(:p2).should_be_nil
+    obj.param(:p3).should respond_to(:arity)
+  end
+end
+
+context "A data object with :check_offset" do
+  context_setup do
+    eval <<-END
+      class TenByteOffset < BinData::Base
+        def do_read(io)
+          # advance the io position before checking offset
+          io.seek(10, IO::SEEK_CUR)
+          super(io)
+        end
+        def _do_read(io) end
+        def done_read; end
+        def clear; end
+      end
+    END
+  end
+
+  specify "should fail if offset is incorrect" do
+    io = StringIO.new("12345678901234567890")
+    io.seek(2)
+    obj = TenByteOffset.new(:check_offset => 8)
+    lambda { obj.read(io) }.should raise_error(BinData::ValidityError)
+  end
+
+  specify "should succeed if offset is correct" do
+    io = StringIO.new("12345678901234567890")
+    io.seek(3)
+    obj = TenByteOffset.new(:check_offset => 10)
+    lambda { obj.read(io) }.should_not raise_error
+  end
+
+  specify "should fail if :check_offset fails" do
+    io = StringIO.new("12345678901234567890")
+    io.seek(4)
+    obj = TenByteOffset.new(:check_offset => lambda { offset == 11 } )
+    lambda { obj.read(io) }.should raise_error(BinData::ValidityError)
+  end
+
+  specify "should succeed if :check_offset succeeds" do
+    io = StringIO.new("12345678901234567890")
+    io.seek(5)
+    obj = TenByteOffset.new(:check_offset => lambda { offset == 10 } )
+    lambda { obj.read(io) }.should_not raise_error
+  end
+end
+
+context "A data object with :readwrite => false" do
+  context_setup do
+    eval <<-END
+      class NoIO < BinData::Base
+        def _do_read(io)
+          @_do_read = true
+        end
+        def _write(io)
+          @_do_write = true
+        end
+        def _num_bytes
+          5
+        end
+        def done_read; end
+        def clear; end
+        attr_reader :_do_read, :_do_write
+      end
+    END
+    @obj = NoIO.new :readwrite => false
+  end
+
+  specify "should not read" do
+    io = StringIO.new("12345678901234567890")
+    @obj.read(io)
+    @obj._do_read.should_not == true
+  end
+
+  specify "should not write" do
+    io = StringIO.new
+    @obj.write(io)
+    @obj._do_write.should_not == true
+  end
+
+  specify "should have zero num_bytes" do
+    @obj.num_bytes.should == 0
+  end
+end
+
+context "A data object defining a value method" do
+  context_setup do
+    eval <<-END
+      class SingleValueObject < BinData::Base
+        def value; end
+      end
+    END
+  end
+
+  specify "should be a single value object" do
+    obj = SingleValueObject.new
+    obj.should be_a_single_value
+  end
+end

data/spec/choice_spec.rb

@@ -0,0 +1,105 @@
+#!/usr/bin/env ruby
+
+require File.expand_path(File.dirname(__FILE__)) + '/spec_common'
+require 'bindata/choice'
+require 'bindata/int'
+require 'bindata/lazy'
+require 'bindata/struct'
+
+context "Instantiating a Choice" do
+  specify "should ensure mandatory parameters are supplied" do
+    args = {}
+    lambda { BinData::Choice.new(args) }.should raise_error(ArgumentError)
+    args = {:selection => 1}
+    lambda { BinData::Choice.new(args) }.should raise_error(ArgumentError)
+    args = {:choices => []}
+    lambda { BinData::Choice.new(args) }.should raise_error(ArgumentError)
+  end
+
+  specify "should fail if a given type is unknown" do
+    args = {:choices => [:does_not_exist], :selection => 0}
+    lambda { BinData::Choice.new(args) }.should raise_error(TypeError)
+  end
+end
+
+context "A Choice with several choices" do
+  setup do
+    # allow specifications to select the choice
+    @env = BinData::LazyEvalEnv.new
+    @env.class.class_eval { attr_accessor :choose }
+
+    @data = BinData::Choice.new({:choices => [[:int8, {:initial_value => 3}],
+                                              [:int16le, {:initial_value => 5}],
+                                              :int8,
+                                              [:struct,
+                                               {:fields =>[[:int8, :a]]}],
+                                              [:int8, {:initial_value => 7}]],
+                                 :selection => :choose},
+                                @env)
+  end
+
+  specify "should be able to select the choice" do
+    @env.choose = 0
+    @data.value.should == 3
+    @env.choose = 1
+    @data.value.should == 5
+    @env.choose = 2
+    @data.value.should == 0
+    @env.choose = 3
+    @data.a.should == 0
+    @env.choose = 4
+    @data.value.should == 7
+  end
+
+  specify "should not be able to select an invalid choice" do
+    @env.choose = -1
+    lambda { @data.value }.should raise_error(IndexError)
+    @env.choose = 5
+    lambda { @data.value }.should raise_error(IndexError)
+  end
+
+  specify "should be able to interact directly with the choice" do
+    @env.choose = 0
+    @data.value = 17
+    @data.value.should == 17
+  end
+
+  specify "should handle missing methods correctly" do
+    @env.choose = 0
+
+    @data.should respond_to(:value)
+    @data.should_not respond_to(:does_not_exist)
+    lambda { @data.does_not_exist }.should raise_error(NoMethodError)
+  end
+
+  specify "should delegate methods to the selected single choice" do
+    @env.choose = 1
+    @data.value = 17
+
+    @data.find_obj_for_name("does_not_exist").should be_nil
+    @data.num_bytes.should == 2
+    @data.field_names.should be_empty
+    @data.value.should == 17
+
+    io = StringIO.new
+    @data.write(io)
+
+    @data.clear
+    @data.clear?.should be_true
+    @data.value.should == 5
+
+    io.rewind
+    @data.read(io)
+    @data.value.should == 17
+
+    @data.snapshot.should == 17
+  end
+
+  specify "should delegate methods to the selected complex choice" do
+    @env.choose = 3
+    @data.find_obj_for_name("a").should_not be_nil
+    @data.field_names.should == ["a"]
+    @data.num_bytes.should == 1
+  end
+end
+

data/spec/int_spec.rb

@@ -0,0 +1,141 @@
+#!/usr/bin/env ruby
+
+require File.expand_path(File.dirname(__FILE__)) + '/spec_common'
+require 'bindata/int'
+
+context "All signed integers" do
+  specify "should have a sensible value of zero" do
+    [BinData::Int8,
+     BinData::Int16le,
+     BinData::Int16be,
+     BinData::Int32le,
+     BinData::Int32be].each do |klass|
+      klass.new.value.should == 0
+    end
+  end
+
+  specify "should pass these tests" do
+    [
+      [1, true,  BinData::Int8],
+      [2, false, BinData::Int16le],
+      [2, true,  BinData::Int16be],
+      [4, false, BinData::Int32le],
+      [4, true,  BinData::Int32be],
+    ].each do |nbytes, big_endian, klass|
+      gen_int_test_data(nbytes, big_endian).each do |val, clamped_val, str|
+        test_read_write(klass, val, clamped_val, str)
+      end
+    end
+  end
+end
+
+context "All unsigned integers" do
+  specify "should have a sensible value of zero" do
+    [BinData::Uint8,
+     BinData::Uint16le,
+     BinData::Uint16be,
+     BinData::Uint32le,
+     BinData::Uint32be].each do |klass|
+      klass.new.value.should == 0
+    end
+  end
+
+  specify "should pass these tests" do
+    [
+      [1, true,  BinData::Uint8],
+      [2, false, BinData::Uint16le],
+      [2, true,  BinData::Uint16be],
+      [4, false, BinData::Uint32le],
+      [4, true,  BinData::Uint32be],
+    ].each do |nbytes, big_endian, klass|
+      gen_uint_test_data(nbytes, big_endian).each do |val, clamped_val, str|
+        test_read_write(klass, val, clamped_val, str)
+      end
+    end
+  end
+end
+
+# run read / write tests for the given values
+def test_read_write(klass, val, clamped_val, str)
+  # set the data and ensure clamping occurs
+  data = klass.new
+  data.value = val
+  data.value.should == clamped_val
+  
+  # write the data
+  io = StringIO.new
+  data.write(io)
+
+  # check that we write the expected byte pattern
+  io.rewind
+  io.read.should == str
+
+  # check that we read in the same data that was written
+  io.rewind
+  data = klass.new
+  data.read(io)
+  data.value.should == clamped_val
+end
+
+# return test data for testing unsigned ints
+def gen_uint_test_data(nbytes, big_endian)
+  raise "nbytes too big" if nbytes > 8
+  tests = []
+
+  # test the minimum value
+  v = 0
+  s = "\x00" * nbytes
+  tests.push [v, v, big_endian ? s : s.reverse]
+
+  # values below minimum should be clamped to minimum
+  tests.push [v-1, v, big_endian ? s : s.reverse]
+
+  # test a value within range
+  v = 0x123456789abcdef0 >> ((8-nbytes) * 8)
+  s = "\x12\x34\x56\x78\x9a\xbc\xde\xf0".slice(0, nbytes)
+  tests.push [v, v, big_endian ? s : s.reverse]
+
+  # test the maximum value
+  v = (1 << (nbytes * 8)) - 1
+  s = "\xff" * nbytes
+  tests.push [v, v, big_endian ? s : s.reverse]
+
+  # values above maximum should be clamped to maximum
+  tests.push [v+1, v, big_endian ? s : s.reverse]
+
+  tests
+end
+
+# return test data for testing signed ints
+def gen_int_test_data(nbytes, big_endian)
+  raise "nbytes too big" if nbytes > 8
+  tests = []
+
+  # test the minimum value
+  v = -((1 << (nbytes * 8 - 1)) - 1) -1
+  s = "\x80\x00\x00\x00\x00\x00\x00\x00".slice(0, nbytes)
+  tests.push [v, v, big_endian ? s : s.reverse]
+
+  # values below minimum should be clamped to minimum
+  tests.push [v-1, v, big_endian ? s : s.reverse]
+
+  # test a -ve value within range
+  v = -1
+  s = "\xff" * nbytes
+  tests.push [v, v, big_endian ? s : s.reverse]
+
+  # test a +ve value within range
+  v = 0x123456789abcdef0 >> ((8-nbytes) * 8)
+  s = "\x12\x34\x56\x78\x9a\xbc\xde\xf0".slice(0, nbytes)
+  tests.push [v, v, big_endian ? s : s.reverse]
+
+  # test the maximum value
+  v = (1 << (nbytes * 8 - 1)) - 1
+  s = "\x7f" + "\xff" * (nbytes - 1)
+  tests.push [v, v, big_endian ? s : s.reverse]
+
+  # values above maximum should be clamped to maximum
+  tests.push [v+1, v, big_endian ? s : s.reverse]
+
+  tests
+end