bindata 0.6.0 → 0.7.0

data/ChangeLog

@@ -1,5 +1,12 @@
 = BinData Changelog
 
+== Version 0.7.0 (2007-08-26)
+
+* Arrays now support terminating conditions as well as fixed length reads.
+* Updated specs to new rspec syntax (0.9).
+* Added scoped resolution of variables in lambdas.
+* Added ability to append elements to arrays.
+
 == Version 0.6.0 (2007-03-28)
 
 * Added 64 bit integers.

data/README

@@ -157,12 +157,16 @@ BinData::Int16le::  Signed 16 bit integer (little endian).
 BinData::Int16be::  Signed 16 bit integer (big endian).
 BinData::Int32le::  Signed 32 bit integer (little endian).
 BinData::Int32be::  Signed 32 bit integer (big endian).
+BinData::Int64le::  Signed 64 bit integer (little endian).
+BinData::Int64be::  Signed 64 bit integer (big endian).
 
 BinData::Uint8::    Unsigned  8 bit integer.
 BinData::Uint16le:: Unsigned 16 bit integer (little endian).
 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::Uint64le:: Unsigned 64 bit integer (little endian).
+BinData::Uint64be:: Unsigned 64 bit integer (big endian).
 
 BinData::FloatLe::  Single precision floating point number (little endian).
 BinData::FloatBe::  Single precision floating point number (big endian).

data/TODO

@@ -1,8 +1,3 @@
-* Add a way to do something like: read a bunch of integers and stop reading
-  after reading an integer with a value of 0.
-
-* Add scoping so the value of a param doesn't need to call parent
-
 * Think how offset_of should work.
 
 * Need optional parameter for fields

data/lib/bindata.rb

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

data/lib/bindata/array.rb

@@ -21,6 +21,15 @@ module BinData
   #                            passed to it, then it should be provided as
   #                            <tt>[type_symbol, hash_params]</tt>.
   # <tt>:initial_length</tt>:: The initial length of the array.
+  # <tt>:read_until</tt>::     While reading, elements are read until this
+  #                            condition is true.  This is typically used to
+  #                            read an array until a sentinel value is found.
+  #                            The variables +index+, +element+ and +array+
+  #                            are made available to any lambda assigned to
+  #                            this parameter.
+  #
+  # Each data object in an array has the variable +index+ made available
+  # to any lambda evaluated as a parameter of that data object.
   class Array < Base
     include Enumerable
 
@@ -28,11 +37,13 @@ module BinData
     register(self.name, self)
 
     # These are the parameters used by this class.
-    mandatory_parameters :type, :initial_length
+    mandatory_parameter :type
+    optional_parameters :initial_length, :read_until
 
     # Creates a new Array
     def initialize(params = {}, env = nil)
-      super(params, env)
+      super(cleaned_params(params), env)
+      ensure_mutual_exclusion(:initial_length, :read_until)
 
       type, el_params = param(:type)
       klass = klass_lookup(type)
@@ -41,8 +52,6 @@ module BinData
       @element_list    = nil
       @element_klass   = klass
       @element_params  = el_params || {}
-
-      # TODO: how to increase the size of the array?
     end
 
     # Clears the element at position +index+.  If +index+ is not given, then
@@ -73,7 +82,19 @@ module BinData
 
     # Reads the values for all fields in this object from +io+.
     def _do_read(io)
-      elements.each { |f| f.do_read(io) }
+      if has_param?(:initial_length)
+        elements.each { |f| f.do_read(io) }
+      else # :read_until
+        @element_list = nil
+        loop do
+          element = append_new_element
+          element.do_read(io)
+          variables = { :index => self.length - 1, :element => self.last,
+                        :array => self }
+          finished = eval_param(:read_until, variables)
+          break if finished
+        end
+      end
     end
 
     # To be called after calling #do_read.
@@ -107,6 +128,46 @@ 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.
+    def append(value = nil)
+      append_new_element
+      self[self.length - 1] = value unless value.nil?
+      self.last
+    end
+
     # Returns the element at +index+.  If the element is a single_value
     # then the value of the element is returned instead.
     def [](index)
@@ -146,15 +207,39 @@ module BinData
     def elements
       if @element_list.nil?
         @element_list = []
-
-        # create the desired number of instances
-        eval_param(:initial_length).times do |i|
-          env = create_env
-          env.index = i
-          @element_list << @element_klass.new(@element_params, env)
+        if has_param?(:initial_length)
+          # create the desired number of instances
+          eval_param(:initial_length).times do
+            append_new_element
+          end
         end
       end
       @element_list
     end
+
+    # Creates a new element and appends it to the end of @element_list.
+    # Returns the newly created element
+    def append_new_element
+      # ensure @element_list is initialised
+      elements()
+
+      env = create_env
+      env.add_variable(:index, @element_list.length)
+      element = @element_klass.new(@element_params, env)
+      @element_list << element
+      element
+    end
+
+    # Returns a hash of cleaned +params+.  Cleaning means that param
+    # values are converted to a desired format.
+    def cleaned_params(params)
+      unless params.has_key?(:initial_length) or params.has_key?(:read_until)
+        # ensure one of :initial_length and :read_until exists
+        new_params = params.dup
+        new_params[:initial_length] = 0
+        params = new_params
+      end
+      params
+    end
   end
 end

data/lib/bindata/base.rb

@@ -14,11 +14,13 @@ module BinData
   #
   # [<tt>:readwrite</tt>]     If false, calls to #read or #write will
   #                           not perform any I/O.  Default is true.
-  # [<tt>:check_offset</tt>]  Raise an error if the current IO offest doesn't
+  # [<tt>:check_offset</tt>]  Raise an error if the current IO offset doesn't
   #                           meet this criteria.  A boolean return indicates
   #                           success or failure.  Any other return is compared
-  #                           to the current offset.  This parameter is
-  #                           only checked before reading.
+  #                           to the current offset.  The variable +offset+
+  #                           is made available to any lambda assigned to
+  #                           this parameter.  This parameter is only checked
+  #                           before reading.
   class Base
     class << self
       # Returns the mandatory parameters used by this class.  Any given args
@@ -33,7 +35,7 @@ module BinData
             end
           end
         end
-        unless (args.empty?)
+        if not args.empty?
           args.each { |arg| @mandatory_parameters << arg.to_sym }
           @mandatory_parameters.uniq!
         end
@@ -53,7 +55,7 @@ module BinData
             end
           end
         end
-        unless (args.empty?)
+        if not args.empty?
           args.each { |arg| @optional_parameters << arg.to_sym }
           @optional_parameters.uniq!
         end
@@ -111,14 +113,14 @@ module BinData
     # environment that these callable objects are evaluated in.
     def initialize(params = {}, env = nil)
       # default :readwrite param to true if unspecified
-      unless params.has_key?(:readwrite)
+      if not params.has_key?(:readwrite)
         params = params.dup
         params[:readwrite] = true
       end
 
       # ensure mandatory parameters exist
       self.class.mandatory_parameters.each do |prm|
-        unless params.has_key?(prm)
+        if not params.has_key?(prm)
           raise ArgumentError, "parameter ':#{prm}' must be specified " +
                                "in #{self}"
         end
@@ -197,9 +199,10 @@ module BinData
 
     # Returns the value of the evaluated parameter.  +key+ references a
     # parameter from the +params+ hash used when creating the data object.
+    # +values+ contains data that may be accessed when evaluating +key+.
     # Returns nil if +key+ does not refer to any parameter.
-    def eval_param(key)
-      @env.lazy_eval(@params[key])
+    def eval_param(key, values = {})
+      @env.lazy_eval(@params[key], values)
     end
 
     # Returns the parameter from the +params+ hash referenced by +key+.
@@ -227,13 +230,13 @@ module BinData
     # be called from #do_read before performing the reading.
     def check_offset(io)
       if has_param?(:check_offset)
-        @env.offset = io.pos - io.mark
-        expected = eval_param(:check_offset)
+        actual_offset = io.pos - io.mark
+        expected = eval_param(:check_offset, :offset => actual_offset)
 
         if not expected
           raise ValidityError, "offset not as expected"
-        elsif @env.offset != expected and expected != true
-          raise ValidityError, "offset is '#{@env.offset}' but " +
+        elsif actual_offset != expected and expected != true
+          raise ValidityError, "offset is '#{actual_offset}' but " +
                                "expected '#{expected}'"
         end
       end

data/lib/bindata/lazy.rb

@@ -7,11 +7,8 @@ module BinData
   # params:: any extra parameters that have been passed to the data object.
   #          The value of a parameter is either a lambda, a symbol or a
   #          literal value (such as a Fixnum).
-  # value::  the value of the data object if it is single
-  # index::  the index of the data object if it is in an array
-  # offset:: the current offset of the IO object when reading
   #
-  # Unknown methods are resolved in the context of the parent data object,
+  # Unknown methods are resolved in the context of the parent environment,
   # first as keys in the extra parameters, and secondly as methods in the
   # parent data object.  This makes the lambda easier to read as we just write
   # <tt>field</tt> instead of <tt>obj.field</tt>.
@@ -20,21 +17,27 @@ module BinData
     # parent data object.
     def initialize(parent = nil)
       @parent = parent
+      @variables = {}
+      @overrides = {}
     end
     attr_reader :parent
-    attr_accessor :data_object, :params, :index, :offset
+    attr_accessor :data_object, :params
 
     # only accessible by another LazyEvalEnv
     protected :data_object
 
+    # Add a variable with a pre-assigned value to this environment.  +sym+
+    # will be accessible as a variable for any lambda evaluated
+    # with #lazy_eval.
+    def add_variable(sym, value)
+      @variables[sym.to_sym] = value
+    end
+
     # TODO: offset_of needs to be better thought out
     def offset_of(sym)
-      if @parent and @parent.data_object and
-              @parent.data_object.respond_to?(:offset_of)
-        @parent.data_object.offset_of(sym)
-      else
-        nil
-      end
+      @parent.data_object.offset_of(sym)
+    rescue
+      nil
     end
 
     # Returns the data_object for the parent environment.
@@ -42,32 +45,33 @@ module BinData
       @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
-    end
-
     # Evaluates +obj+ in the context of this environment.  Evaluation
     # recurses until it yields a value that is not a symbol or lambda.
-    def lazy_eval(obj)
+    def lazy_eval(obj, overrides = {})
+      @overrides = overrides
       if obj.is_a? Symbol
         # treat :foo as lambda { foo }
-        lazy_eval(__send__(obj))
+        obj = __send__(obj)
       elsif obj.respond_to? :arity
-        instance_eval(&obj)
-      else
-        obj
+        obj = instance_eval(&obj)
       end
+      @overrides = {}
+      obj
     end
 
     def method_missing(symbol, *args)
-      if @parent and @parent.params and @parent.params.has_key?(symbol)
-        # is there a param with this name?
-        @parent.lazy_eval(@parent.params[symbol])
-      elsif @parent and @parent.data_object and
-              @parent.data_object.respond_to?(symbol)
-        # how about a field or method in the parent?
-        @parent.data_object.__send__(symbol, *args)
+      if @overrides.include?(symbol)
+        @overrides[symbol]
+      elsif @variables.include?(symbol)
+        @variables[symbol]
+      elsif @parent
+        obj = symbol
+        if @parent.params and @parent.params.has_key?(symbol)
+          obj = @parent.params[symbol]
+        elsif @parent.data_object and @parent.data_object.respond_to?(symbol)
+          obj = @parent.data_object.__send__(symbol, *args)
+        end
+        @parent.lazy_eval(obj)
       else
         super
       end

data/lib/bindata/single.rb

@@ -20,9 +20,11 @@ module BinData
   #                           will return the value of the data read from the
   #                           IO, not the result of the <tt>:value</tt> param.
   # [<tt>:check_value</tt>]   Raise an error unless the value read in meets
-  #                           this criteria.  A boolean return indicates
-  #                           success or failure.  Any other return is compared
-  #                           to the value just read in.
+  #                           this criteria.  The variable +value+ is made
+  #                           available to any lambda assigned to this
+  #                           parameter.  A boolean return indicates success
+  #                           or failure.  Any other return is compared to
+  #                           the value just read in.
   class Single < Base
     # These are the parameters used by this class.
     optional_parameters :initial_value, :value, :check_value
@@ -56,11 +58,12 @@ module BinData
 
       # does the value meet expectations?
       if has_param?(:check_value)
-        expected = eval_param(:check_value)
+        current_value = self.value
+        expected = eval_param(:check_value, :value => current_value)
         if not expected
           raise ValidityError, "value not as expected"
-        elsif @value != expected and expected != true
-          raise ValidityError, "value is '#{@value}' but " +
+        elsif current_value != expected and expected != true
+          raise ValidityError, "value is '#{current_value}' but " +
                                "expected '#{expected}'"
         end
       end

data/lib/bindata/struct.rb

@@ -56,8 +56,7 @@ module BinData
       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.
+      # Endianess is applied to the fields of this structure.
       # Valid values are :little and :big.
       def endian(endian = nil)
         @endian ||= nil

data/spec/array_spec.rb

@@ -5,87 +5,140 @@ require 'bindata/array'
 require 'bindata/int'
 require 'bindata/struct'
 
-context "Instantiating an Array" do
-  specify "should ensure mandatory parameters are supplied" do
+describe "Instantiating an Array" do
+  it "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
+  it "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
+
+  it "should not allow both :initial_length and :read_until" do
+    args = {:initial_length => 3, :read_until => lambda { false } }
+    lambda { BinData::Array.new(args) }.should raise_error(ArgumentError)
+  end
+end
+
+describe "An Array with no elements" do
+  before(:each) do
+    @data = BinData::Array.new(:type => :int8)
+  end
+
+  it "should return correct length" do
+    @data.length.should be_zero
+  end
+
+  it "should return nil for the first element" do
+    @data.first.should be_nil
+  end
+
+  it "should return [] for the first n elements" do
+    @data.first(3).should eql([])
+  end
+
+  it "should return nil for the last element" do
+    @data.last.should be_nil
+  end
+
+  it "should return [] for the last n elements" do
+    @data.last(3).should eql([])
+  end
+
+  it "should append an element" do
+    @data.append(99)
+    @data.length.should eql(1)
+    @data.last.should eql(99)
+  end
 end
 
-context "An Array with several elements" do
-  setup do
+describe "An Array with several elements" do
+  before(:each) 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
+  it "should return a correct snapshot" do
     @data.snapshot.should eql([1, 2, 3, 4, 5])
   end
 
-  specify "should have correct num elements" do
+  it "should return the first element" do
+    @data.first.should eql(1)
+  end
+
+  it "should return the first n elements" do
+    @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)
+  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])
+  end
+
+  it "should have correct num elements" do
     @data.length.should eql(5)
     @data.size.should eql(5)
   end
 
-  specify "should have correct num_bytes" do
+  it "should have correct num_bytes" do
     @data.num_bytes.should eql(10)
   end
 
-  specify "should have correct num_bytes for individual elements" do
+  it "should have correct num_bytes for individual elements" do
     @data.num_bytes(0).should eql(2)
   end
 
-  specify "should have no field_names" do
+  it "should have no field_names" do
     @data.field_names.should be_empty
   end
 
-  specify "should be able to directly access elements" do
+  it "should be able to directly access elements" do
     @data[1] = 8
     @data[1].should eql(8)
   end
 
-  specify "should be able to use methods from Enumerable" do
+  it "should be able to use methods from Enumerable" do
     @data.select { |x| (x % 2) == 0 }.should eql([2, 4])
   end
 
-  specify "should clear" do
+  it "should clear" do
     @data[1] = 8
     @data.clear
     @data.collect.should eql([1, 2, 3, 4, 5])
   end
 
-  specify "should clear a single element" do
+  it "should clear a single element" do
     @data[1] = 8
     @data.clear(1)
     @data[1].should eql(2)
   end
 
-  specify "should be clear upon creation" do
+  it "should be clear upon creation" do
     @data.clear?.should be_true
   end
 
-  specify "should be clear if all elements are clear" do
+  it "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
+  it "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
+  it "should read and write correctly" do
     io = StringIO.new
     @data[1] = 8
     @data.write(io)
@@ -97,25 +150,71 @@ context "An Array with several elements" do
     @data.read(io)
     @data[1].should eql(8)
   end
+
+  it "should append an element" do
+    @data.append(99)
+    @data.length.should eql(6)
+    @data.last.should eql(99)
+  end
 end
 
-context "An Array containing structs" do
-  setup do
+describe "An Array containing structs" do
+  before(:each) 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
+  it "should access elements, not values" do
     @data[3].a.should eql(3)
   end
 
-  specify "should not be able to modify elements" do
+  it "should not be able to modify elements" do
     lambda { @data[1] = 3 }.should raise_error(NoMethodError)
   end
 
-  specify "should interate over each element" do
+  it "should interate over each element" do
     @data.collect { |s| s.a }.should eql([0, 1, 2, 3, 4])
   end
+
+  it "should be able to append elements" do
+    obj = @data.append
+    obj.a = 3
+    obj.b = 5
+
+    @data.last.a.should eql(3)
+    @data.last.b.should eql(5)
+  end
+end
+
+describe "An Array with :read_until containing +element+" do
+  before(:each) do
+    read_until = lambda { element == 5 }
+    @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 eql(3)
+  end
+
+  it "should read until the sentinel is reached" do
+    io = StringIO.new("\x01\x02\x03\x04\x05\x06\x07")
+    @data.read(io)
+    @data.length.should eql(5)
+  end
+end
+
+describe "An Array with :read_until containing +array+ and +index+" do
+  before(:each) do
+    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)
+    @data.length.should eql(7)
+  end
 end