bindata 0.9.3 → 0.10.0

data/lib/bindata/io.rb

@@ -53,7 +53,6 @@ module BinData
       if positioning_supported?
         @raw_io.pos - @initial_pos
       else
-        # stream does not support positioning
         0
       end
     end
@@ -69,7 +68,7 @@ module BinData
     #
     # If the data read is too short an IOError is raised.
     def readbytes(n)
-      raise "Internal state error nbits = #{@rnbits}" if @rnbits > 8
+      raise "Internal state error nbits = #{@rnbits}" if @rnbits >= 8
       @rnbits = 0
       @rval   = 0
 
@@ -79,9 +78,18 @@ module BinData
       str
     end
 
+    # Reads all remaining bytes from the stream.
+    def read_all_bytes
+      raise "Internal state error nbits = #{@rnbits}" if @rnbits >= 8
+      @rnbits = 0
+      @rval   = 0
+
+      @raw_io.read
+    end
+
     # Reads exactly +nbits+ bits from the stream. +endian+ specifies whether
     # the bits are stored in +:big+ or +:little+ endian format.
-    def readbits(nbits, endian = :big)
+    def readbits(nbits, endian)
       if @rendian != endian
         # don't mix bits of differing endian
         @rnbits  = 0
@@ -90,9 +98,9 @@ module BinData
       end
 
       if endian == :big
-        read_be_bits(nbits)
+        read_big_endian_bits(nbits)
       else
-        read_le_bits(nbits)
+        read_little_endian_bits(nbits)
       end
     end
 
@@ -104,32 +112,29 @@ module BinData
 
     # Writes +nbits+ bits from +val+ to the stream. +endian+ specifies whether
     # the bits are to be stored in +:big+ or +:little+ endian format.
-    def writebits(val, nbits, endian = :big)
-      # clamp val to range
-      val = val & ((1 << nbits) - 1)
-
+    def writebits(val, nbits, endian)
       if @wendian != endian
         # don't mix bits of differing endian
-        flushbits if @wnbits > 0
+        flushbits
 
         @wendian = endian
       end
 
+      clamped_val = val & mask(nbits)
+
       if endian == :big
-        write_be_bits(val, nbits)
+        write_big_endian_bits(clamped_val, nbits)
       else
-        write_le_bits(val, nbits)
+        write_little_endian_bits(clamped_val, nbits)
       end
     end
 
     # To be called after all +writebits+ have been applied.
     def flushbits
-      if @wnbits > 8
-        raise "Internal state error nbits = #{@wnbits}" if @wnbits > 8
-      elsif @wnbits > 0
+      raise "Internal state error nbits = #{@wnbits}" if @wnbits >= 8
+
+      if @wnbits > 0
         writebits(0, 8 - @wnbits, @wendian)
-      else
-        # do nothing
       end
     end
     alias_method :flush, :flushbits
@@ -137,7 +142,6 @@ module BinData
     #---------------
     private
 
-    # Checks if positioning is supported by the underlying io stream.
     def positioning_supported?
       unless defined? @positioning_supported
         @positioning_supported = begin
@@ -150,52 +154,55 @@ module BinData
       @positioning_supported
     end
 
-    # Reads exactly +nbits+ big endian bits from the stream.
-    def read_be_bits(nbits)
-      # ensure enough bits have accumulated
-      while nbits > @rnbits
-        byte = @raw_io.read(1)
-        raise EOFError, "End of file reached" if byte.nil?
-        byte = byte.unpack('C').at(0) & 0xff
-
-        @rval = (@rval << 8) | byte
-        @rnbits += 8
+    def read_big_endian_bits(nbits)
+      while @rnbits < nbits
+        accumulate_big_endian_bits
       end
 
-      val     = (@rval >> (@rnbits - nbits)) & ((1 << nbits) - 1)
+      val     = (@rval >> (@rnbits - nbits)) & mask(nbits)
       @rnbits -= nbits
-      @rval   &= ((1 << @rnbits) - 1)
+      @rval   &= mask(@rnbits)
 
       val
     end
 
-    # Reads exactly +nbits+ little endian bits from the stream.
-    def read_le_bits(nbits)
-      # ensure enough bits have accumulated
-      while nbits > @rnbits
-        byte = @raw_io.read(1)
-        raise EOFError, "End of file reached" if byte.nil?
-        byte = byte.unpack('C').at(0) & 0xff
+    def accumulate_big_endian_bits
+      byte = @raw_io.read(1)
+      raise EOFError, "End of file reached" if byte.nil?
+      byte = byte.unpack('C').at(0) & 0xff
+
+      @rval = (@rval << 8) | byte
+      @rnbits += 8
+    end
 
-        @rval = @rval | (byte << @rnbits)
-        @rnbits += 8
+    def read_little_endian_bits(nbits)
+      while @rnbits < nbits
+        accumulate_little_endian_bits
       end
 
-      val     = @rval & ((1 << nbits) - 1)
+      val     = @rval & mask(nbits)
       @rnbits -= nbits
       @rval   >>= nbits
 
       val
     end
 
-    # Writes +nbits+ bits from +val+ to the stream in big endian format.
-    def write_be_bits(val, nbits)
+    def accumulate_little_endian_bits
+      byte = @raw_io.read(1)
+      raise EOFError, "End of file reached" if byte.nil?
+      byte = byte.unpack('C').at(0) & 0xff
+
+      @rval = @rval | (byte << @rnbits)
+      @rnbits += 8
+    end
+
+    def write_big_endian_bits(val, nbits)
       while nbits > 0
         bits_req = 8 - @wnbits
         if nbits >= bits_req
-          msb_bits = (val >> (nbits - bits_req)) & ((1 << bits_req) - 1)
+          msb_bits = (val >> (nbits - bits_req)) & mask(bits_req)
           nbits -= bits_req
-          val &= (1 << nbits) - 1
+          val &= mask(nbits)
 
           @wval   = (@wval << bits_req) | msb_bits
           @raw_io.write(@wval.chr)
@@ -210,26 +217,29 @@ module BinData
       end
     end
 
-    # Writes +nbits+ bits from +val+ to the stream in little endian format.
-    def write_le_bits(val, nbits)
+    def write_little_endian_bits(val, nbits)
       while nbits > 0
         bits_req = 8 - @wnbits
         if nbits >= bits_req
-          lsb_bits = val & ((1 << bits_req) - 1)
+          lsb_bits = val & mask(bits_req)
           nbits -= bits_req
           val >>= bits_req
 
-          @wval   |= (lsb_bits << @wnbits)
+          @wval   = @wval | (lsb_bits << @wnbits)
           @raw_io.write(@wval.chr)
 
           @wval   = 0
           @wnbits = 0
         else
-          @wval   |= (val << @wnbits)
+          @wval   = @wval | (val << @wnbits)
           @wnbits += nbits
           nbits = 0
         end
       end
     end
+
+    def mask(nbits)
+      (1 << nbits) - 1
+    end
   end
 end

data/lib/bindata/lazy.rb

@@ -5,31 +5,56 @@ module BinData
   #
   #    BinData::String.new(:value => lambda { %w{a test message}.join(" ") })
   #
-  # When evaluating lambdas, unknown methods are resolved in the context of
-  # the parent of the bound data object, first as keys in #parameters, and
-  # secondly as methods in this parent.  This resolution propagates up the
-  # chain of parent data objects.
+  # As a shortcut, :foo is the equivalent of lambda { foo }.
+  #
+  # When evaluating lambdas, unknown methods are resolved in the context of the
+  # parent of the bound data object.  Resolution is attempted firstly as keys
+  # in #parameters, and secondly as methods in this parent.  This
+  # resolution propagates up the chain of parent data objects.
+  #
+  # An evaluation will recurse until it returns a result that is not
+  # a lambda or a symbol.
   #
   # This resolution process makes the lambda easier to read as we just write
   # <tt>field</tt> instead of <tt>obj.field</tt>.
   class LazyEvaluator
+
     class << self
       # Lazily evaluates +val+ in the context of +obj+, with possibility of
       # +overrides+.
-      def eval(val, obj, overrides = nil)
-        env = self.new(obj)
-        env.lazy_eval(val, overrides)
+      def eval(obj, val, overrides = {})
+        if can_eval?(val)
+          env = self.new(obj, overrides)
+          env.lazy_eval(val)
+        else
+          val
+        end
       end
-    end
 
-    # An empty hash shared by all instances
-    @@empty_hash = Hash.new.freeze
+      #-------------
+      private
+
+      def can_eval?(val)
+        val.is_a?(Symbol) or val.respond_to?(:arity)
+      end
+    end
 
     # Creates a new evaluator.  All lazy evaluation is performed in the
     # context of +obj+.
-    def initialize(obj)
+    # +overrides+ is an optional +obj.parameters+ like hash.
+    def initialize(obj, overrides = {})
       @obj = obj
-      @overrides = @@empty_hash
+      @overrides = overrides
+    end
+
+    def lazy_eval(val)
+      if val.is_a? Symbol
+        __send__(val)
+      elsif val.respond_to? :arity
+        instance_eval(&val)
+      else
+        val
+      end
     end
 
     # Returns a LazyEvaluator for the parent of this data object.
@@ -41,35 +66,30 @@ module BinData
       end
     end
 
-    # Evaluates +val+ in the context of this data object.  Evaluation
-    # recurses until it yields a value that is not a symbol or lambda.
-    # +overrides+ is an optional +obj.parameters+ like hash.
-    def lazy_eval(val, overrides = nil)
-      result = val
-      @overrides = overrides if overrides
-      if val.is_a? Symbol
-        # treat :foo as lambda { foo }
-        result = __send__(val)
-      elsif val.respond_to? :arity
-        result = instance_eval(&val)
+    # Returns the index of this data object inside it's nearest container
+    # array.
+    def index
+      return @overrides[:index] if @overrides.has_key?(:index)
+
+      bindata_array_class = BinData.const_defined?("Array") ? 
+                              BinData.const_get("Array") : nil
+      child = @obj
+      parent = @obj.parent
+      while parent
+        if parent.class == bindata_array_class
+          return parent.find_index_of(child)
+        end
+        child = parent
+        parent = parent.parent
       end
-      @overrides = @@empty_hash
-      result
+      raise NoMethodError, "no index found"
     end
 
     def method_missing(symbol, *args)
-      if @overrides.include?(symbol)
-        @overrides[symbol]
-      elsif symbol == :index
-        array_index
-      elsif @obj.parent
-        val = symbol
-        if @obj.parent.parameters and @obj.parent.parameters.has_key?(symbol)
-          val = @obj.parent.parameters[symbol]
-        elsif @obj.parent and @obj.parent.respond_to?(symbol)
-          val = @obj.parent.__send__(symbol, *args)
-        end
-        LazyEvaluator.eval(val, @obj.parent)
+      return @overrides[symbol] if @overrides.has_key?(symbol)
+
+      if @obj.parent
+        eval_symbol_in_parent_context(symbol, args)
       else
         super
       end
@@ -78,21 +98,31 @@ module BinData
     #---------------
     private
 
-    # Returns the index in the closest ancestor array of this data object.
-    def array_index
-      bindata_array_klass = BinData.const_defined?("Array") ? 
-                              BinData.const_get("Array") : nil
-      child = @obj
-      parent = @obj.parent
-      while parent
-        if parent.class == bindata_array_klass
-          return parent.index(child)
-        end
-        child = parent
-        parent = parent.parent
+    def eval_symbol_in_parent_context(symbol, args)
+      result = resolve_symbol_in_parent_context(symbol, args)
+      recursively_eval(result, args)
+    end
+
+    def resolve_symbol_in_parent_context(symbol, args)
+      obj_parent = @obj.parent
+
+      if obj_parent.has_parameter?(symbol)
+        result = obj_parent.get_parameter(symbol)
+      elsif obj_parent.respond_to?(symbol)
+        result = obj_parent.__send__(symbol, *args)
+      else
+        result = symbol
       end
-      raise NoMethodError, "no index found"
     end
 
+    def recursively_eval(val, args)
+      if val.is_a?(Symbol)
+        parent.__send__(val, *args)
+      elsif val.respond_to?(:arity)
+        parent.instance_eval(&val)
+      else
+        val
+      end
+    end
   end
 end

data/lib/bindata/params.rb

@@ -1,36 +1,144 @@
 module BinData
-  module Parameters
-
-    # Definition method for creating a method that maintains a collection
-    # of parameters.  This is used for creating collections of mandatory,
-    # optional, default etc parameters.  The parameters for a class will
-    # include the parameters of its ancestors.
-    def define_x_parameters(name, empty, &block) #:nodoc:
-      full_name_singular = "#{name.to_s}_parameter"
-      full_name_plural = "#{name.to_s}_parameters"
-
-      sym = full_name_plural.to_sym
-      iv = "@#{full_name_plural}".to_sym
-
-      body = Proc.new do |*args|
-        # initialize collection to duplicate ancestor's collection
-        unless instance_variable_defined?(iv)
-          ancestor = ancestors[1..-1].find { |a| a.respond_to?(sym) }
-          val = ancestor.nil? ? empty : ancestor.send(sym).dup
-          instance_variable_set(iv, val)
+  # BinData objects accept parameters when initializing.  AcceptedParameters
+  # allow a BinData class to declaratively identify accepted parameters as
+  # mandatory, optional, default or mutually exclusive.
+  class AcceptedParameters
+    class << self
+      def define_all_accessors(obj_class, param_name)
+        all_accessors = [:mandatory, :optional, :default, :mutually_exclusive]
+        all_accessors.each do |accessor|
+          define_accessor(obj_class, param_name, accessor)
         end
+      end
+
+      def define_accessors(obj_class, param_name, *accessors)
+        accessors.each do |accessor|
+          define_accessor(obj_class, param_name, accessor)
+        end
+      end
+
+      def get(obj_class, param_name)
+        obj_class.__send__(internal_storage_method_name(param_name))
+      end
+
+      #-------------
+      private
+
+      def define_accessor(obj_class, param_name, accessor)
+        singular_name = accessor_method_name(accessor)
+        plural_name = singular_name + "s"
+        internal_storage_method = internal_storage_method_name(param_name)
+
+        ensure_parameter_storage_exists(obj_class, internal_storage_method)
+
+        obj_class.class_eval <<-END
+          def #{singular_name}(*args)
+            #{internal_storage_method}.#{accessor}(*args)
+          end
+          alias_method :#{plural_name}, :#{singular_name}
+        END
+      end
+
+      def accessor_method_name(accessor)
+        "#{accessor}_parameter"
+      end
+
+      def internal_storage_method_name(param_name)
+        "_bindata_accepted_parameters_#{param_name}"
+      end
+
+      def ensure_parameter_storage_exists(obj_class, method_name)
+        return if obj_class.instance_methods.include?(method_name)
+
+        iv = "@#{method_name}"
+        obj_class.class_eval <<-END
+          def #{method_name}
+            unless defined? #{iv}
+              ancestor = ancestors[1..-1].find { |a| a.instance_variable_defined?(:#{iv}) }
+              ancestor_params = ancestor.nil? ? nil : ancestor.instance_variable_get(:#{iv})
+              #{iv} = AcceptedParameters.new(ancestor_params)
+            end
+            #{iv}
+          end
+        END
+      end
+    end
+
+    def initialize(ancestor_params = nil)
+      @mandatory = ancestor_params ? ancestor_params.mandatory : []
+      @optional = ancestor_params ? ancestor_params.optional : []
+      @default = ancestor_params ? ancestor_params.default : Hash.new
+      @mutually_exclusive = ancestor_params ? ancestor_params.mutually_exclusive : []
+    end
+
+    def mandatory(*args)
+      if not args.empty?
+        @mandatory.concat(args.collect { |a| a.to_sym })
+        @mandatory.uniq!
+      end
+      @mandatory.dup
+    end
+
+    def optional(*args)
+      if not args.empty?
+        @optional.concat(args.collect { |a| a.to_sym })
+        @optional.uniq!
+      end
+      @optional.dup
+    end
 
-        # add new parameters to the collection
-        if not args.empty?
-          block.call(instance_variable_get(iv), args)
+    def default(args = {})
+      if not args.empty?
+        args.each_pair do |k,v|
+          @default[k.to_sym] = v
         end
+      end
+      @default.dup
+    end
+
+    def mutually_exclusive(*args)
+      arg1, arg2 = args
+      if arg1 != nil && arg2 != nil
+        @mutually_exclusive.push([arg1.to_sym, arg2.to_sym])
+        @mutually_exclusive.uniq!
+      end
+      @mutually_exclusive.dup
+    end
+
+    def all
+      (@mandatory + @optional + @default.keys).uniq
+    end
+
+    def sanitize_parameters!(sanitizer, params)
+      merge_default_parameters!(params)
+      ensure_mandatory_parameters_exist(params)
+      ensure_mutual_exclusion_of_parameters(params)
+    end
 
-        # return collection
-        instance_variable_get(iv)
+    #---------------
+    private
+
+    def merge_default_parameters!(params)
+      @default.each do |k,v|
+        params[k] = v unless params.has_key?(k)
       end
+    end
 
-      define_method(sym, body)
-      alias_method(full_name_singular.to_sym, sym)
+    def ensure_mandatory_parameters_exist(params)
+      @mandatory.each do |prm|
+        unless params.has_key?(prm)
+          raise ArgumentError, "parameter ':#{prm}' must be specified"
+        end
+      end
+    end
+
+    def ensure_mutual_exclusion_of_parameters(params)
+      @mutually_exclusive.each do |param1, param2|
+        if params.has_key?(param1) and params.has_key?(param2)
+          raise ArgumentError, "params ':#{param1}' and ':#{param2}' " +
+                               "are mutually exclusive"
+        end
+      end
     end
   end
 end