bindata 0.9.3 → 0.10.0

data/lib/bindata/trace.rb

@@ -0,0 +1,35 @@
+module BinData
+  # reference to the current tracer
+  @tracer ||= nil
+
+  class Tracer #:nodoc:
+    def initialize(io)
+      @trace_io = io
+    end
+
+    def trace(msg)
+      @trace_io.puts(msg)
+    end
+  end
+
+  # Turn on trace information when reading a BinData object.
+  # If +block+ is given then the tracing only occurs for that block.
+  # This is useful for debugging a BinData declaration.
+  def trace_reading(io = STDERR, &block)
+    @tracer = Tracer.new(io)
+    if block_given?
+      begin
+        block.call
+      ensure
+        @tracer = nil
+      end
+    end
+  end
+
+  def trace_message(&block) #:nodoc:
+    return if @tracer.nil?
+    block.call(@tracer)
+  end
+
+  module_function :trace_reading, :trace_message
+end

data/spec/array_spec.rb

@@ -1,10 +1,9 @@
 #!/usr/bin/env ruby
 
 require File.expand_path(File.dirname(__FILE__)) + '/spec_common'
+require File.expand_path(File.dirname(__FILE__)) + '/example'
 require 'bindata/array'
-require 'bindata/bits'
 require 'bindata/int'
-require 'bindata/struct'
 
 describe BinData::Array, "when instantiating" do
   it "should ensure mandatory parameters are supplied" do
@@ -27,11 +26,11 @@ end
 
 describe BinData::Array, "with no elements" do
   before(:each) do
-    @data = BinData::Array.new(:type => :int8)
+    @data = BinData::Array.new(:type => :example_single)
   end
 
-  it "should not be a single_value" do
-    @data.should_not be_single_value
+  it "should be clear" do
+    @data.should be_clear
   end
 
   it "should return zero length" do
@@ -57,30 +56,51 @@ describe BinData::Array, "with no elements" do
   it "should return [] for the last n elements" do
     @data.last(3).should == []
   end
-
-  it "should append an element" do
-    @data.append(99)
-    @data.length.should == 1
-    @data.last.should == 99
-  end
 end
 
 describe BinData::Array, "with several elements" do
   before(:each) do
-    type = [:int16le, {:initial_value => lambda { index + 1 }}]
+    type = [:example_single, {:initial_value => lambda { index + 1 }}]
     @data = BinData::Array.new(:type => type, :initial_length => 5)
   end
 
-  it "should not be a single_value" do
-    @data.should_not be_single_value
+  it "should have correct debug name" do
+    @data[2].debug_name.should == "obj[2]"
+  end
+
+  it "should have correct offset" do
+    @data[2].offset.should == ExampleSingle.new.num_bytes * 2
   end
 
   it "should return a correct snapshot" do
     @data.snapshot.should == [1, 2, 3, 4, 5]
   end
 
+  it "should assign primitive values" do
+    @data.assign([4, 5, 6])
+    @data.snapshot.should == [4, 5, 6]
+  end
+
+  it "should assign bindata objects" do
+    o1 = ExampleSingle.new
+    o1.value = 4
+    o2 = ExampleSingle.new
+    o2.value = 5
+    o3 = ExampleSingle.new
+    o3.value = 6
+    @data.assign([o1, o2, o3])
+    @data.snapshot.should == [4, 5, 6]
+  end
+
+  it "should assign bindata array" do
+    array = BinData::Array.new(:type => :example_single)
+    array.push(4, 5, 6)
+    @data.assign(array)
+    @data.snapshot.should == [4, 5, 6]
+  end
+
   it "should coerce to ::Array if required" do
-    ((1..7).to_a - @data).should == [6, 7]
+    [0].concat(@data).should == [0, 1, 2, 3, 4, 5]
   end
 
   it "should return the first element" do
@@ -111,11 +131,11 @@ describe BinData::Array, "with several elements" do
   end
 
   it "should have correct num_bytes" do
-    @data.num_bytes.should == 10
+    @data.num_bytes.should == 5 * ExampleSingle.new.num_bytes
   end
 
   it "should have correct num_bytes for individual elements" do
-    @data.num_bytes(0).should == 2
+    @data.num_bytes(0).should == ExampleSingle.new.num_bytes
   end
 
   it "should be able to directly access elements" do
@@ -135,12 +155,6 @@ describe BinData::Array, "with several elements" do
     @data.select { |x| (x % 2) == 0 }.should == [2, 4]
   end
 
-  it "should automatically extend" do
-    @data[9] = 3
-    @data[8].should == 9
-    @data.length.should == 10
-  end
-
   it "should clear" do
     @data[1] = 8
     @data.clear
@@ -153,19 +167,14 @@ describe BinData::Array, "with several elements" do
     @data[1].should == 2
   end
 
-  it "should clear a single element out of range without extending" do
-    @data.clear(9)
-    @data.length.should == 5
-  end
-
   it "should be clear upon creation" do
-    @data.clear?.should be_true
+    @data.should be_clear
   end
 
   it "should be clear if all elements are clear" do
     @data[1] = 8
     @data.clear(1)
-    @data.clear?.should be_true
+    @data.should be_clear
   end
 
   it "should test clear status of individual elements" do
@@ -174,62 +183,110 @@ describe BinData::Array, "with several elements" do
     @data.clear?(1).should be_false
   end
 
-  it "should test clear status of out of range elements without extending" do
-    @data.clear?(9).should be_true
-    @data.length.should == 5
-  end
-
-  it "should read and write correctly" do
-    io = StringIO.new
+  it "should symmetrically read and write" do
     @data[1] = 8
-    @data.write(io)
+    str = @data.to_binary_s
 
     @data.clear
-    io.rewind
     @data[1].should == 2
 
-    @data.read(io)
+    @data.read(str)
     @data[1].should == 8
   end
 
-  it "should append an element" do
-    @data.append(99)
-    @data.length.should == 6
-    @data.last.should == 99
+  it "should identify index of elements" do
+    @data.index(3).should == 2
+  end
+
+  it "should return nil for index of non existent element" do
+    @data.index(42).should be_nil
   end
 end
 
-describe BinData::Array, "containing structs" do
+describe BinData::Array, "when accessing elements" do
   before(:each) do
-    type = [:struct, {:fields => [[:int8, :a,
-                                   {:initial_value => lambda { parent.index }}],
-                                  [:int8, :b]]}]
+    type = [:example_single, {:initial_value => lambda { index + 1 }}]
     @data = BinData::Array.new(:type => type, :initial_length => 5)
+    @data[0] = 1
+    @data[1] = 2
+    @data[2] = 3
+    @data[3] = 4
+    @data[4] = 5
+  end
+
+  it "should insert with positive indexes" do
+    @data.insert(2, 30, 40)
+    @data.snapshot.should == [1, 2, 30, 40, 3, 4, 5]
+  end
+
+  it "should insert with negative indexes" do
+    @data.insert(-2, 30, 40)
+    @data.snapshot.should == [1, 2, 3, 4, 30, 40, 5]
+  end
+
+  it "should push" do
+    @data.push(30, 40)
+    @data.snapshot.should == [1, 2, 3, 4, 5, 30, 40]
+  end
+
+  it "should concat" do
+    @data.concat([30, 40])
+    @data.snapshot.should == [1, 2, 3, 4, 5, 30, 40]
   end
 
-  it "should access elements, not values" do
-    @data[3].a.should == 3
+  it "should unshift" do
+    @data.unshift(30, 40)
+    @data.snapshot.should == [30, 40, 1, 2, 3, 4, 5]
   end
 
-  it "should access multiple elements with slice" do
-    @data.slice(2, 3).collect { |x| x.a }.should == [2, 3, 4]
+  it "should automatically extend on [index]" do
+    @data[9].should == 10
+    @data.snapshot.should == [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
   end
 
-  it "should not be able to modify elements" do
-    lambda { @data[1] = 3 }.should raise_error(NoMethodError)
+  it "should automatically extend on []=" do
+    @data[9] = 30
+    @data.snapshot.should == [1, 2, 3, 4, 5, 6, 7, 8, 9, 30]
   end
 
-  it "should interate over each element" do
-    @data.collect { |s| s.a }.should == [0, 1, 2, 3, 4]
+  it "should automatically extend on insert" do
+    @data.insert(7, 30, 40)
+    @data.snapshot.should == [1, 2, 3, 4, 5, 6, 7, 30, 40]
   end
 
-  it "should be able to append elements" do
-    obj = @data.append
-    obj.a = 3
-    obj.b = 5
+  it "should not extend on at" do
+    @data.at(9).should be_nil
+    @data.length.should == 5
+  end
+
+  it "should not extend on [start, length]" do
+    @data[9, 2].should be_nil
+    @data.length.should == 5
+  end
+
+  it "should not extend on [range]" do
+    @data[9 .. 10].should be_nil
+    @data.length.should == 5
+  end
 
-    @data.last.a.should == 3
-    @data.last.b.should == 5
+  it "should not extend on clear" do
+    @data.clear(9)
+    @data.length.should == 5
+  end
+
+  it "should not extend on clear?" do
+    @data.clear?(9).should be_true
+    @data.length.should == 5
+  end
+
+  it "should not extend on num_bytes" do
+    @data.num_bytes(9).should == 0
+    @data.length.should == 5
+  end
+
+  it "should raise error on bad input to []" do
+    lambda { @data["a"] }.should raise_error(TypeError)
+    lambda { @data[1, "a"] }.should raise_error(TypeError)
   end
 end
 
@@ -239,27 +296,22 @@ describe BinData::Array, "with :read_until containing +element+" do
     @data = BinData::Array.new(:type => :int8, :read_until => read_until)
   end
 
-  it "should append to an empty array" do
-    @data.append(3)
-    @data.first.should == 3
-  end
-
   it "should read until the sentinel is reached" do
-    io = StringIO.new("\x01\x02\x03\x04\x05\x06\x07")
-    @data.read(io)
+    str = "\x01\x02\x03\x04\x05\x06\x07"
+    @data.read(str)
     @data.length.should == 5
   end
 end
 
 describe BinData::Array, "with :read_until containing +array+ and +index+" do
   before(:each) do
-    read_until = lambda { index >=2 and array[index - 2] == 5 }
+    read_until = lambda { index >= 2 and array[index - 2] == 5 }
     @data = BinData::Array.new(:type => :int8, :read_until => read_until)
   end
 
   it "should read until the sentinel is reached" do
-    io = StringIO.new("\x01\x02\x03\x04\x05\x06\x07\x08")
-    @data.read(io)
+    str = "\x01\x02\x03\x04\x05\x06\x07\x08"
+    @data.read(str)
     @data.length.should == 7
   end
 end
@@ -267,54 +319,19 @@ end
 describe BinData::Array, "with :read_until => :eof" do
   it "should read records until eof" do
     obj = BinData::Array.new(:type => :int8, :read_until => :eof)
-    data = "\x01\x02\x03"
-    obj.read(data)
+    str = "\x01\x02\x03"
+    obj.read(str)
     obj.snapshot.should == [1, 2, 3]
   end
 
   it "should read records until eof, ignoring partial records" do
     obj = BinData::Array.new(:type => :int16be, :read_until => :eof)
-    data = "\x00\x01\x00\x02\x03"
-    obj.read(data)
+    str = "\x00\x01\x00\x02\x03"
+    obj.read(str)
     obj.snapshot.should == [1, 2]
   end
 end
 
-describe BinData::Array, "of bits" do
-  before(:each) do
-    @data = BinData::Array.new(:type => :bit1, :initial_length => 15)
-  end
-
-  it "should read" do
-    str = [0b0001_0100, 0b1000_1000].pack("CC")
-    @data.read(str)
-    @data[0].should  == 0
-    @data[1].should  == 0
-    @data[2].should  == 0
-    @data[3].should  == 1
-    @data[4].should  == 0
-    @data[5].should  == 1
-    @data[6].should  == 0
-    @data[7].should  == 0
-    @data[8].should  == 1
-    @data[9].should  == 0
-    @data[10].should == 0
-    @data[11].should == 0
-    @data[12].should == 1
-    @data[13].should == 0
-    @data[14].should == 0
-  end
-
-  it "should write" do
-    @data[3] = 1
-    @data.to_s.should == [0b0001_0000, 0b0000_0000].pack("CC")
-  end
-
-  it "should return num_bytes" do
-    @data.num_bytes.should == 2
-  end
-end
-
 describe BinData::Array, "nested within an Array" do
   before(:each) do
     nested_array_params = { :type => [:int8, { :initial_value => :index }],
@@ -333,4 +350,3 @@ describe BinData::Array, "nested within an Array" do
     @data.snapshot.should == [ [4], [5, 6], [7, 8, 9] ]
   end
 end
-

data/spec/{single_spec.rb → base_primitive_spec.rb}

@@ -1,68 +1,139 @@
 #!/usr/bin/env ruby
 
 require File.expand_path(File.dirname(__FILE__)) + '/spec_common'
+require File.expand_path(File.dirname(__FILE__)) + '/example'
+require 'bindata/base_primitive'
 require 'bindata/io'
-require 'bindata/single'
 
-# An implementation of a unsigned 4 byte integer.
-class ConcreteSingle < BinData::Single
-  def val_to_str(val)    [val].pack("V") end
-  def read_val(io)       io.readbytes(4).unpack("V")[0] end
-  def sensible_default() 0 end
+class ExampleSingle
+  # reopen example to make @in_read public for testing
+  def in_read?
+    @in_read
+  end
+end
+
+describe BinData::BasePrimitive, "when subclassing" do
+  before(:all) do
+    eval <<-END
+      class SubClassOfSingle < BinData::BasePrimitive
+        expose_methods_for_testing
+      end
+    END
+  end
 
-  def in_read?()         @in_read end
+  before(:each) do
+    @obj = SubClassOfSingle.new
+  end
+
+  it "should raise errors on unimplemented methods" do
+    lambda { @obj.value_to_binary_string(nil) }.should raise_error(NotImplementedError)
+    lambda { @obj.read_and_return_value(nil) }.should raise_error(NotImplementedError)
+    lambda { @obj.sensible_default }.should raise_error(NotImplementedError)
+  end
 end
 
-describe BinData::Single do
+describe BinData::BasePrimitive do
   it "should conform to rule 1 for returning a value" do
-    data = ConcreteSingle.new(:value => 5)
+    data = ExampleSingle.new(:value => 5)
     data.should_not be_in_read
     data.value.should == 5
   end
 
   it "should conform to rule 2 for returning a value" do
     io = StringIO.new([42].pack("V"))
-    data = ConcreteSingle.new(:value => 5)
+    data = ExampleSingle.new(:value => 5)
+    data.expose_methods_for_testing
     data.do_read(BinData::IO.new(io))
     data.should be_in_read
     data.value.should == 42
   end
 
   it "should conform to rule 3 for returning a value" do
-    data = ConcreteSingle.new(:initial_value => 5)
+    data = ExampleSingle.new(:initial_value => 5)
     data.should be_clear
     data.value.should == 5
   end
 
   it "should conform to rule 4 for returning a value" do
-    data = ConcreteSingle.new(:initial_value => 5)
+    data = ExampleSingle.new(:initial_value => 5)
     data.value = 17
     data.should_not be_clear
     data.value.should == 17
   end
 
   it "should conform to rule 5 for returning a value" do
-    data = ConcreteSingle.new
+    data = ExampleSingle.new
     data.should be_clear
     data.value.should == 0
   end
 
   it "should conform to rule 6 for returning a value" do
-    data = ConcreteSingle.new
+    data = ExampleSingle.new
     data.value = 8
     data.should_not be_clear
     data.value.should == 8
   end
 end
 
-describe BinData::Single, "after initialisation" do
+describe ExampleSingle do
   before(:each) do
-    @data = ConcreteSingle.new
+    @data = ExampleSingle.new
+    @data.value = 5
+  end
+
+  it "should fail when assigning nil values" do
+    lambda { @data.assign(nil) }.should raise_error(ArgumentError)
+  end
+
+  it "should allowing setting and retrieving value" do
+    @data.value = 7
+    @data.value.should == 7
+  end
+
+  it "should allowing setting and retrieving BinData::BasePrimitives" do
+    obj = ExampleSingle.new
+    obj.value = 7
+    @data.value = obj
+    @data.value.should == 7
+  end
+
+  it "should respond to known methods" do
+    @data.should respond_to(:num_bytes)
+  end
+
+  it "should respond to known methods in #snapshot" do
+    @data.should respond_to(:div)
+  end
+
+  it "should not respond to unknown methods in self or #snapshot" do
+    @data.should_not respond_to(:does_not_exist)
+  end
+
+  it "should behave as #snapshot" do
+    (@data + 1).should == 6
+    (1 + @data).should == 6
+  end
+
+  it "should be equal to other ExampleSingle" do
+    other = ExampleSingle.new
+    other.value = 5
+    @data.should == other
+  end
+
+  it "should be equal to raw values" do
+    @data.should == 5
+    5.should == @data
+  end
+end
+
+describe BinData::BasePrimitive, "after initialisation" do
+  before(:each) do
+    @data = ExampleSingle.new
   end
 
   it "should not allow both :initial_value and :value" do
     params = {:initial_value => 1, :value => 2}
-    lambda { ConcreteSingle.new(params) }.should raise_error(ArgumentError)
+    lambda { ExampleSingle.new(params) }.should raise_error(ArgumentError)
   end
 
   it "should have a sensible value" do
@@ -70,18 +141,10 @@ describe BinData::Single, "after initialisation" do
   end
 
   it "should have symmetric IO" do
-    io = StringIO.new
     @data.value = 42
-    @data.write(io)
+    written = @data.to_binary_s
 
-    io.rewind
-    @data = ConcreteSingle.new
-    @data.read(io)
-    @data.value.should == 42
-  end
-
-  it "should be a single_value" do
-    @data.should be_single_value
+    ExampleSingle.read(written).should == 42
   end
 
   it "should allowing setting and retrieving value" do
@@ -99,8 +162,7 @@ describe BinData::Single, "after initialisation" do
   end
 
   it "should not be clear after reading" do
-    io = StringIO.new([123456].pack("V"))
-    @data.read(io)
+    @data.read("\x11\x22\x33\x44")
     @data.should_not be_clear
   end
 
@@ -114,9 +176,9 @@ describe BinData::Single, "after initialisation" do
   end
 end
 
-describe BinData::Single, "with :initial_value" do
+describe BinData::BasePrimitive, "with :initial_value" do
   before(:each) do
-    @data = ConcreteSingle.new(:initial_value => 5)
+    @data = ExampleSingle.new(:initial_value => 5)
   end
 
   it "should return that initial value before reading or being set" do
@@ -129,8 +191,7 @@ describe BinData::Single, "with :initial_value" do
   end
 
   it "should forget :initial_value after reading" do
-    io = StringIO.new([56].pack("V"))
-    @data.read(io)
+    @data.read("\x11\x22\x33\x44")
     @data.value.should_not == 5
   end
 
@@ -141,9 +202,10 @@ describe BinData::Single, "with :initial_value" do
   end
 end
 
-describe BinData::Single, "with :value" do
+describe BinData::BasePrimitive, "with :value" do
   before(:each) do
-    @data = ConcreteSingle.new(:value => 5)
+    @data = ExampleSingle.new(:value => 5)
+    @data.expose_methods_for_testing
   end
 
   it "should return that :value" do
@@ -169,49 +231,28 @@ describe BinData::Single, "with :value" do
   end
 end
 
-describe BinData::Single, "with :check_value" do
+describe BinData::BasePrimitive, "with :check_value" do
   before(:each) do
     @io = StringIO.new([34].pack("V"))
   end
 
   it "should succeed when check_value is non boolean and correct" do
-    data = ConcreteSingle.new(:check_value => 34)
+    data = ExampleSingle.new(:check_value => 34)
     lambda { data.read(@io) }.should_not raise_error
   end
 
   it "should fail when check_value is non boolean and incorrect" do
-    data = ConcreteSingle.new(:check_value => lambda { 123 * 5 })
+    data = ExampleSingle.new(:check_value => lambda { 123 * 5 })
     lambda { data.read(@io) }.should raise_error(BinData::ValidityError)
   end
 
   it "should succeed when check_value is boolean and true" do
-    data = ConcreteSingle.new(:check_value => lambda { (value % 2) == 0})
+    data = ExampleSingle.new(:check_value => lambda { (value % 2) == 0})
     lambda { data.read(@io) }.should_not raise_error
   end
 
   it "should fail when check_value is boolean and false" do
-    data = ConcreteSingle.new(:check_value => lambda { value > 100 })
+    data = ExampleSingle.new(:check_value => lambda { value > 100 })
     lambda { data.read(@io) }.should raise_error(BinData::ValidityError)
   end
 end
-
-describe BinData::Single, "when subclassing" do
-  before(:all) do
-    eval <<-END
-      class SubClassOfSingle < BinData::Single
-        public :val_to_str, :read_val, :sensible_default
-      end
-    END
-  end
-
-  before(:each) do
-    @obj = SubClassOfSingle.new
-  end
-
-  it "should raise errors on unimplemented methods" do
-    lambda { @obj.val_to_str(nil) }.should raise_error(NotImplementedError)
-    lambda { @obj.read_val(nil) }.should raise_error(NotImplementedError)
-    lambda { @obj.sensible_default }.should raise_error(NotImplementedError)
-  end
-end
-