bindata 0.5.1 → 0.6.0

data/ChangeLog

@@ -1,5 +1,11 @@
 = BinData Changelog
 
+== Version 0.6.0 (2007-03-28)
+
+* Added 64 bit integers.
+* Added floating point numbers.
+* Added endian keyword to Struct to reduce the amount of typing needed.
+
 == Version 0.5.1 (2007-03-21)
 
 * Updated documentation.

data/README

@@ -164,6 +164,11 @@ BinData::Uint16be:: Unsigned 16 bit integer (big endian).
 BinData::Uint32le:: Unsigned 32 bit integer (little endian).
 BinData::Uint32be:: Unsigned 32 bit integer (big endian).
 
+BinData::FloatLe::  Single precision floating point number (little endian).
+BinData::FloatBe::  Single precision floating point number (big endian).
+BinData::DoubleLe:: Double precision floating point number (little endian).
+BinData::DoubleBe:: Double precision floating point number (big endian).
+
 BinData::String::   A sequence of bytes.
 BinData::Stringz::  A zero terminated sequence of bytes.
 
@@ -201,6 +206,37 @@ If the value is a symbol, it is taken as syntactic sugar for a lambda
 containing the value of the symbol.
 e.g <tt>:param => :foo</tt> is <tt>:param => lambda { foo }</tt>
 
+== Saving Typing
+
+The endianess of numeric types must be explicitly defined so that the code
+produced is independent of architecture.  Explicitly specifying the
+endianess of each numeric type can become tedious, so the following
+shortcut is provided.
+
+  class A < BinData::Struct
+    endian :little
+
+    uint16   :a
+    uint32   :b
+    double   :c
+    uint32be :d
+    array    :e, :type => :int16
+  end
+
+is equivalent to:
+
+  class A < BinData::Struct
+    uint16le  :a
+    uint32le  :b
+    double_le :c
+    uint32be  :d
+    array     :e, :type => :int16le
+  end
+
+Using the endian keyword improves the readability of the declaration as well
+as reducing the amount of typing necessary.  Note that the endian keyword will
+cascade to nested types, as illustrated with the array in the above example.
+
 == Creating custom types
 
 Custom types should be created by subclassing BinData::Struct.

data/TODO

@@ -3,11 +3,8 @@
 
 * Add scoping so the value of a param doesn't need to call parent
 
-* Optimise int.rb for speed.
-
-* Maybe add an endian method to struct so you can say int16 instead of int16le.
-  - Should this by lazily evaluated, or evaluated only once when
-    instantiating fields?
-
 * Think how offset_of should work.
 
+* Need optional parameter for fields
+
+* Should I add seek capability?

data/lib/bindata.rb

@@ -3,11 +3,12 @@
 
 require 'bindata/array'
 require 'bindata/choice'
+require 'bindata/float'
 require 'bindata/int'
 require 'bindata/string'
 require 'bindata/stringz'
 require 'bindata/struct'
 
 module BinData
-  VERSION = "0.5.1"
+  VERSION = "0.6.0"
 end

data/lib/bindata/array.rb

@@ -35,7 +35,7 @@ module BinData
       super(params, env)
 
       type, el_params = param(:type)
-      klass = self.class.lookup(type)
+      klass = klass_lookup(type)
       raise TypeError, "unknown type '#{type}' for #{self}" if klass.nil?
 
       @element_list    = nil

data/lib/bindata/base.rb

@@ -83,7 +83,21 @@ module BinData
 
       # Returns the class matching a previously registered +name+.
       def lookup(name)
-        Registry.instance.lookup(name)
+        klass = Registry.instance.lookup(name)
+        if klass.nil?
+          # lookup failed so attempt endian lookup
+          if self.respond_to?(:endian) and self.endian != nil
+            name = name.to_s
+            if /^u?int\d\d?$/ =~ name
+              new_name = name + ((self.endian == :little) ? "le" : "be")
+              klass = Registry.instance.lookup(new_name)
+            elsif ["float", "double"].include?(name)
+              new_name = name + ((self.endian == :little) ? "_le" : "_be")
+              klass = Registry.instance.lookup(new_name)
+            end
+          end
+        end
+        klass
       end
     end
 
@@ -131,6 +145,16 @@ module BinData
       @env.data_object = self
     end
 
+    # Returns the class matching a previously registered +name+.
+    def klass_lookup(name)
+      klass = self.class.lookup(name)
+      if klass.nil? and @env.parent_data_object != nil
+        # lookup failed so retry in the context of the parent data object
+        klass = @env.parent_data_object.klass_lookup(name)
+      end
+      klass
+    end
+
     # Reads data into this bin object by calling #do_read then #done_read.
     def read(io)
       # remember the current position in the IO object

data/lib/bindata/choice.rb

@@ -38,7 +38,7 @@ module BinData
       @choices = []
       param(:choices).each do |choice_type, choice_params|
         choice_params ||= {}
-        klass = self.class.lookup(choice_type)
+        klass = klass_lookup(choice_type)
         if klass.nil?
           raise TypeError, "unknown type '#{choice_type.id2name}' for #{self}"
         end

data/lib/bindata/float.rb

@@ -0,0 +1,84 @@
+require 'bindata/single'
+
+module BinData
+  # Provides a number of classes that contain a floating point number.
+  # The float is defined by endian, and precision.
+
+  module Float #:nodoc: all
+    def self.create_float_methods(klass, single_precision, endian)
+      read = create_read_code(single_precision, endian)
+      to_s = create_to_s_code(single_precision, endian)
+
+      define_methods(klass, single_precision, read, to_s)
+    end
+
+    def self.create_read_code(single_precision, endian)
+      if single_precision
+        unpack = (endian == :little) ? 'e' : 'g'
+        nbytes = 4
+      else # double_precision
+        unpack = (endian == :little) ? 'E' : 'G'
+        nbytes = 8
+      end
+
+      "readbytes(io,#{nbytes}).unpack('#{unpack}').at(0)"
+    end
+
+    def self.create_to_s_code(single_precision, endian)
+      if single_precision
+        pack = (endian == :little) ? 'e' : 'g'
+      else # double_precision
+        pack = (endian == :little) ? 'E' : 'G'
+      end
+
+      "[val].pack('#{pack}')"
+    end
+
+    def self.define_methods(klass, single_precision, read, to_s)
+      nbytes = single_precision ? 4 : 8
+
+      # define methods in the given class
+      klass.module_eval <<-END
+        def _num_bytes(ignored)
+          #{nbytes}
+        end
+
+        #---------------
+        private
+
+        def sensible_default
+          0.0
+        end
+
+        def val_to_str(val)
+          #{to_s}
+        end
+
+        def read_val(io)
+          #{read}
+        end
+      END
+    end
+  end
+
+
+  # Single precision floating point number in little endian format
+  class FloatLe < Single
+    Float.create_float_methods(self, true, :little)
+  end
+
+  # Single precision floating point number in big endian format
+  class FloatBe < Single
+    Float.create_float_methods(self, true, :big)
+  end
+
+  # Double precision floating point number in little endian format
+  class DoubleLe < Single
+    Float.create_float_methods(self, false, :little)
+  end
+
+  # Double precision floating point number in big endian format
+  class DoubleBe < Single
+    Float.create_float_methods(self, false, :big)
+  end
+end

data/lib/bindata/int.rb

@@ -4,168 +4,168 @@ module BinData
   # Provides a number of classes that contain an integer.  The integer
   # is defined by endian, signedness and number of bytes.
 
-  module BaseUint #:nodoc: all
-
-    def value=(val)
-      super(clamp(val))
-    end
+  module Integer #:nodoc: all
+    def self.create_int_methods(klass, nbits, endian)
+      max = (1 << (nbits - 1)) - 1
+      min = -(max + 1)
+      clamp = "val = (val < #{min}) ? #{min} : (val > #{max}) ? #{max} : val"
 
-    #---------------
-    private
+      int2uint = "val = val & #{(1 << nbits) - 1}"
+      uint2int = "val = ((val & #{1 << (nbits - 1)}).zero?) ? " +
+                 "val & #{max} : -(((~val) & #{max}) + 1)"
 
-    def sensible_default
-      0
-    end
+      read = create_read_code(nbits, endian)
+      to_s = create_to_s_code(nbits, endian)
 
-    def val_to_str(val)
-      _val_to_str(clamp(val))
+      define_methods(klass, nbits / 8, clamp, read, to_s, int2uint, uint2int)
     end
 
-    # Clamps +val+ to the range 0 .. max_val
-    def clamp(val)
-      v = val
-      nbytes = val_num_bytes(0)
+    def self.create_uint_methods(klass, nbits, endian)
       min = 0
-      max = (1 << (nbytes * 8)) - 1
-      val = min if val < min
-      val = max if val > max
-      val
-    end
-  end
+      max = (1 << nbits) - 1
+      clamp = "val = (val < #{min}) ? #{min} : (val > #{max}) ? #{max} : val"
 
-  module BaseInt #:nodoc: all
-    def uint2int(val)
-      nbytes = val_num_bytes(0)
-      mask = (1 << (nbytes * 8 - 1)) - 1
-      msb = (val >> (nbytes * 8 - 1)) & 0x1
-      (msb == 1) ? -(((~val) & mask) + 1) : val & mask
-    end
+      read = create_read_code(nbits, endian)
+      to_s = create_to_s_code(nbits, endian)
 
-    def int2uint(val)
-      nbytes = val_num_bytes(0)
-      mask = (1 << (nbytes * 8)) - 1
-      val & mask
+      define_methods(klass, nbits / 8, clamp, read, to_s)
     end
 
-    def value=(val)
-      super(clamp(val))
+    def self.create_read_code(nbits, endian)
+      c16 = (endian == :little) ? 'v' : 'n'
+      c32 = (endian == :little) ? 'V' : 'N'
+      b1  = (endian == :little) ? 0 : 1
+      b2  = (endian == :little) ? 1 : 0
+
+      case nbits
+      when  8; "readbytes(io,1)[0]"
+      when 16; "readbytes(io,2).unpack('#{c16}').at(0)"
+      when 32; "readbytes(io,4).unpack('#{c32}').at(0)"
+      when 64; "(a = readbytes(io,8).unpack('#{c32 * 2}'); " +
+                     "(a.at(#{b2}) << 32) + a.at(#{b1}))"
+      else
+        raise "unknown nbits '#{nbits}'"
+      end
     end
 
-    #---------------
-    private
-
-    def sensible_default
-      0
+    def self.create_to_s_code(nbits, endian)
+      c16 = (endian == :little) ? 'v' : 'n'
+      c32 = (endian == :little) ? 'V' : 'N'
+      v1  = (endian == :little) ? 'val' : '(val >> 32)'
+      v2  = (endian == :little) ? '(val >> 32)' : 'val'
+
+      case nbits
+      when  8; "val.chr"
+      when 16; "[val].pack('#{c16}')"
+      when 32; "[val].pack('#{c32}')"
+      when 64; "[#{v1} & 0xffffffff, #{v2} & 0xffffffff].pack('#{c32 * 2}')"
+      else
+        raise "unknown nbits '#{nbits}'"
+      end
     end
 
-    def val_to_str(val)
-      _val_to_str(int2uint(clamp(val)))
-    end
-
-    def read_val(io)
-      uint2int(_read_val(io))
-    end
-
-    # Clamps +val+ to the range min_val .. max_val, where min and max
-    # are the largest representable integers.
-    def clamp(val)
-      nbytes = val_num_bytes(0)
-      max = (1 << (nbytes * 8 - 1)) - 1
-      min = -(max + 1)
-      val = min if val < min
-      val = max if val > max
-      val
+    def self.define_methods(klass, nbytes, clamp, read, to_s,
+                            int2uint = nil, uint2int = nil)
+      # define methods in the given class
+      klass.module_eval <<-END
+        def value=(val)
+          #{clamp}
+          super(val)
+        end
+
+        def _num_bytes(ignored)
+          #{nbytes}
+        end
+
+        #---------------
+        private
+
+        def sensible_default
+          0
+        end
+
+        def val_to_str(val)
+          #{clamp}
+          #{int2uint unless int2uint.nil?}
+          #{to_s}
+        end
+
+        def read_val(io)
+          val = #{read}
+          #{uint2int unless uint2int.nil?}
+        end
+      END
     end
   end
 
 
   # Unsigned 1 byte integer.
   class Uint8 < Single
-    include BaseUint
-    private
-    def val_num_bytes(val) 1 end
-    def read_val(io)       readbytes(io,1)[0] end
-    def _val_to_str(val)   val.chr end
+    Integer.create_uint_methods(self, 8, :little)
   end
 
   # Unsigned 2 byte little endian integer.
   class Uint16le < Single
-    include BaseUint
-    private
-    def val_num_bytes(val) 2 end
-    def read_val(io)       readbytes(io,2).unpack("v")[0] end
-    def _val_to_str(val)   [val].pack("v") end
+    Integer.create_uint_methods(self, 16, :little)
   end
 
   # Unsigned 2 byte big endian integer.
   class Uint16be < Single
-    include BaseUint
-    private
-    def val_num_bytes(val) 2 end
-    def read_val(io)       readbytes(io,2).unpack("n")[0] end
-    def _val_to_str(val)   [val].pack("n") end
+    Integer.create_uint_methods(self, 16, :big)
   end
 
   # Unsigned 4 byte little endian integer.
   class Uint32le < Single
-    include BaseUint
-    private
-    def val_num_bytes(val) 4 end
-    def read_val(io)       readbytes(io,4).unpack("V")[0] end
-    def _val_to_str(val)   [val].pack("V") end
+    Integer.create_uint_methods(self, 32, :little)
   end
 
   # Unsigned 4 byte big endian integer.
   class Uint32be < Single
-    include BaseUint
-    private
-    def val_num_bytes(val) 4 end
-    def read_val(io)       readbytes(io,4).unpack("N")[0] end
-    def _val_to_str(val)   [val].pack("N") end
+    Integer.create_uint_methods(self, 32, :big)
+  end
+
+  # Unsigned 8 byte little endian integer.
+  class Uint64le < Single
+    Integer.create_uint_methods(self, 64, :little)
+  end
+
+  # Unsigned 8 byte big endian integer.
+  class Uint64be < Single
+    Integer.create_uint_methods(self, 64, :big)
   end
 
   # Signed 1 byte integer.
   class Int8 < Single
-    include BaseInt
-    private
-    def val_num_bytes(val) 1 end
-    def _read_val(io)      readbytes(io,1)[0] end
-    def _val_to_str(val)   val.chr end
+    Integer.create_int_methods(self, 8, :little)
   end
 
   # Signed 2 byte little endian integer.
   class Int16le < Single
-    include BaseInt
-    private
-    def val_num_bytes(val) 2 end
-    def _read_val(io)      readbytes(io,2).unpack("v")[0] end
-    def _val_to_str(val)   [val].pack("v") end
+    Integer.create_int_methods(self, 16, :little)
   end
 
   # Signed 2 byte big endian integer.
   class Int16be < Single
-    include BaseInt
-    private
-    def val_num_bytes(val) 2 end
-    def _read_val(io)      readbytes(io,2).unpack("n")[0] end
-    def _val_to_str(val)   [val].pack("n") end
+    Integer.create_int_methods(self, 16, :big)
   end
 
   # Signed 4 byte little endian integer.
   class Int32le < Single
-    include BaseInt
-    private
-    def val_num_bytes(val) 4 end
-    def _read_val(io)      readbytes(io,4).unpack("V")[0] end
-    def _val_to_str(val)   [val].pack("V") end
+    Integer.create_int_methods(self, 32, :little)
   end
 
   # Signed 4 byte big endian integer.
   class Int32be < Single
-    include BaseInt
-    private
-    def val_num_bytes(val) 4 end
-    def _read_val(io)      readbytes(io,4).unpack("N")[0] end
-    def _val_to_str(val)   [val].pack("N") end
+    Integer.create_int_methods(self, 32, :big)
+  end
+
+  # Signed 8 byte little endian integer.
+  class Int64le < Single
+    Integer.create_int_methods(self, 64, :little)
+  end
+
+  # Signed 8 byte big endian integer.
+  class Int64be < Single
+    Integer.create_int_methods(self, 64, :big)
   end
 end

data/lib/bindata/lazy.rb

@@ -37,6 +37,11 @@ module BinData
       end
     end
 
+    # Returns the data_object for the parent environment.
+    def parent_data_object
+      @parent.nil? ? nil : @parent.data_object
+    end
+
     # Returns the value of the data object wrapped by this environment.
     def value
       @data_object.respond_to?(:value) ? @data_object.value : nil

data/lib/bindata/struct.rb

@@ -55,6 +55,20 @@ module BinData
         register(subclass.name, subclass)
       end
 
+      # Returns or sets the endianess of numerics used in this stucture.
+      # Endianess is propagated to nested data objects unless overridden
+      # in a nested Struct.
+      # Valid values are :little and :big.
+      def endian(endian = nil)
+        @endian ||= nil
+        if [:little, :big].include?(endian)
+          @endian = endian
+        elsif endian != nil
+          raise ArgumentError, "unknown value for endian '#{endian}'"
+        end
+        @endian
+      end
+
       # Returns the names of any hidden fields in this struct.  Any given args
       # are appended to the hidden list.
       def hide(*args)
@@ -106,7 +120,7 @@ module BinData
 
     # These are the parameters used by this class.
     mandatory_parameter :fields
-    optional_parameter :hide
+    optional_parameter :endian, :hide
 
     # Creates a new Struct.
     def initialize(params = {}, env = nil)
@@ -114,7 +128,7 @@ module BinData
 
       # create instances of the fields
       @fields = param(:fields).collect do |type, name, params|
-        klass = self.class.lookup(type)
+        klass = klass_lookup(type)
         raise TypeError, "unknown type '#{type}' for #{self}" if klass.nil?
         if methods.include?(name)
           raise NameError.new("field '#{name}' shadows an existing method",name)

data/spec/float_spec.rb

@@ -0,0 +1,105 @@
+#!/usr/bin/env ruby
+
+require File.expand_path(File.dirname(__FILE__)) + '/spec_common'
+require 'bindata/float'
+
+context "A FloatLe" do
+  setup do
+    @obj = BinData::FloatLe.new
+    @obj.value = Math::PI
+
+    @io = StringIO.new
+  end
+
+  specify "should write the expected value" do
+    @obj.write(@io)
+    @io.rewind
+
+    @io.read.should == [Math::PI].pack('e')
+  end
+
+  specify "should read the same value as written" do
+    @obj.write(@io)
+    @io.rewind
+
+    # check that we read in the same data that was written
+    @obj.read(@io)
+    @obj.value.should be_close(Math::PI, 0.000001)
+  end
+end
+
+context "A FloatBe" do
+  setup do
+    @obj = BinData::FloatBe.new
+    @obj.value = Math::PI
+
+    @io = StringIO.new
+  end
+
+  specify "should write the expected value" do
+    @obj.write(@io)
+    @io.rewind
+
+    @io.read.should == [Math::PI].pack('g')
+  end
+
+  specify "should read the same value as written" do
+    @obj.write(@io)
+    @io.rewind
+
+    # check that we read in the same data that was written
+    @obj.read(@io)
+    @obj.value.should be_close(Math::PI, 0.000001)
+  end
+end
+
+context "A DoubleLe" do
+  setup do
+    @obj = BinData::DoubleLe.new
+    @obj.value = Math::PI
+
+    @io = StringIO.new
+  end
+
+  specify "should write the expected value" do
+    @obj.write(@io)
+    @io.rewind
+
+    @io.read.should == [Math::PI].pack('E')
+  end
+
+  specify "should read the same value as written" do
+    @obj.write(@io)
+    @io.rewind
+
+    # check that we read in the same data that was written
+    @obj.read(@io)
+    @obj.value.should be_close(Math::PI, 0.000000000000000001)
+  end
+end
+
+
+context "A DoubleBe" do
+  setup do
+    @obj = BinData::DoubleBe.new
+    @obj.value = Math::PI
+
+    @io = StringIO.new
+  end
+
+  specify "should write the expected value" do
+    @obj.write(@io)
+    @io.rewind
+
+    @io.read.should == [Math::PI].pack('G')
+  end
+
+  specify "should read the same value as written" do
+    @obj.write(@io)
+    @io.rewind
+
+    # check that we read in the same data that was written
+    @obj.read(@io)
+    @obj.value.should be_close(Math::PI, 0.000000000000000001)
+  end
+end

data/spec/int_spec.rb

@@ -9,7 +9,9 @@ context "All signed integers" do
      BinData::Int16le,
      BinData::Int16be,
      BinData::Int32le,
-     BinData::Int32be].each do |klass|
+     BinData::Int32be,
+     BinData::Int64le,
+     BinData::Int64be].each do |klass|
       klass.new.value.should eql(0)
     end
   end
@@ -21,6 +23,8 @@ context "All signed integers" do
       [2, true,  BinData::Int16be],
       [4, false, BinData::Int32le],
       [4, true,  BinData::Int32be],
+      [8, false, BinData::Int64le],
+      [8, true,  BinData::Int64be],
     ].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)
@@ -35,7 +39,9 @@ context "All unsigned integers" do
      BinData::Uint16le,
      BinData::Uint16be,
      BinData::Uint32le,
-     BinData::Uint32be].each do |klass|
+     BinData::Uint32be,
+     BinData::Uint64le,
+     BinData::Uint64be].each do |klass|
       klass.new.value.should eql(0)
     end
   end
@@ -47,6 +53,8 @@ context "All unsigned integers" do
       [2, true,  BinData::Uint16be],
       [4, false, BinData::Uint32le],
       [4, true,  BinData::Uint32be],
+      [8, false, BinData::Uint64le],
+      [8, true,  BinData::Uint64be],
     ].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)

data/spec/struct_spec.rb

@@ -1,8 +1,7 @@
 #!/usr/bin/env ruby
 
 require File.expand_path(File.dirname(__FILE__)) + '/spec_common'
-require 'bindata/struct'
-require 'bindata/int'
+require 'bindata'
 
 context "A Struct with hidden fields" do
   context_setup do
@@ -72,6 +71,16 @@ context "Defining a Struct" do
       BinData::Struct.new(:fields => [[:int8, :object_id]])
     }.should raise_error(NameError)
   end
+
+  specify "should fail on unknown endian" do
+    lambda {
+      eval <<-END
+        class BadEndian < BinData::Struct
+          endian 'a bad value'
+        end
+      END
+    }.should raise_error(ArgumentError)
+  end
 end
 
 context "A Struct with multiple fields" do
@@ -202,3 +211,37 @@ context "A Struct with nested structs" do
   end
 end
 
+context "A Struct with an endian defined" do
+  context_setup do
+    eval <<-END
+      class StructWithEndian < BinData::Struct
+        endian :little
+
+        uint16 :a
+        float  :b
+        array  :c, :type => :int8, :initial_length => 2
+        choice :d, :choices => [ [:uint16], [:uint32] ], :selection => 1
+        struct :e, :fields => [ [:uint16, :f], [:uint32be, :g] ]
+      end
+    END
+    @obj = StructWithEndian.new
+  end
+
+  specify "should use correct endian" do
+    @obj.a = 1
+    @obj.b = 2.0
+    @obj.c[0] = 3
+    @obj.c[1] = 4
+    @obj.d = 5
+    @obj.e.f = 6
+    @obj.e.g = 7
+
+    expected = [1, 2.0, 3, 4, 5, 6, 7].pack('veCCVvN')
+
+    io = StringIO.new
+    @obj.write(io)
+
+    io.rewind
+    io.read.should == expected
+  end
+end

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.9.0
 specification_version: 1
 name: bindata
 version: !ruby/object:Gem::Version 
-  version: 0.5.1
-date: 2007-03-21 00:00:00 +09:00
+  version: 0.6.0
+date: 2007-03-28 00:00:00 +08:00
 summary: A declarative way to read and write binary file formats
 require_paths: 
 - lib
@@ -47,6 +47,7 @@ files:
 - spec/spec_common.rb
 - spec/array_spec.rb
 - spec/struct_spec.rb
+- spec/float_spec.rb
 - lib/bindata
 - lib/bindata.rb
 - lib/bindata/int.rb
@@ -59,6 +60,7 @@ files:
 - lib/bindata/choice.rb
 - lib/bindata/lazy.rb
 - lib/bindata/single.rb
+- lib/bindata/float.rb
 test_files: []
 
 rdoc_options: