bindata 0.7.0 → 0.8.0

data/ChangeLog

@@ -1,5 +1,13 @@
 = BinData Changelog
 
+-== Version 0.8.0 (2007-10-14)
+
+* Add reserved field names to Struct.
+* Prevent warnings about method redefinition.
+* Allow Struct to masquerade as one of its fields.
+* Renamed String param :initial_length to :read_length.
+* BinData::Array now behaves more like the internal ruby array.
+
 == Version 0.7.0 (2007-08-26)
 
 * Arrays now support terminating conditions as well as fixed length reads.

data/README

@@ -17,7 +17,7 @@ There is a better way.
 
   class Rectangle < BinData::Struct
     uint16le :len
-    string   :name, :initial_length => :len
+    string   :name, :read_length => :len
     uint32le :width
     uint32le :height
   end
@@ -102,7 +102,7 @@ Here's how we'd implement the same example with BinData.
 
   class PascalString < BinData::Struct
     uint8  :len,  :value => lambda { data.length }
-    string :data, :initial_length => :len
+    string :data, :read_length => :len
   end
 
   # reading
@@ -122,15 +122,15 @@ writing separately.
 
   class PascalStringReader < BinData::Struct
     uint8  :len
-    string :data, :initial_length => :len
+    string :data, :read_length => :len
   end
 
 This states that when reading the string, the initial length of the string
 (and hence the number of bytes to read) is determined by the value of the
 +len+ field.
 
-Note that <tt>:initial_length => :len</tt> is syntactic sugar for
-<tt>:initial_length => lambda { len }</tt>, but more on that later.
+Note that <tt>:read_length => :len</tt> is syntactic sugar for
+<tt>:read_length => lambda { len }</tt>, but more on that later.
 
   class PascalStringWriter < BinData::Struct
     uint8  :len, :value => lambda { data.length }

data/examples/gzip.rb

@@ -11,11 +11,11 @@ class Gzip
 
   class Extra < BinData::Struct
     uint16le :len,  :length => lambda { data.length }
-    string   :data, :initial_length => :len
+    string   :data, :read_length => :len
   end
 
   class Header < BinData::Struct
-    uint16le :id,         :value => 0x8b1f, :check_value => 0x8b1f
+    uint16le :ident,      :value => 0x8b1f, :check_value => 0x8b1f
     uint8    :compression_method, :initial_value => DEFLATE
     uint8    :flags,      :value => :calculate_flags_val,
                           # Upper 3 bits must be zero

data/lib/bindata.rb

@@ -10,5 +10,5 @@ require 'bindata/stringz'
 require 'bindata/struct'
 
 module BinData
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

data/lib/bindata/array.rb

@@ -128,37 +128,6 @@ module BinData
       []
     end
 
-    # Returns the first element, or the first +n+ elements, of the array.
-    # If the array is empty, the first form returns nil, and the second
-    # form returns an empty array.
-    def first(n = nil)
-      if n.nil?
-        self.length.zero? ? nil : self[0]
-      else
-        array = []
-        [n, self.length].min.times do |i|
-          array.push(self[i])
-        end
-        array
-      end
-    end
-
-    # Returns the last element, or the last +n+ elements, of the array.
-    # If the array is empty, the first form returns nil, and the second
-    # form returns an empty array.
-    def last(n = nil)
-      if n.nil?
-        self.length.zero? ? nil : self[self.length - 1]
-      else
-        array = []
-        start = self.length - [n, self.length].min
-        start.upto(self.length - 1) do |i|
-          array.push(self[i])
-        end
-        array
-      end
-    end
-
     # Appends a new element to the end of the array.  If the array contains
     # single_values then the +value+ may be provided to the call.
     # Returns the appended object, or value in the case of single_values.
@@ -170,10 +139,15 @@ module BinData
 
     # Returns the element at +index+.  If the element is a single_value
     # then the value of the element is returned instead.
-    def [](index)
-      obj = elements[index]
-      obj.single_value? ? obj.value : obj
+    def [](*index)
+      data = elements[*index]
+      if data.respond_to?(:each)
+        data.collect { |el| el.single_value? ? el.value : el }
+      else
+        data.single_value? ? data.value : data
+      end
     end
+    alias_method :slice, :[]
 
     # Sets the element at +index+.  If the element is a single_value
     # then the value of the element is set instead.
@@ -193,12 +167,53 @@ module BinData
       end
     end
 
+    # Returns the first element, or the first +n+ elements, of the array.
+    # If the array is empty, the first form returns nil, and the second
+    # form returns an empty array.
+    def first(n = nil)
+      if n.nil?
+        self.length.zero? ? nil : self[0]
+      else
+        array = []
+        [n, self.length].min.times do |i|
+          array.push(self[i])
+        end
+        array
+      end
+    end
+
+    # Returns the last element, or the last +n+ elements, of the array.
+    # If the array is empty, the first form returns nil, and the second
+    # form returns an empty array.
+    def last(n = nil)
+      if n.nil?
+        self.length.zero? ? nil : self[self.length - 1]
+      else
+        array = []
+        start = self.length - [n, self.length].min
+        start.upto(self.length - 1) do |i|
+          array.push(self[i])
+        end
+        array
+      end
+    end
+
     # The number of elements in this array.
     def length
       elements.length
     end
     alias_method :size, :length
 
+    # Returns true if self array contains no elements.
+    def empty?
+      length.zero?
+    end
+
+    # Allow this object to be used in array context.
+    def to_ary
+      snapshot
+    end
+
     #---------------
     private
 

data/lib/bindata/base.rb

@@ -157,13 +157,25 @@ module BinData
       klass
     end
 
+    # Returns a list of parameters that *weren't* provided to this object.
+    def unsupplied_parameters
+      supplied = @params.keys + @env.params.keys
+      self.class.parameters - supplied
+    end
+
     # Reads data into this bin object by calling #do_read then #done_read.
     def read(io)
+      # remove previous method to prevent warnings
+      class << io
+        undef_method(:bindata_mark) if method_defined?(:bindata_mark)
+      end
+
       # remember the current position in the IO object
-      io.instance_eval "def mark; #{io.pos}; end"
+      io.instance_eval "def bindata_mark; #{io.pos}; end"
 
       do_read(io)
       done_read
+      self
     end
 
     # Reads the value for this data from +io+.
@@ -189,6 +201,11 @@ module BinData
       respond_to? :value
     end
 
+    # Return a human readable representation of this object.
+    def inspect
+      snapshot.inspect
+    end
+
     #---------------
     private
 
@@ -230,7 +247,7 @@ module BinData
     # be called from #do_read before performing the reading.
     def check_offset(io)
       if has_param?(:check_offset)
-        actual_offset = io.pos - io.mark
+        actual_offset = io.pos - io.bindata_mark
         expected = eval_param(:check_offset, :offset => actual_offset)
 
         if not expected
@@ -242,7 +259,6 @@ module BinData
       end
     end
 
-=begin
     # To be implemented by subclasses
 
     # Resets the internal state to that of a newly created object.
@@ -281,7 +297,10 @@ module BinData
       raise NotImplementedError
     end
 
-    # To be implemented by subclasses
-=end
+    # Set visibility requirements of methods to implement
+    public :clear, :done_read, :snapshot, :field_names
+    private :_do_read, :_write, :_num_bytes
+
+    # End To be implemented by subclasses
   end
 end

data/lib/bindata/string.rb

@@ -9,8 +9,7 @@ module BinData
   # String objects accept all the params that BinData::Single
   # does, as well as the following:
   #
-  # <tt>:initial_length</tt>:: The initial length to use before a value is
-  #                            either read or set.
+  # <tt>:read_length</tt>::    The length to use when reading a value.
   # <tt>:length</tt>::         The fixed length of the string.  If a shorter
   #                            string is set, it will be padded to this length.
   # <tt>:pad_char</tt>::       The character to use when padding a string to a
@@ -23,17 +22,17 @@ module BinData
   class String < Single
     # These are the parameters used by this class.
     mandatory_parameters :pad_char
-    optional_parameters  :initial_length, :length, :trim_value
+    optional_parameters  :read_length, :length, :trim_value
 
     def initialize(params = {}, env = nil)
       super(cleaned_params(params), env)
 
       # the only valid param combinations of length and value are:
-      #   :initial_length and :value
+      #   :read_length and :value
+      #   :read_length and :initial_value
       #   :length and :initial_value
       ensure_mutual_exclusion(:initial_value, :value)
-      ensure_mutual_exclusion(:initial_length, :length)
-      ensure_mutual_exclusion(:initial_length, :initial_value)
+      ensure_mutual_exclusion(:read_length, :length)
       ensure_mutual_exclusion(:length, :value)
     end
 
@@ -51,7 +50,7 @@ module BinData
     # Returns +val+ ensuring that it is padded to the desired length.
     def val_to_str(val)
       # trim val if necessary
-      len = val_num_bytes(val)
+      len = eval_param(:length) || val.length
       str = val.slice(0, len)
 
       # then pad to length if str is short
@@ -60,7 +59,8 @@ module BinData
 
     # Read a number of bytes from +io+ and return the value they represent.
     def read_val(io)
-      readbytes(io, val_num_bytes(""))
+      len = eval_param(:read_length) || eval_param(:length) || 0
+      readbytes(io, len)
     end
 
     # Returns an empty string as default.
@@ -68,22 +68,17 @@ module BinData
       ""
     end
 
-    # Return the number of bytes that +val+ will occupy when written.
-    def val_num_bytes(val)
-      if clear? and (evaluated = eval_param(:initial_length))
-        evaluated
-      elsif (evaluated = eval_param(:length))
-        evaluated
-      else
-        val.length
-      end
-    end
-
     # Returns a hash of cleaned +params+.  Cleaning means that param
     # values are converted to a desired format.
     def cleaned_params(params)
       new_params = params.dup
 
+      # warn about deprecated param - remove before releasing 1.0
+      if params[:initial_length]
+        warn ":initial_length is deprecated. Replacing with :read_length"
+        new_params[:read_length] = params[:initial_length]
+      end
+
       # set :pad_char to be a single length character string
       ch = new_params[:pad_char] || 0
       ch = ch.respond_to?(:chr) ? ch.chr : ch.to_s

data/lib/bindata/struct.rb

@@ -22,22 +22,38 @@ module BinData
   #    obj = SomeStruct.new
   #    obj.field_names   =># ["b", "x", "y", "z"]
   #
+  #
+  #    class PascalString < BinData::Struct
+  #      delegate :data
+  #
+  #      int32le :len, :value => lambda { data.length }
+  #      string  :data, :read_length => :len
+  #    end
+  #
+  #    str = PascalString.new
+  #    str.value = "a test string"
+  #    str.single_value?   =># true
+  #    str.len         =># 13
+  #    str.num_bytes   =># 17
+  #
   # == Parameters
   #
   # Parameters may be provided at initialisation to control the behaviour of
   # an object.  These params are:
   #
-  # <tt>:fields</tt>:: An array specifying the fields for this struct.  Each
-  #                    element of the array is of the form
-  #                    [type, name, params].  Type is a symbol representing
-  #                    a registered type.  Name is the name of this field.
-  #                    Name may be nil as in the example above.  Params is an
-  #                    optional hash of parameters to pass to this field when
-  #                    instantiating it.
-  # <tt>:hide</tt>::   A list of the names of fields that are to be hidden
-  #                    from the outside world.  Hidden fields don't appear
-  #                    in #snapshot or #field_names but are still accessible
-  #                    by name.
+  # <tt>:fields</tt>::   An array specifying the fields for this struct.
+  #                      Each element of the array is of the form [type, name,
+  #                      params].  Type is a symbol representing a registered
+  #                      type.  Name is the name of this field.  Name may be
+  #                      nil as in the example above.  Params is an optional
+  #                      hash of parameters to pass to this field when
+  #                      instantiating it.
+  # <tt>:hide</tt>::     A list of the names of fields that are to be hidden
+  #                      from the outside world.  Hidden fields don't appear
+  #                      in #snapshot or #field_names but are still accessible
+  #                      by name.
+  # <tt>:delegate</tt>:: Forwards unknown methods calls and unknown params
+  #                      to this field.
   class Struct < Base
     # A hash that can be accessed via attributes.
     class Snapshot < Hash #:nodoc:
@@ -68,6 +84,16 @@ module BinData
         @endian
       end
 
+      # Returns the name of the delegate field for this struct.  The delegate
+      # is set to +name+ if given.
+      def delegate(name=nil)
+        @delegate ||= nil
+        if name != nil
+          @delegate = name.to_s
+        end
+        @delegate
+      end
+
       # Returns the names of any hidden fields in this struct.  Any given args
       # are appended to the hidden list.
       def hide(*args)
@@ -106,6 +132,12 @@ module BinData
                 "field '#{name}' shadows an existing method", caller
         end
 
+        # check that name isn't reserved
+        if Hash.instance_methods.include?(name) and delegate.nil?
+          raise NameError.new("", name),
+                "field '#{name}' is a reserved name", caller
+        end
+
         # remember this field.  These fields will be recalled upon creating
         # an instance of this class
         @fields.push([type, name, params])
@@ -119,23 +151,65 @@ module BinData
 
     # These are the parameters used by this class.
     mandatory_parameter :fields
-    optional_parameter :endian, :hide
+    optional_parameters :endian, :hide, :delegate
 
     # Creates a new Struct.
     def initialize(params = {}, env = nil)
       super(cleaned_params(params), env)
 
+      all_methods = methods
+      all_reserved_methods = nil
+      delegate_name = param(:delegate)
+
+      # get all reserved field names
+      res = param(:fields).find { |type, name, params| name == delegate_name }
+      if res
+        # all methods and field_names of the delegate are reserved.
+        klass_name = res[0]
+        delegate_klass = klass_lookup(klass_name)
+        if delegate_klass.nil?
+          raise TypeError, "unknown type '#{klass_name} for #{self}"
+        end
+
+        delegate_params = res[2]
+        delegate = delegate_klass.new(delegate_params, create_env)
+        all_reserved_methods = delegate.methods + delegate.field_names -
+                                 all_methods
+
+        # move unsupplied params from this object to the delegate object
+        delegate.unsupplied_parameters.each do |p|
+          if (v = @env.params.delete(p))
+            delegate_params[p] = v
+          end
+        end
+      else
+        # no delegate so all instance methods of Hash are reserved
+        all_reserved_methods = Hash.instance_methods - all_methods
+      end
+
       # create instances of the fields
       @fields = param(:fields).collect do |type, name, params|
         klass = klass_lookup(type)
         raise TypeError, "unknown type '#{type}' for #{self}" if klass.nil?
-        if methods.include?(name)
+        if all_methods.include?(name)
           raise NameError.new("field '#{name}' shadows an existing method",name)
         end
+        if all_reserved_methods.include?(name)
+          raise NameError.new("field '#{name}' is a reserved name",name)
+        end
         [name, klass.new(params, create_env)]
       end
     end
 
+    # Returns a list of parameters that *weren't* provided to this object.
+    def unsupplied_parameters
+      if delegate_object != nil
+        delegate_object.unsupplied_parameters
+      else
+        super
+      end
+    end
+
     # Clears the field represented by +name+.  If no +name+
     # is given, clears all fields in the struct.
     def clear(name = nil)
@@ -185,32 +259,39 @@ module BinData
 
     # Returns a snapshot of this struct as a hash.
     def snapshot
-      # allow structs to fake single value
-      return value if single_value?
-
-      hash = Snapshot.new
-      field_names.each do |name|
-        hash[name] = find_obj_for_name(name).snapshot
+      if delegate_object != nil
+        delegate_object.snapshot
+      else
+        hash = Snapshot.new
+        field_names.each do |name|
+          hash[name] = find_obj_for_name(name).snapshot
+        end
+        hash
       end
-      hash
     end
 
     # Returns a list of the names of all fields accessible through this
     # object.  +include_hidden+ specifies whether to include hidden names
     # in the listing.
     def field_names(include_hidden = false)
-      # single values don't have any fields
-      return [] if single_value?
-
-      names = []
-      @fields.each do |name, obj|
-        if name != ""
-          names << name unless (param(:hide).include?(name) and !include_hidden)
-        else
-          names.concat(obj.field_names)
+      if delegate_object != nil and !include_hidden
+        # delegate if possible
+        delegate_object.field_names
+      else
+        # collect field names
+        names = []
+        hidden = param(:hide)
+        @fields.each do |name, obj|
+          if name != ""
+            if include_hidden or not hidden.include?(name)
+              names << name
+            end
+          else
+            names.concat(obj.field_names)
+          end
         end
+        names
       end
-      names
     end
 
     # Returns the data object that stores values for +name+.
@@ -240,18 +321,18 @@ module BinData
       offset
     end
 
-    # Override to include field names.
+    # Override to include field names and delegate methods.
     alias_method :orig_respond_to?, :respond_to?
     def respond_to?(symbol, include_private = false)
       orig_respond_to?(symbol, include_private) ||
-        field_names(true).include?(symbol.id2name.chomp("="))
+        field_names(true).include?(symbol.id2name.chomp("=")) ||
+          delegate_object.respond_to?(symbol, include_private)
     end
 
     # Returns whether this data object contains a single value.  Single
     # value data objects respond to <tt>#value</tt> and <tt>#value=</tt>.
     def single_value?
-      # need to use original respond_to? to prevent infinite recursion
-      orig_respond_to?(:value)
+      delegate_object ? delegate_object.single_value? : false
     end
 
     def method_missing(symbol, *args)
@@ -270,6 +351,8 @@ module BinData
         else
           obj
         end
+      elsif delegate_object.respond_to?(symbol)
+        delegate_object.__send__(symbol, *args)
       else
         super
       end
@@ -278,6 +361,15 @@ module BinData
     #---------------
     private
 
+    # Returns the delegate object if any.
+    def delegate_object
+      if (name = param(:delegate))
+        find_obj_for_name(name)
+      else
+        nil
+      end
+    end
+
     # Returns a list of all the bindata objects for this struct.
     def bindata_objects
       @fields.collect { |f| f[1] }
@@ -308,6 +400,12 @@ module BinData
       end
       new_params[:hide] = hide
 
+      # collect delegate name if it corresponds to a field name
+      if (delegate = (new_params[:delegate] || self.class.delegate))
+        delegate = delegate.to_s
+        new_params[:delegate] = delegate if field_names.include?(delegate)
+      end
+
       new_params
     end
   end

data/spec/array_spec.rb

@@ -33,6 +33,10 @@ describe "An Array with no elements" do
     @data.length.should be_zero
   end
 
+  it "should be empty" do
+    @data.should be_empty
+  end
+
   it "should return nil for the first element" do
     @data.first.should be_nil
   end
@@ -66,22 +70,30 @@ describe "An Array with several elements" do
     @data.snapshot.should eql([1, 2, 3, 4, 5])
   end
 
+  it "should coerce to ::Array if required" do
+    ((1..7).to_a - @data).should eql([6, 7])
+  end
+
   it "should return the first element" do
     @data.first.should eql(1)
   end
 
   it "should return the first n elements" do
+    @data[0...3].should eql([1, 2, 3])
     @data.first(3).should eql([1, 2, 3])
     @data.first(99).should eql([1, 2, 3, 4, 5])
   end
 
   it "should return the last element" do
     @data.last.should eql(5)
+    @data[-1].should eql(5)
   end
 
   it "should return the last n elements" do
     @data.last(3).should eql([3, 4, 5])
     @data.last(99).should eql([1, 2, 3, 4, 5])
+
+    @data[-3, 100].should eql([3, 4, 5])
   end
 
   it "should have correct num elements" do
@@ -106,6 +118,14 @@ describe "An Array with several elements" do
     @data[1].should eql(8)
   end
 
+  it "should not be empty" do
+    @data.should_not be_empty
+  end
+
+  it "should return a nicely formatted array  for inspect" do
+    @data.inspect.should eql("[1, 2, 3, 4, 5]")
+  end
+
   it "should be able to use methods from Enumerable" do
     @data.select { |x| (x % 2) == 0 }.should eql([2, 4])
   end
@@ -170,6 +190,10 @@ describe "An Array containing structs" do
     @data[3].a.should eql(3)
   end
 
+  it "should access multiple elements with slice" do
+    @data.slice(2, 3).collect { |x| x.a }.should eql([2, 3, 4])
+  end
+
   it "should not be able to modify elements" do
     lambda { @data[1] = 3 }.should raise_error(NoMethodError)
   end

data/spec/base_spec.rb

@@ -93,6 +93,14 @@ describe "A data object with parameters" do
     obj.param(:p2).should be_nil
     obj.param(:p3).should respond_to(:arity)
   end
+
+  it "should identify unsupplied parameters" do
+    obj = WithParam.new(:p1 => 1, :p3 => 3, :p4 => 4, :p5 => 5)
+    obj.unsupplied_parameters.should include(:p2)
+    obj.unsupplied_parameters.should_not include(:p1)
+    obj.unsupplied_parameters.should_not include(:p3)
+    obj.unsupplied_parameters.should_not include(:p4)
+  end
 end
 
 describe "A data object with :check_offset" do
@@ -192,3 +200,24 @@ describe "A data object defining a value method" do
     obj.should be_a_single_value
   end
 end
+
+describe "A subclass of Base" do
+  before(:all) do
+    eval <<-END
+      class SubClassOfBase < BinData::Base
+        public :_do_read, :_write, :_num_bytes
+      end
+    END
+    @obj = SubClassOfBase.new
+  end
+
+  it "should raise errors on unimplemented methods" do
+    lambda { @obj.clear }.should raise_error(NotImplementedError)
+    lambda { @obj.done_read }.should raise_error(NotImplementedError)
+    lambda { @obj.snapshot }.should raise_error(NotImplementedError)
+    lambda { @obj.field_names }.should raise_error(NotImplementedError)
+    lambda { @obj._do_read(nil) }.should raise_error(NotImplementedError)
+    lambda { @obj._write(nil) }.should raise_error(NotImplementedError)
+    lambda { @obj._num_bytes }.should raise_error(NotImplementedError)
+  end
+end

data/spec/string_spec.rb

@@ -9,13 +9,8 @@ describe "Test mutual exclusion of parameters" do
     lambda { BinData::String.new(params) }.should raise_error(ArgumentError)
   end
 
-  it ":length and :initial_length" do
-    params = {:length => 5, :initial_length => 5}
-    lambda { BinData::String.new(params) }.should raise_error(ArgumentError)
-  end
-
-  it ":initial_value and :initial_length" do
-    params = {:initial_value => "", :initial_length => 5}
+  it ":length and :read_length" do
+    params = {:length => 5, :read_length => 5}
     lambda { BinData::String.new(params) }.should raise_error(ArgumentError)
   end
 
@@ -25,35 +20,38 @@ describe "Test mutual exclusion of parameters" do
   end
 end
 
-describe "A String with :initial_length" do
-  before(:each) do
-    @str = BinData::String.new(:initial_length => 5)
+describe "A String with deprecated parameters" do
+  it "should substitude :read_length for :initial_length" do
+    obj = BinData::String.new(:initial_length => 3)
+    io = StringIO.new("abcdefghij")
+    obj.read(io)
+    obj.value.should eql("abc")
   end
+end
 
-  it "should set num_bytes" do
-    @str.num_bytes.should eql(5)
+describe "A String with :read_length" do
+  before(:each) do
+    @str = BinData::String.new(:read_length => 5)
   end
 
-  it "should fill value with pad_char" do
-    @str.value.should eql("\0\0\0\0\0")
+  it "should have default value" do
+    @str.num_bytes.should eql(0)
+    @str.value.should eql("")
   end
 
-  it "should read :initial_length bytes" do
+  it "should read :read_length bytes" do
     io = StringIO.new("abcdefghij")
     @str.read(io)
     @str.value.should eql("abcde")
   end
 
-  it "should forget :initial_length after value is set" do
-    @str.value = "abc"
-    @str.num_bytes.should eql(3)
-  end
-
-  it "should remember :initial_length after value is cleared" do
+  it "should remember :read_length after value is cleared" do
     @str.value = "abc"
     @str.num_bytes.should eql(3)
     @str.clear
-    @str.num_bytes.should eql(5)
+    io = StringIO.new("abcdefghij")
+    @str.read(io)
+    @str.value.should eql("abcde")
   end
 end
 
@@ -97,23 +95,48 @@ describe "A String with :length" do
   end
 end
 
-describe "A String with :initial_length and :value" do
+describe "A String with :read_length and :initial_value" do
   before(:each) do
-    @str = BinData::String.new(:initial_length => 5, :value => "abcdefghij")
+    @str = BinData::String.new(:read_length => 5, :initial_value => "abcdefghij")
+  end
+
+  it "should use :initial_value before value is read" do
+    @str.num_bytes.should eql(10)
+    @str.value.should eql("abcdefghij")
   end
 
-  it "should use :initial_length before value is read" do
+  it "should use :read_length for reading" do
+    io = StringIO.new("ABCDEFGHIJKLMNOPQRST")
+    @str.read(io)
+    io.pos.should eql(5)
+   end
+
+  it "should forget :initial_value after reading" do
+    io = StringIO.new("ABCDEFGHIJKLMNOPQRST")
+    @str.read(io)
     @str.num_bytes.should eql(5)
-    @str.value.should eql("abcde")
+    @str.value.should eql("ABCDE")
+  end
+
+end
+
+describe "A String with :read_length and :value" do
+  before(:each) do
+    @str = BinData::String.new(:read_length => 5, :value => "abcdefghij")
+  end
+
+  it "should not be affected by :read_length before value is read" do
+    @str.num_bytes.should eql(10)
+    @str.value.should eql("abcdefghij")
   end
 
-  it "should use :initial_length for reading" do
+  it "should use :read_length for reading" do
     io = StringIO.new("ABCDEFGHIJKLMNOPQRST")
     @str.read(io)
     io.pos.should eql(5)
    end
 
-  it "should forget :initial_length after reading" do
+  it "should not be affected by :read_length after reading" do
     io = StringIO.new("ABCDEFGHIJKLMNOPQRST")
     @str.read(io)
     @str.num_bytes.should eql(10)

data/spec/struct_spec.rb

@@ -6,7 +6,7 @@ require 'bindata'
 describe "A Struct with hidden fields" do
   before(:all) do
     eval <<-END
-      class TestStruct < BinData::Struct
+      class HiddenStruct < BinData::Struct
         hide :b, 'c'
         int8 :a
         int8 'b', :initial_value => 10
@@ -14,7 +14,7 @@ describe "A Struct with hidden fields" do
         int8 :d, :value => :b
       end
     END
-    @obj = TestStruct.new
+    @obj = HiddenStruct.new
   end
 
   it "should only show fields that aren't hidden" do
@@ -35,7 +35,88 @@ describe "A Struct with hidden fields" do
   end
 end
 
+describe "A Struct that delegates" do
+  before(:all) do
+    eval <<-END
+      class DelegateStruct < BinData::Struct
+        delegate :b
+        int8 :a, :initial_value => :num
+        int8 'b'
+        int8 :c, :value => :b
+      end
+    END
+    @obj = DelegateStruct.new(:num => 5)
+  end
+
+  it "should access custom parameters" do
+    @obj.a.should eql(5)
+  end
+
+  it "should have correct num_bytes" do
+    @obj.num_bytes.should eql(3)
+  end
+
+  it "should delegate snapshot" do
+    @obj.value = 6
+    @obj.snapshot.should eql(6)
+  end
+
+  it "should delegate single_value?" do
+    @obj.should be_a_single_value
+  end
+
+  it "should delegate methods" do
+    @obj.should respond_to?(:value)
+    @obj.value = 7
+    @obj.c.should eql(7)
+  end
+
+  it "should identify unsupplied parameters" do
+    @obj.unsupplied_parameters.should include(:check_value)
+    @obj.unsupplied_parameters.should include(:initial_value)
+    @obj.unsupplied_parameters.should include(:value)
+    @obj.unsupplied_parameters.should_not include(:endian)
+  end
+
+  it "should pass params when creating" do
+    obj = DelegateStruct.new(:initial_value => :val, :val => 14)
+    obj.value.should eql(14)
+  end
+end
+
+describe "A Struct with nested delegation" do
+  before(:all) do
+    eval <<-END
+      class DelegateOuterStruct < BinData::Struct
+        endian :little
+        delegate :b
+        int8 :a
+        struct :b, :delegate => :y,
+                   :fields => [[:int8, :x], [:int32, :y], [:int8, :z]]
+      end
+    END
+    @obj = DelegateOuterStruct.new(:initial_value => 7)
+  end
+
+  it "should followed nested delegation" do
+    @obj.should be_a_single_value
+    @obj.field_names.should eql([])
+  end
+
+  it "should forward parameters" do
+    @obj.should respond_to?(:value)
+    @obj.value.should eql(7)
+  end
+
+  it "should identify unsupplied parameters" do
+    @obj.unsupplied_parameters.should include(:check_value)
+    @obj.unsupplied_parameters.should include(:value)
+  end
+end
+
 describe "Defining a Struct" do
+  before(:all) do
+  end
   it "should fail on non registered types" do
     lambda {
       eval <<-END
@@ -44,6 +125,15 @@ describe "Defining a Struct" do
         end
       END
     }.should raise_error(TypeError)
+
+    lambda {
+      BinData::Struct.new(:fields => [[:non_registered_type, :a]])
+    }.should raise_error(TypeError)
+
+    lambda {
+      BinData::Struct.new(:delegate => :a,
+                          :fields => [[:non_registered_type, :a]])
+    }.should raise_error(TypeError)
   end
 
   it "should fail on duplicate names" do
@@ -58,6 +148,30 @@ describe "Defining a Struct" do
     }.should raise_error(SyntaxError)
   end
 
+  it "should fail on reserved names" do
+    lambda {
+      eval <<-END
+        class ReservedName < BinData::Struct
+          int8 :a
+          int8 :invert # from Hash.instance_methods
+        end
+      END
+    }.should raise_error(NameError)
+
+    lambda {
+      # :invert is from Hash.instance_methods
+      BinData::Struct.new(:fields => [[:int8, :a], [:int8, :invert]])
+    }.should raise_error(NameError)
+  end
+
+  it "should fail on reserved names of delegated fields" do
+    lambda {
+      # :value is from Int8.instance_methods
+      BinData::Struct.new(:delegate => :a,
+                          :fields => [[:int8, :a], [:int8, :value]])
+    }.should raise_error(NameError)
+  end
+
   it "should fail when field name shadows an existing method" do
     lambda {
       eval <<-END
@@ -97,6 +211,11 @@ describe "A Struct with multiple fields" do
     @obj.num_bytes.should     eql(2)
   end
 
+  it "should identify unsupplied parameters" do
+    @obj.unsupplied_parameters.should include(:delegate)
+    @obj.unsupplied_parameters.should include(:endian)
+  end
+
   it "should clear" do
     @obj.a = 6
     @obj.clear
@@ -143,34 +262,6 @@ describe "A Struct with multiple fields" do
   end
 end
 
-describe "A Struct with a value method" do
-  before(:all) do
-    eval <<-END
-      class StructWithValue < BinData::Struct
-        int8 :a
-        int8 :b
-
-        def value
-          a
-        end
-      end
-    END
-    @obj = StructWithValue.new
-  end
-
-  it "should be single value object" do
-    @obj.should be_a_single_value
-  end
-
-  it "should have no field names" do
-    @obj.field_names.should be_empty
-  end
-
-  it "should not respond to field accesses" do
-    @obj.should_not respond_to?(:a)
-  end
-end
-
 describe "A Struct with nested structs" do
   before(:all) do
     eval <<-END
@@ -222,6 +313,7 @@ describe "A Struct with an endian defined" do
         array  :c, :type => :int8, :initial_length => 2
         choice :d, :choices => [ [:uint16], [:uint32] ], :selection => 1
         struct :e, :fields => [ [:uint16, :f], [:uint32be, :g] ]
+        struct :h, :fields => [ [:struct, :i, {:fields => [[:uint16, :j]]}] ]
       end
     END
     @obj = StructWithEndian.new
@@ -235,8 +327,9 @@ describe "A Struct with an endian defined" do
     @obj.d = 5
     @obj.e.f = 6
     @obj.e.g = 7
+    @obj.h.i.j = 8
 
-    expected = [1, 2.0, 3, 4, 5, 6, 7].pack('veCCVvN')
+    expected = [1, 2.0, 3, 4, 5, 6, 7, 8].pack('veCCVvNv')
 
     io = StringIO.new
     @obj.write(io)

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.9.0
 specification_version: 1
 name: bindata
 version: !ruby/object:Gem::Version 
-  version: 0.7.0
-date: 2007-08-27 00:00:00 +08:00
+  version: 0.8.0
+date: 2007-10-14 00:00:00 +08:00
 summary: A declarative way to read and write binary file formats
 require_paths: 
 - lib