bindata 0.9.2 → 0.9.3

data/lib/bindata/lazy.rb

@@ -1,110 +1,98 @@
 module BinData
-  # The enviroment in which a lazily evaluated lamba is called.  These lambdas
-  # are those that are passed to data objects as parameters.  Each lambda
-  # has access to the following:
+  # A LazyEvaluator is bound to a data object.  The evaluator will evaluate
+  # lambdas in the context of this data object.  These lambdas
+  # are those that are passed to data objects as parameters, e.g.:
   #
-  # parent:: the environment of the parent data object
-  # 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).
+  #    BinData::String.new(:value => lambda { %w{a test message}.join(" ") })
   #
-  # 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
+  # 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.
+  #
+  # This resolution process makes the lambda easier to read as we just write
   # <tt>field</tt> instead of <tt>obj.field</tt>.
-  class LazyEvalEnv
+  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)
+      end
+    end
+
     # An empty hash shared by all instances
     @@empty_hash = Hash.new.freeze
 
-    @@variables_cache = {}
-
-    # Creates a new environment.  +parent+ is the environment of the
-    # parent data object.
-    def initialize(parent = nil)
-      @parent = parent
-      @variables = @@empty_hash
+    # Creates a new evaluator.  All lazy evaluation is performed in the
+    # context of +obj+.
+    def initialize(obj)
+      @obj = obj
       @overrides = @@empty_hash
-      @params    = @@empty_hash
     end
-    attr_reader :parent, :params
-    attr_accessor :data_object
 
-    # only accessible by another LazyEvalEnv
-    protected :data_object
-
-    # Set the parameters for this environment.
-    def params=(p)
-      @params = (p.nil? or p.empty?) ? @@empty_hash : p
-    end
-
-    # 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)
-      sym = sym.to_sym
-      if @variables.equal?(@@empty_hash)
-        # optimise the case where only 1 variable is added as this
-        # is the most common occurance (BinData::Arrays adding index)
-        key = [sym, value]
-        @variables = @@variables_cache[key]
-        if @variables.nil?
-          # cache this variable and value so it can be shared with
-          # other LazyEvalEnvs to keep memory usage down
-          @variables = {sym => value}.freeze
-          @@variables_cache[key] = @variables
-        end
+    # Returns a LazyEvaluator for the parent of this data object.
+    def parent
+      if @obj.parent
+        LazyEvaluator.new(@obj.parent)
       else
-        if @variables.length == 1
-          key = @variables.keys[0]
-          @variables = {key => @variables[key]}
-        end
-        @variables[sym] = value
+        nil
       end
     end
 
-    # TODO: offset_of needs to be better thought out
-    def offset_of(sym)
-      @parent.data_object.offset_of(sym)
-    rescue
-      nil
-    end
-
-    # Returns the data_object for the parent environment.
-    def parent_data_object
-      @parent.nil? ? nil : @parent.data_object
-    end
-
-    # Evaluates +obj+ in the context of this environment.  Evaluation
+    # 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 +params+ like hash
-    def lazy_eval(obj, overrides = nil)
+    # +overrides+ is an optional +obj.parameters+ like hash.
+    def lazy_eval(val, overrides = nil)
+      result = val
       @overrides = overrides if overrides
-      if obj.is_a? Symbol
+      if val.is_a? Symbol
         # treat :foo as lambda { foo }
-        obj = __send__(obj)
-      elsif obj.respond_to? :arity
-        obj = instance_eval(&obj)
+        result = __send__(val)
+      elsif val.respond_to? :arity
+        result = instance_eval(&val)
       end
       @overrides = @@empty_hash
-      obj
+      result
     end
 
     def method_missing(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)
+      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
-        @parent.lazy_eval(obj)
+        LazyEvaluator.eval(val, @obj.parent)
       else
         super
       end
     end
+
+    #---------------
+    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
+      end
+      raise NoMethodError, "no index found"
+    end
+
   end
 end

data/lib/bindata/multi_value.rb

@@ -1,3 +1,4 @@
+require 'bindata/params'
 require 'bindata/struct'
 
 module BinData
@@ -44,11 +45,18 @@ module BinData
   class MultiValue < BinData::Struct
 
     class << self
+      extend Parameters
+
       # Register the names of all subclasses of this class.
       def inherited(subclass) #:nodoc:
         register(subclass.name, subclass)
       end
 
+      # Can this data object self reference itself?
+      def recursive?
+        true
+      end
+
       # Returns or sets the endianess of numerics used in this stucture.
       # Endianess is applied to the fields of this structure.
       # Valid values are :little and :big.
@@ -117,11 +125,8 @@ module BinData
         @fields.push([type, name, params])
       end
 
-      # Returns a sanitized +params+ that is of the form expected
-      # by #initialize.
-      def sanitize_parameters(sanitizer, params)
-        params = params.dup
-
+      # Ensures that +params+ is of the form expected by #initialize.
+      def sanitize_parameters!(sanitizer, params)
         endian = params[:endian] || self.endian
         fields = params[:fields] || self.fields
         hide   = params[:hide]   || self.hide
@@ -130,8 +135,37 @@ module BinData
         params[:fields] = fields
         params[:hide]   = hide
 
+        # add default parameters
+        default_parameters.each do |k,v|
+          params[k] = v unless params.has_key?(k)
+        end
+
+        # ensure mandatory parameters exist
+        mandatory_parameters.each do |prm|
+          if not params.has_key?(prm)
+            raise ArgumentError, "parameter ':#{prm}' must be specified " +
+                                 "in #{self}"
+          end
+        end
+
         super(sanitizer, params)
       end
+
+      # Sets the mandatory parameters used by this class.
+      def mandatory_parameters(*args) ; end
+
+      define_x_parameters(:mandatory, []) do |array, args|
+        args.each { |arg| array << arg.to_sym }
+        array.uniq!
+      end
+
+      # Sets the default parameters used by this class.
+      def default_parameters(params = {}); end
+
+      define_x_parameters(:default, {}) do |hash, args|
+        params = args.length > 0 ? args[0] : {}
+        hash.merge!(params)
+      end
     end
   end
 end

data/lib/bindata/params.rb

@@ -0,0 +1,36 @@
+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)
+        end
+
+        # add new parameters to the collection
+        if not args.empty?
+          block.call(instance_variable_get(iv), args)
+        end
+
+        # return collection
+        instance_variable_get(iv)
+      end
+
+      define_method(sym, body)
+      alias_method(full_name_singular.to_sym, sym)
+    end
+  end
+end

data/lib/bindata/registry.rb

@@ -23,15 +23,15 @@ module BinData
     # Returns the converted name
     def register(name, klass)
       # convert camelCase name to underscore style
-      name = underscore_name(name)
+      key = underscore_name(name)
 
       # warn if replacing an existing class
-      if $VERBOSE and (existing = @registry[name])
+      if $VERBOSE and (existing = @registry[key])
         warn "warning: replacing registered class #{existing} with #{klass}"
       end
 
-      @registry[name] = klass
-      name.dup
+      @registry[key] = klass
+      key.dup
     end
 
     # Returns the class matching a previously registered +name+.

data/lib/bindata/sanitize.rb

@@ -1,14 +1,56 @@
 require 'forwardable'
 
 module BinData
+
+  # A BinData object accepts arbitrary parameters.  This class only contains
+  # parameters that have been sanitized, and categorizes them according to
+  # whether they are BinData::Base.internal_parameters or are extra.
+  class SanitizedParameters
+    extend Forwardable
+
+    # Sanitize the given parameters.
+    def initialize(klass, params)
+      @hash = params
+      @internal_parameters = {}
+      @extra_parameters = {}
+
+      # partition parameters into known and extra parameters
+      @hash.each do |k,v|
+        k = k.to_sym
+        if v.nil?
+          raise ArgumentError, "parameter :#{k} has nil value in #{klass}"
+        end
+
+        if klass.internal_parameters.include?(k)
+          @internal_parameters[k] = v
+        else
+          @extra_parameters[k] = v
+        end
+      end
+    end
+
+    attr_reader :internal_parameters, :extra_parameters
+
+    def_delegators :@hash, :[], :has_key?, :include?, :keys
+  end
+
+  # The Sanitizer sanitizes the parameters that are passed when creating a
+  # BinData object.  Sanitizing consists of checking for mandatory, optional
+  # and default parameters and ensuring the values of known parameters are
+  # valid.
   class Sanitizer
+
     class << self
+
       # Sanitize +params+ for +obj+.
       # Returns sanitized parameters.
-      def sanitize(obj, params)
-        sanitizer = self.new
-        klass, new_params = sanitizer.sanitize(obj.class, params)
-        new_params
+      def sanitize(klass, params)
+        if SanitizedParameters === params
+          params
+        else
+          sanitizer = self.new
+          sanitizer.sanitize_params(klass, params)
+        end
       end
 
       # Returns true if +type+ is registered.
@@ -52,70 +94,44 @@ module BinData
       end
     end
 
-    # Sanitizes +params+ for +type+.
-    # Returns [klass, sanitized_params]
-    def sanitize(type, params)
-      if Class === type
-        klass = type
-      else
-        klass = self.class.lookup(type, @endian)
-        raise TypeError, "unknown type '#{type}'" if klass.nil?
-      end
+    # Converts +type+ into the appropriate class.
+    def lookup_klass(type)
+      klass = self.class.lookup(type, @endian)
+      raise TypeError, "unknown type '#{type}'" if klass.nil?
+      klass
+    end
+
+    # Sanitizes +params+ for +klass+.
+    # Returns +sanitized_params+.
+    def sanitize_params(klass, params)
+      new_params = params.nil? ? {} : params.dup
 
-      params ||= {}
-      if @seen.include?(klass)
+      if klass.recursive? and @seen.include?(klass)
         # This klass is defined recursively.  Remember the current endian
         # and delay sanitizing the parameters until later.
-        if @endian != nil and klass.accepted_parameters.include?(:endian) and
-            not params.has_key?(:endian)
-          params = params.dup
-          params[:endian] = @endian
-        end
+        new_params[:endian] = @endian if can_store_endian?(klass, new_params)
+        ret_val = new_params
       else
-        # subclasses of MultiValue may be defined recursively
-        # TODO: define a class field instead
-        possibly_recursive = (BinData.const_defined?(:MultiValue) and 
-                              klass.ancestors.include?(BinData.const_get(:MultiValue)))
-        @seen.push klass if possibly_recursive
-
-        new_params = klass.sanitize_parameters(self, params)
-        params = SanitizedParameters.new(klass, new_params)
-      end
+        @seen.push(klass)
 
-      [klass, params]
-    end
-  end
+        # Sanitize new_params.  This may recursively call this method again.
+        klass.sanitize_parameters!(self, new_params)
+        ret_val = SanitizedParameters.new(klass, new_params)
 
-  # A BinData object accepts arbitrary parameters.  This class ensures that
-  # the parameters have been sanitized, and categorizes them according to
-  # whether they are BinData::Base.accepted_parameters or are extra.
-  class SanitizedParameters
-    extend Forwardable
-
-    # Sanitize the given parameters.
-    def initialize(klass, params)
-      @hash = params
-      @accepted_parameters = {}
-      @extra_parameters = {}
-
-      # partition parameters into known and extra parameters
-      @hash.each do |k,v|
-        k = k.to_sym
-        if v.nil?
-          raise ArgumentError, "parameter :#{k} has nil value in #{klass}"
-        end
-
-        if klass.accepted_parameters.include?(k)
-          @accepted_parameters[k] = v
-        else
-          @extra_parameters[k] = v
-        end
+        @seen.pop
       end
+
+      ret_val
     end
 
-    attr_reader :accepted_parameters, :extra_parameters
+    #---------------
+    private
 
-    def_delegators :@hash, :[], :has_key?, :include?, :keys
+    # Can we store the current endian for later?
+    def can_store_endian?(klass, params)
+      (@endian != nil and klass.internal_parameters.include?(:endian) and
+       not params.has_key?(:endian))
+    end
   end
 end