bindata 0.10.0 → 0.11.0

data/lib/bindata/registry.rb

@@ -9,24 +9,20 @@ module BinData
     end
 
     def register(name, class_to_register)
-      formatted_name = underscore_name(name)
+      formatted_name = lookup_key(name)
       warn_if_name_is_already_registered(formatted_name, class_to_register)
 
       @registry[formatted_name] = class_to_register
     end
 
     def lookup(name, endian = nil)
-      key = underscore_name(name.to_s)
+      key = lookup_key(name, endian)
 
-      result = @registry[key]
-      if result.nil?
-        result = @registry[merge_key_and_endian(key, endian)]
-      end
-      result
+      @registry[key] || lookup_int(key)
     end
 
     def is_registered?(name, endian = nil)
-      lookup(name, endian) != nil
+      @registry.has_key?(lookup_key(name, endian))
     end
 
     # Convert camelCase +name+ to underscore style.
@@ -41,18 +37,41 @@ module BinData
     #---------------
     private
 
-    def merge_key_and_endian(key, endian)
-      result = key
+    def lookup_key(name, endian = nil)
+      name = underscore_name(name)
+
+      result = name
       if endian != nil
-        if /^u?int\d+$/ =~ key
-          result = key + ((endian == :little) ? "le" : "be")
-        elsif /^(float|double)$/ =~ key
-          result = key + ((endian == :little) ? "_le" : "_be")
+        if /^u?int\d+$/ =~ name
+          result = name + ((endian == :little) ? "le" : "be")
+        elsif /^(float|double)$/ =~ name
+          result = name + ((endian == :little) ? "_le" : "_be")
         end
       end
       result
     end
 
+    def lookup_int(key)
+      if /^(u?)int(\d+)(le|be)$/ =~ key
+        signed = $1 == "u" ? :unsigned : :signed
+        nbits  = $2.to_i
+        endian = $3 == "le" ? :little : :big
+        if nbits > 0 and (nbits % 8) == 0
+          if BinData.const_defined?(:Integer)
+            BinData::Integer.define_class(nbits, endian, signed)
+          end
+        end
+      elsif /^bit(\d+)(le)?$/ =~ key
+        nbits  = $1.to_i
+        endian = $2 == "le" ? :little : :big
+        if BinData.const_defined?(:BitField)
+          BinData::BitField.define_class(nbits, endian)
+        end
+      end
+
+      @registry[key]
+    end
+
     def warn_if_name_is_already_registered(name, class_to_register)
       if $VERBOSE and @registry.has_key?(name)
         prev_class = @registry[name]
@@ -64,11 +83,4 @@ module BinData
 
   # A singleton registry of all registered classes.
   RegisteredClasses = Registry.new
-
-  class Registry
-    def Registry.instance
-      warn "'Registry.instance' is deprecated.  Replacing with 'RegisteredClasses'"
-      RegisteredClasses
-    end
-  end
 end

data/lib/bindata/sanitize.rb

@@ -1,30 +1,112 @@
 require 'bindata/registry'
-require 'forwardable'
 
 module BinData
 
-  # A BinData object accepts arbitrary parameters.  This class only contains
-  # parameters that have been sanitized.
+  # A BinData object accepts arbitrary parameters.  This class sanitizes
+  # those parameters so they can be used by the BinData object.
   class SanitizedParameters
-    extend Forwardable
 
-    def initialize(the_class, params)
+    def initialize(params, the_class)
+      @all_sanitized = false
+      @the_class = the_class
+
       @parameters = {}
+      params.each { |param, value| @parameters[param.to_sym] = value }
+
+      ensure_no_nil_values
+    end
+
+    def length
+      @parameters.size
+    end
+    alias_method :size, :length
 
-      params.each do |k,v|
-        k = k.to_sym
-        if v.nil?
-          raise ArgumentError, "parameter :#{k} has nil value in #{the_class}"
+    def [](param)
+      @parameters[param]
+    end
+
+    def []=(param, value)
+      @parameters[param] = value unless @all_sanitized
+    end
+
+    def has_parameter?(param)
+      @parameters.has_key?(param)
+    end
+
+    def needs_sanitizing?(param)
+      has_parameter?(param) and not self[param].is_a?(SanitizedParameter)
+    end
+
+    def all_sanitized?
+      @all_sanitized
+    end
+
+    def sanitize!(sanitizer)
+      unless @all_sanitized
+        merge_default_parameters!
+
+        @the_class.sanitize_parameters!(self, sanitizer)
+
+        ensure_mandatory_parameters_exist
+        ensure_mutual_exclusion_of_parameters
+
+        @all_sanitized = true
+      end
+    end
+
+    def move_unknown_parameters_to(dest)
+      unless @all_sanitized
+        unused_keys = @parameters.keys - @the_class.accepted_parameters.all
+        unused_keys.each do |param|
+          dest[param] = @parameters.delete(param)
+        end
+      end
+    end
+
+    def delete(param)
+      @parameters.delete(param)
+    end
+
+    #---------------
+    private
+
+    def ensure_no_nil_values
+      @parameters.each do |param, value|
+        if value.nil?
+          raise ArgumentError,
+                "parameter '#{param}' has nil value in #{@the_class}"
         end
+      end
+    end
 
-        @parameters[k] = v
+    def merge_default_parameters!
+      @the_class.default_parameters.each do |param, value|
+        self[param] ||= value
       end
     end
 
-    attr_reader :parameters
+    def ensure_mandatory_parameters_exist
+      @the_class.mandatory_parameters.each do |param|
+        unless has_parameter?(param)
+          raise ArgumentError,
+                  "parameter '#{param}' must be specified in #{@the_class}"
+        end
+      end
+    end
+
+    def ensure_mutual_exclusion_of_parameters
+      return if length < 2
+
+      @the_class.mutually_exclusive_parameters.each do |param1, param2|
+        if has_parameter?(param1) and has_parameter?(param2)
+          raise ArgumentError, "params '#{param1}' and '#{param2}' " +
+                               "are mutually exclusive in #{@the_class}"
+        end
+      end
+    end
 
-    def_delegators :@parameters, :[], :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
@@ -35,26 +117,47 @@ module BinData
     class << self
       # Sanitize +params+ for +the_class+.
       # Returns sanitized parameters.
-      def sanitize(the_class, params)
-        if SanitizedParameters === params
+      def sanitize(params, the_class)
+        if params.is_a?(SanitizedParameters) and params.all_sanitized?
           params
         else
           sanitizer = self.new
-          sanitizer.sanitized_params(the_class, params)
+          sanitizer.create_sanitized_params(params, the_class)
         end
       end
     end
 
     def initialize
       @endian = nil
-      @seen   = []
     end
 
-    # Executes the given block with +endian+ set as the current endian.
+    def create_sanitized_params(params, the_class)
+      sanitized_params = as_sanitized_params(params, the_class)
+      sanitized_params.sanitize!(self)
+
+      sanitized_params
+    end
+
+    def create_sanitized_endian(endian)
+      SanitizedEndian.new(endian)
+    end
+
+    def create_sanitized_choices(choices)
+      SanitizedChoices.new(self, choices)
+    end
+
+    def create_sanitized_fields(endian = nil)
+      SanitizedFields.new(self, endian)
+    end
+
+    def create_sanitized_object_prototype(obj_type, obj_params, endian = nil)
+      SanitizedPrototype.new(self, obj_type, obj_params, endian)
+    end
+
     def with_endian(endian, &block)
       if endian != nil
         saved_endian = @endian
-        @endian = endian
+        @endian = endian.is_a?(SanitizedEndian) ? endian.endian : endian
         yield
         @endian = saved_endian
       else
@@ -70,53 +173,96 @@ module BinData
       registered_class
     end
 
-    def sanitized_params(the_class, params)
-      new_params = params.nil? ? {} : params.dup
+    #---------------
+    private
 
-      if can_sanitize_parameters?(the_class)
-        get_sanitized_params(the_class, new_params)
+    def as_sanitized_params(params, the_class)
+      if SanitizedParameters === params
+        params
       else
-        store_current_endian!(the_class, new_params)
-        new_params
+        SanitizedParameters.new(params || {}, the_class)
       end
     end
+  end
+  #----------------------------------------------------------------------------
 
-    #---------------
-    private
+  class SanitizedParameter; end
 
-    def can_sanitize_parameters?(the_class)
-      not need_to_delay_sanitizing?(the_class)
+  class SanitizedPrototype < SanitizedParameter
+    def initialize(sanitizer, obj_type, obj_params, endian = nil)
+      sanitizer.with_endian(endian) do
+        @obj_class = sanitizer.lookup_class(obj_type)
+        @obj_params = sanitizer.create_sanitized_params(obj_params, @obj_class)
+      end
+    end
+
+    def instantiate(parent = nil)
+      @obj_class.new(@obj_params, parent)
     end
+  end
+  #----------------------------------------------------------------------------
+
+  class SanitizedField < SanitizedParameter
+    def initialize(sanitizer, name, field_type, field_params)
+      @name = name.to_s
+      @prototype = sanitizer.create_sanitized_object_prototype(field_type, field_params)
+    end
+    attr_reader :name
+
+    def instantiate(parent = nil)
+      @prototype.instantiate(parent)
+    end
+  end
+  #----------------------------------------------------------------------------
 
-    def need_to_delay_sanitizing?(the_class)
-      the_class.recursive? and @seen.include?(the_class)
+  class SanitizedFields < SanitizedParameter
+    def initialize(sanitizer, endian)
+      @sanitizer = sanitizer
+      @endian = endian
+      @fields = []
     end
 
-    def get_sanitized_params(the_class, params)
-      result = nil
-      with_class_to_sanitize(the_class) do
-        the_class.sanitize_parameters!(self, params)
-        result = SanitizedParameters.new(the_class, params)
+    def add_field(type, name, params)
+      @sanitizer.with_endian(@endian) do
+        @fields << SanitizedField.new(@sanitizer, name, type, params)
       end
-      result
     end
 
-    def with_class_to_sanitize(the_class, &block)
-      @seen.push(the_class)
-      yield
-      @seen.pop
+    def [](idx)
+      @fields[idx]
     end
 
-    def store_current_endian!(the_class, params)
-      if can_store_endian?(the_class, params)
-        params[:endian] = @endian 
+    def field_names
+      @fields.collect { |field| field.name }
+    end
+  end
+  #----------------------------------------------------------------------------
+
+  class SanitizedChoices < SanitizedParameter
+    def initialize(sanitizer, choices)
+      @choices = {}
+      choices.each_pair do |key, val|
+        type, param = val
+        prototype = sanitizer.create_sanitized_object_prototype(type, param)
+        @choices[key] = prototype
       end
     end
 
-    def can_store_endian?(the_class, params)
-      (@endian != nil and 
-       the_class.accepted_internal_parameters.include?(:endian) and
-       not params.has_key?(:endian))
+    def [](key)
+      @choices[key]
     end
   end
+  #----------------------------------------------------------------------------
+
+  class SanitizedEndian < SanitizedParameter
+    def initialize(endian)
+      unless [:little, :big].include?(endian)
+        raise ArgumentError, "unknown value for endian '#{endian}'"
+      end
+
+      @endian = endian
+    end
+
+    attr_reader :endian
+  end
 end

data/lib/bindata/string.rb

@@ -56,25 +56,13 @@ module BinData
 
     class << self
 
-      def deprecate!(params, old_key, new_key)
-        if params.has_key?(old_key)
-          warn ":#{old_key} is deprecated. Replacing with :#{new_key}"
-          params[new_key] = params.delete(old_key)
-        end
-      end
-
-      def sanitize_parameters!(sanitizer, params)
-        # warn about deprecated param - remove before releasing 1.0
-        deprecate!(params, :trim_value, :trim_padding)
-
+      def sanitize_parameters!(params, sanitizer)
         warn_replacement_parameter(params, :initial_length, :read_length)
 
-        if params.has_key?(:pad_char)
+        if params.has_parameter?(:pad_char)
           ch = params[:pad_char]
           params[:pad_char] = sanitized_pad_char(ch)
         end
-
-        super(sanitizer, params)
       end
 
       #-------------

data/lib/bindata/struct.rb

@@ -1,5 +1,4 @@
 require 'bindata/base'
-require 'bindata/sanitize'
 
 module BinData
   # A Struct is an ordered collection of named data objects.
@@ -69,66 +68,47 @@ module BinData
     end
 
     class << self
-      #### DEPRECATION HACK to warn about inheriting from BinData::Struct
-      #
-      def inherited(subclass) #:nodoc:
-        if subclass != Record
-          # warn about deprecated method - remove before releasing 1.0
-          fail "error: inheriting from BinData::Struct has been deprecated. Inherit from BinData::Record instead."
-        end
-      end
-      #
-      #### DEPRECATION HACK to allow inheriting from BinData::Struct
-
-
-      def sanitize_parameters!(sanitizer, params)
-        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)
+      def sanitize_parameters!(params, sanitizer)
+        sanitize_endian(params, sanitizer)
+        sanitize_fields(params, sanitizer)
+        sanitize_hide(params, sanitizer)
       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
+      def sanitize_endian(params, sanitizer)
+        if params.needs_sanitizing?(:endian)
+          params[:endian] = sanitizer.create_sanitized_endian(params[:endian])
         end
       end
 
-      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)
+      def sanitize_fields(params, sanitizer)
+        if params.needs_sanitizing?(:fields)
+          fields = params[:fields]
+
+          params[:fields] = sanitizer.create_sanitized_fields(params[:endian])
+          fields.each do |ftype, fname, fparams|
+            params[:fields].add_field(ftype, fname, fparams)
           end
+
+          field_names = sanitized_field_names(params[:fields])
+          ensure_field_names_are_valid(field_names)
         end
-        result
       end
 
-      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]
+      def sanitize_hide(params, sanitizer)
+        if params.needs_sanitizing?(:hide) and params.has_parameter?(:fields)
+          field_names = sanitized_field_names(params[:fields])
+          hfield_names = hidden_field_names(params[:hide])
+
+          params[:hide]   = (hfield_names & field_names)
+        end
       end
 
       def sanitized_field_names(sanitized_fields)
-        sanitized_fields.collect { |fclass, fname, fparams| fname }
+        sanitized_fields.field_names
       end
 
       def hidden_field_names(hidden)
@@ -162,32 +142,16 @@ module BinData
     def initialize(params = {}, parent = nil)
       super(params, parent)
 
-      @field_names = get_parameter(:fields).collect { |c, n, p| n }
+      @field_names = get_parameter(:fields).field_names
       @field_objs  = []
     end
 
-    # Clears the field represented by +name+.  If no +name+
-    # is given, clears all fields in the struct.
-    def clear(name = nil)
-      if name.nil?
-        @field_objs.each { |f| f.clear unless f.nil? }
-      else
-        warn "'obj.clear(name)' is deprecated.  Replacing with 'obj.name.clear'"
-        obj = find_obj_for_name(name)
-        obj.clear unless obj.nil?
-      end
+    def clear
+      @field_objs.each { |f| f.clear unless f.nil? }
     end
 
-    # Returns if the field represented by +name+ is clear?.  If no +name+
-    # is given, returns whether all fields are clear.
-    def clear?(name = nil)
-      if name.nil?
-        @field_objs.inject(true) { |all_clear, f| all_clear and (f.nil? or f.clear?) }
-      else
-        warn "'obj.clear?(name)' is deprecated.  Replacing with 'obj.name.clear?'"
-        obj = find_obj_for_name(name)
-        obj.nil? ? true : obj.clear?
-      end
+    def clear?
+      @field_objs.inject(true) { |all_clear, f| all_clear and (f.nil? or f.clear?) }
     end
 
     # Returns a list of the names of all fields accessible through this
@@ -197,7 +161,7 @@ module BinData
       if include_hidden
         @field_names.dup
       else
-        hidden = get_parameter(:hide)
+        hidden = get_parameter(:hide) || []
         @field_names - hidden
       end
     end
@@ -222,10 +186,6 @@ module BinData
     end
 
     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
@@ -268,8 +228,8 @@ module BinData
 
     def instantiate_obj_at(index)
       if @field_objs[index].nil?
-        fclass, fname, fparams = get_parameter(:fields)[index]
-        @field_objs[index] = fclass.new(fparams, self)
+        field = get_parameter(:fields)[index]
+        @field_objs[index] = field.instantiate(self)
       end
     end
 
@@ -287,15 +247,9 @@ module BinData
       @field_objs.each { |f| f.do_write(io) if include_obj(f) }
     end
 
-    def _do_num_bytes(name)
-      if name.nil?
-        instantiate_all_objs
-        sum_num_bytes_for_all_fields.ceil
-      else
-        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
+    def _do_num_bytes(deprecated)
+      instantiate_all_objs
+      sum_num_bytes_for_all_fields.ceil
     end
 
     def _assign(val)