bindata 0.9.3 → 0.10.0

data/lib/bindata/struct.rb

@@ -6,7 +6,7 @@ module BinData
   #
   #    require 'bindata'
   #
-  #    class Tuple < BinData::MultiValue
+  #    class Tuple < BinData::Record
   #      int8  :x
   #      int8  :y
   #      int8  :z
@@ -37,23 +37,34 @@ module BinData
   # <tt>:endian</tt>::   Either :little or :big.  This specifies the default
   #                      endian of any numerics in this struct, or in any
   #                      nested data objects.
+  #
+  # == Field Parameters
+  #
+  # Fields may have have extra parameters as listed below:
+  #
+  # [<tt>:onlyif</tt>]   Used to indicate a data object is optional.
+  #                      if +false+, this object will not be included in any
+  #                      calls to #read, #write, #num_bytes or #snapshot.
   class Struct < BinData::Base
 
+    register(self.name, self)
+
     # These reserved words may not be used as field names
     RESERVED = (::Hash.instance_methods + 
                 %w{alias and begin break case class def defined do else elsif
                    end ensure false for if in module next nil not or redo
                    rescue retry return self super then true undef unless until
                    when while yield} +
-                %w{array element index offset value} ).uniq
-
-    # Register this class
-    register(self.name, self)
+                %w{array element index value} ).uniq
 
     # A hash that can be accessed via attributes.
     class Snapshot < Hash #:nodoc:
+      def respond_to?(symbol, include_private = false)
+        has_key?(symbol.to_s) || super(symbol, include_private)
+      end
+
       def method_missing(symbol, *args)
-        self[symbol.id2name] || super
+        self[symbol.to_s] || super
       end
     end
 
@@ -61,91 +72,97 @@ module BinData
       #### DEPRECATION HACK to warn about inheriting from BinData::Struct
       #
       def inherited(subclass) #:nodoc:
-        if subclass != MultiValue
+        if subclass != Record
           # warn about deprecated method - remove before releasing 1.0
-          fail "error: inheriting from BinData::Struct has been deprecated. Inherit from BinData::MultiValue instead."
+          fail "error: inheriting from BinData::Struct has been deprecated. Inherit from BinData::Record instead."
         end
       end
       #
       #### DEPRECATION HACK to allow inheriting from BinData::Struct
 
 
-      # Ensures that +params+ is of the form expected by #initialize.
       def sanitize_parameters!(sanitizer, params)
-        # possibly override endian
-        endian = params[:endian]
-        if endian != nil
+        ensure_valid_endian(params)
+
+        if params.has_key?(:fields)
+          sfields = sanitized_fields(sanitizer, params[:fields], params[:endian])
+          field_names = sanitized_field_names(sfields)
+          hfield_names = hidden_field_names(params[:hide])
+
+          ensure_field_names_are_valid(field_names)
+
+          params[:fields] = sfields
+          params[:hide]   = (hfield_names & field_names)
+        end
+
+        super(sanitizer, params)
+      end
+
+      #-------------
+      private
+
+      def ensure_valid_endian(params)
+        if params.has_key?(:endian)
+          endian = params[:endian]
           unless [:little, :big].include?(endian)
             raise ArgumentError, "unknown value for endian '#{endian}'"
           end
-
-          params[:endian] = endian
         end
+      end
 
-        if params.has_key?(:fields)
-          sanitizer.with_endian(endian) do
-            # ensure names of fields are strings and that params is sanitized
-            all_fields = params[:fields].collect do |ftype, fname, fparams|
-              fname = fname.to_s
-              klass = sanitizer.lookup_klass(ftype)
-              sanitized_fparams = sanitizer.sanitize_params(klass, fparams)
-              [klass, fname, sanitized_fparams]
-            end
-            params[:fields] = all_fields
+      def sanitized_fields(sanitizer, fields, endian)
+        result = nil
+        sanitizer.with_endian(endian) do
+          result = fields.collect do |ftype, fname, fparams|
+            sanitized_field(sanitizer, ftype, fname, fparams)
           end
+        end
+        result
+      end
 
-          # now params are sanitized, check that parameter names are okay
-          field_names = []
-          instance_methods = self.instance_methods
-          reserved_names = RESERVED
-
-          params[:fields].each do |fklass, fname, fparams|
+      def sanitized_field(sanitizer, ftype, fname, fparams)
+        fname = fname.to_s
+        fclass = sanitizer.lookup_class(ftype)
+        sanitized_fparams = sanitizer.sanitized_params(fclass, fparams)
+        [fclass, fname, sanitized_fparams]
+      end
 
-            # check that name doesn't shadow an existing method
-            if instance_methods.include?(fname)
-              raise NameError.new("Rename field '#{fname}' in #{self}, " +
-                                  "as it shadows an existing method.", fname)
-            end
+      def sanitized_field_names(sanitized_fields)
+        sanitized_fields.collect { |fclass, fname, fparams| fname }
+      end
 
-            # check that name isn't reserved
-            if reserved_names.include?(fname)
-              raise NameError.new("Rename field '#{fname}' in #{self}, " +
-                                  "as it is a reserved name.", fname)
-            end
+      def hidden_field_names(hidden)
+        (hidden || []).collect { |h| h.to_s }
+      end
 
-            # check for multiple definitions
-            if field_names.include?(fname)
-              raise NameError.new("field '#{fname}' in #{self}, " +
-                                  "is defined multiple times.", fname)
-            end
+      def ensure_field_names_are_valid(field_names)
+        instance_methods = self.instance_methods
+        reserved_names = RESERVED
 
-            field_names << fname
+        field_names.each do |name|
+          if instance_methods.include?(name)
+            raise NameError.new("Rename field '#{name}' in #{self}, " +
+                                "as it shadows an existing method.", name)
           end
-
-          # collect all hidden names that correspond to a field name
-          hide = []
-          if params.has_key?(:hide)
-            hidden = (params[:hide] || []).collect { |h| h.to_s }
-            all_field_names = params[:fields].collect { |k,n,p| n }
-            hide = hidden & all_field_names
+          if reserved_names.include?(name)
+            raise NameError.new("Rename field '#{name}' in #{self}, " +
+                                "as it is a reserved name.", name)
+          end
+          if field_names.count(name) != 1
+            raise NameError.new("field '#{name}' in #{self}, " +
+                                "is defined multiple times.", name)
           end
-          params[:hide] = hide
         end
-
-        super(sanitizer, params)
       end
     end
 
-    # These are the parameters used by this class.
-    bindata_mandatory_parameter :fields
-    bindata_optional_parameters :endian, :hide
+    mandatory_parameter :fields
+    optional_parameters :endian, :hide
 
-    # Creates a new Struct.
     def initialize(params = {}, parent = nil)
       super(params, parent)
 
-      # extract field names but don't instantiate the fields
-      @field_names = no_eval_param(:fields).collect { |k, n, p| n }
+      @field_names = get_parameter(:fields).collect { |c, n, p| n }
       @field_objs  = []
     end
 
@@ -155,7 +172,8 @@ module BinData
       if name.nil?
         @field_objs.each { |f| f.clear unless f.nil? }
       else
-        obj = find_obj_for_name(name.to_s)
+        warn "'obj.clear(name)' is deprecated.  Replacing with 'obj.name.clear'"
+        obj = find_obj_for_name(name)
         obj.clear unless obj.nil?
       end
     end
@@ -164,149 +182,176 @@ module BinData
     # is given, returns whether all fields are clear.
     def clear?(name = nil)
       if name.nil?
-        @field_objs.each do |f|
-          return false unless f.nil? or f.clear?
-        end
-        true
+        @field_objs.inject(true) { |all_clear, f| all_clear and (f.nil? or f.clear?) }
       else
-        obj = find_obj_for_name(name.to_s)
+        warn "'obj.clear?(name)' is deprecated.  Replacing with 'obj.name.clear?'"
+        obj = find_obj_for_name(name)
         obj.nil? ? true : obj.clear?
       end
     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?
-      return false
-    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)
-      # collect field names
-      names = []
-      hidden = no_eval_param(:hide)
-      @field_names.each do |name|
-        if include_hidden or not hidden.include?(name)
-          names << name
-        end
+      if include_hidden
+        @field_names.dup
+      else
+        hidden = get_parameter(:hide)
+        @field_names - hidden
       end
-      names
     end
 
-    # To be called after calling #read.
-    def done_read
-      @field_objs.each { |f| f.done_read unless f.nil? }
+    def respond_to?(symbol, include_private = false)
+      super(symbol, include_private) ||
+        field_names(true).include?(symbol.to_s.chomp("="))
     end
 
-    def offset_of(field)
-      idx = @field_names.index(field.to_s)
-      if idx
-        instantiate_all
-
-        offset = 0
-        (0...idx).each do |i|
-          this_offset = @field_objs[i].do_num_bytes
-          if ::Float === offset and ::Integer === this_offset
-            offset = offset.ceil
-          end
-          offset += this_offset
-        end
-        offset
+    def method_missing(symbol, *args, &block)
+      obj = find_obj_for_name(symbol)
+      if obj
+        invoke_field(obj, symbol, args)
       else
-        nil
+        super
       end
     end
 
-    # Override to include field names
-    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("="))
+    def debug_name_of(child)
+      field_name = @field_names[find_index_of(child)]
+      "#{debug_name}.#{field_name}"
     end
 
-    def method_missing(symbol, *args, &block)
-      name = symbol.id2name
+    def offset_of(child)
+      if child.class == ::String
+        fail "error: 'offset_of(\"fieldname\")' is deprecated.  Use 'fieldname.offset' instead"
+      end
+
+      instantiate_all_objs
+      sum = sum_num_bytes_below_index(find_index_of(child))
+      child_offset = (::Integer === child.do_num_bytes) ? sum.ceil : sum.floor
+
+      offset + child_offset
+    end
 
+    #---------------
+    private
+
+    def invoke_field(obj, symbol, args)
+      name = symbol.to_s
       is_writer = (name[-1, 1] == "=")
-      name.chomp!("=")
-
-      # find the object that is responsible for name
-      if (obj = find_obj_for_name(name))
-        # pass on the request
-        if obj.single_value? and is_writer
-          obj.value = *args
-        elsif obj.single_value?
-          obj.value
-        else
-          obj
-        end
+
+      if is_writer
+        obj.assign(*args)
       else
-        super
+        obj
       end
     end
 
-    #---------------
-    private
+    def find_index_of(obj)
+      @field_objs.find_index { |el| el.equal?(obj) }
+    end
 
-    # Returns the data object that stores values for +name+.
     def find_obj_for_name(name)
-      idx = @field_names.index(name)
-      if idx
-        instantiate_obj(idx)
-        @field_objs[idx].obj
+      field_name = name.to_s.chomp("=")
+      index = @field_names.find_index(field_name)
+      if index
+        instantiate_obj_at(index)
+        @field_objs[index]
       else
         nil
       end
     end
 
-    # Instantiates all fields.
-    def instantiate_all
-      @field_names.each_with_index { |name, i| instantiate_obj(i) }
+    def instantiate_all_objs
+      @field_names.each_index { |i| instantiate_obj_at(i) }
     end
 
-    # Instantiates the field object at position +idx+.
-    def instantiate_obj(idx)
-      if @field_objs[idx].nil?
-        fklass, fname, fparams = no_eval_param(:fields)[idx]
-        @field_objs[idx] = fklass.new(fparams, self)
+    def instantiate_obj_at(index)
+      if @field_objs[index].nil?
+        fclass, fname, fparams = get_parameter(:fields)[index]
+        @field_objs[index] = fclass.new(fparams, self)
       end
     end
 
-    # Reads the values for all fields in this object from +io+.
     def _do_read(io)
-      instantiate_all
-      @field_objs.each { |f| f.do_read(io) }
+      instantiate_all_objs
+      @field_objs.each { |f| f.do_read(io) if include_obj(f) }
+    end
+
+    def _done_read
+      @field_objs.each { |f| f.done_read if include_obj(f) }
     end
 
-    # Writes the values for all fields in this object to +io+.
     def _do_write(io)
-      instantiate_all
-      @field_objs.each { |f| f.do_write(io) }
+      instantiate_all_objs
+      @field_objs.each { |f| f.do_write(io) if include_obj(f) }
     end
 
-    # Returns the number of bytes it will take to write the field represented
-    # by +name+.  If +name+ is nil then returns the number of bytes required
-    # to write all fields.
     def _do_num_bytes(name)
       if name.nil?
-        instantiate_all
-        (@field_objs.inject(0) { |sum, f| sum + f.do_num_bytes }).ceil
+        instantiate_all_objs
+        sum_num_bytes_for_all_fields.ceil
       else
-        obj = find_obj_for_name(name.to_s)
+        warn "'obj.num_bytes(name)' is deprecated.  Replacing with 'obj.name.num_bytes'"
+        obj = find_obj_for_name(name)
         obj.nil? ? 0 : obj.do_num_bytes
       end
     end
 
-    # Returns a snapshot of this struct as a hash.
+    def _assign(val)
+      clear
+      assign_fields(as_snapshot(val))
+    end
+
+    def as_snapshot(val)
+      if val.class == Hash
+        snapshot = Snapshot.new
+        val.each_pair { |k,v| snapshot[k.to_s] = v unless v.nil? }
+        snapshot
+      elsif val.nil?
+        Snapshot.new
+      else
+        val
+      end
+    end
+
+    def assign_fields(snapshot)
+      field_names(true).each do |name|
+        obj = find_obj_for_name(name)
+        if obj and snapshot.respond_to?(name)
+          obj.assign(snapshot.__send__(name))
+        end
+      end
+    end
+
     def _snapshot
-      hash = Snapshot.new
+      snapshot = Snapshot.new
       field_names.each do |name|
-        ss = find_obj_for_name(name).snapshot
-        hash[name] = ss unless ss.nil?
+        obj = find_obj_for_name(name)
+        snapshot[name] = obj.snapshot if include_obj(obj)
+      end
+      snapshot
+    end
+
+    def sum_num_bytes_for_all_fields
+      sum_num_bytes_below_index(@field_objs.length)
+    end
+
+    def sum_num_bytes_below_index(index)
+      sum = 0
+      (0...index).each do |i|
+        obj = @field_objs[i]
+        if include_obj(obj)
+          nbytes = obj.do_num_bytes
+          sum = ((::Integer === nbytes) ? sum.ceil : sum) + nbytes
+        end
       end
-      hash
+
+      sum
+    end
+
+    def include_obj(obj)
+      not obj.has_parameter?(:onlyif) or obj.eval_parameter(:onlyif)
     end
   end
 end