bindata 1.1.0 → 1.2.0

data/lib/bindata/record.rb

@@ -1,3 +1,4 @@
+require 'bindata/dsl'
 require 'bindata/sanitize'
 require 'bindata/struct'
 
@@ -6,22 +7,21 @@ module BinData
   #
   #    require 'bindata'
   #
-  #    class Tuple < BinData::Record
-  #      int8  :x
-  #      int8  :y
-  #      int8  :z
-  #    end
-  #
   #    class SomeDataType < BinData::Record
   #      hide 'a'
   #
   #      int32le :a
   #      int16le :b
-  #      tuple   :s
+  #      struct  :s do
+  #        int8  :x
+  #        int8  :y
+  #        int8  :z
+  #      end
   #    end
   #
   #    obj = SomeDataType.new
   #    obj.field_names   =># ["b", "s"]
+  #    obj.s.field_names =># ["x", "y", "z"]
   #
   #
   # == Parameters
@@ -43,50 +43,12 @@ module BinData
   #                      endian of any numerics in this struct, or in any
   #                      nested data objects.
   class Record < BinData::Struct
+    include DSLMixin
 
-    class << self
-
-      def inherited(subclass) #:nodoc:
-        # Register the names of all subclasses of this class.
-        register(subclass.name, subclass)
-      end
-
-      def endian(endian = nil)
-        @endian ||= default_endian
-        if [:little, :big].include?(endian)
-          @endian = endian
-        elsif endian != nil
-          raise ArgumentError,
-                  "unknown value for endian '#{endian}' in #{self}", caller(1)
-        end
-        @endian
-      end
-
-      def hide(*args)
-        @hide ||= default_hide
-        @hide.concat(args.collect { |name| name.to_s })
-        @hide
-      end
-
-      def fields #:nodoc:
-        @fields ||= default_fields
-      end
-
-      def method_missing(symbol, *args) #:nodoc:
-        name, params = args
-
-        if name.is_a?(Hash)
-          params = name
-          name = nil
-        end
-
-        type = symbol
-        name = name.to_s
-        params ||= {}
-
-        append_field(type, name, params)
-      end
+    register_subclasses
+    dsl_parser :multiple_fields, :optional_fieldnames, :sanitize_fields, :hidden_fields
 
+    class << self
       def sanitize_parameters!(params, sanitizer) #:nodoc:
         params[:fields] = fields
         params[:endian] = endian unless endian.nil?
@@ -94,56 +56,6 @@ module BinData
 
         super(params, sanitizer)
       end
-
-      #-------------
-      private
-
-      def parent_record
-        ancestors[1..-1].find { |cls|
-          cls.ancestors[1..-1].include?(BinData::Record)
-        }
-      end
-
-      def default_endian
-        rec = parent_record
-        rec ? rec.endian : nil
-      end
-
-      def default_hide
-        rec = parent_record
-        rec ? rec.hide.dup : []
-      end
-
-      def default_fields
-        rec = parent_record
-        if rec
-          Sanitizer.new.clone_sanitized_fields(rec.fields)
-        else
-          Sanitizer.new.create_sanitized_fields
-        end
-      end
-
-      def append_field(type, name, params)
-        ensure_valid_name(name)
-
-        fields.add_field(type, name, params, endian)
-      rescue UnknownTypeError => err
-        raise TypeError, "unknown type '#{err.message}' for #{self}", caller(2)
-      end
-
-      def ensure_valid_name(name)
-        if fields.field_names.include?(name)
-          raise SyntaxError, "duplicate field '#{name}' in #{self}", caller(3)
-        end
-        if self.instance_methods.collect { |meth| meth.to_s }.include?(name)
-          raise NameError.new("", name),
-                "field '#{name}' shadows an existing method in #{self}", caller(3)
-        end
-        if self::RESERVED.include?(name)
-          raise NameError.new("", name),
-                "field '#{name}' is a reserved name in #{self}", caller(3)
-        end
-      end
     end
   end
 end

data/lib/bindata/registry.rb

@@ -1,6 +1,13 @@
 module BinData
+
+  class UnRegisteredTypeError < StandardError ; end
+
   # This registry contains a register of name -> class mappings.
   #
+  # Numerics (integers and floating point numbers) have an endian property as
+  # part of their name (e.g. int32be, float_le).  The lookup can either be
+  # on the full name, or on the shortened name plus endian (e.g. "int32", :big)
+  #
   # Names are stored in under_score_style, not camelCase.
   class Registry
 
@@ -21,7 +28,13 @@ module BinData
       key = lookup_key(name, endian)
       try_registering_key(key) unless @registry.has_key?(key)
 
-      @registry[key]
+      @registry[key] || raise(UnRegisteredTypeError, name.to_s)
+    end
+
+    def normalize_name(name, endian = nil)
+      if lookup(name, endian)
+        lookup_key(name, endian)
+      end
     end
 
     def is_registered?(name, endian = nil)
@@ -65,8 +78,8 @@ module BinData
     end
 
     def warn_if_name_is_already_registered(name, class_to_register)
-      if $VERBOSE and @registry[name] != class_to_register
-        prev_class = @registry[name]
+      prev_class = @registry[name]
+      if $VERBOSE and prev_class and prev_class != class_to_register
         warn "warning: replacing registered class #{prev_class} " +
              "with #{class_to_register}"
       end

data/lib/bindata/rest.rb

@@ -17,7 +17,7 @@ module BinData
   #
   class Rest < BinData::BasePrimitive
 
-    register(self.name, self)
+    register_self
 
     #---------------
     private

data/lib/bindata/sanitize.rb

@@ -2,18 +2,25 @@ require 'bindata/registry'
 
 module BinData
 
-  class UnknownTypeError < StandardError ; end
-
-  # A BinData object accepts arbitrary parameters.  This class sanitizes
-  # those parameters so they can be used by the BinData object.
+  # When a BinData object is instantiated, it can be supplied parameters to
+  # determine its behaviour.  These parameters must be sanitized to ensure
+  # their values are valid.  When instantiating many objects, such as an array
+  # of records, there is much duplicated validation.
+  #
+  # The purpose of the sanitizing code is to eliminate the duplicated
+  # validation.
+  #
+  # SanitizedParameters is a hash-like collection of parameters.  Its purpose
+  # it to recursively sanitize the parameters of an entire BinData object chain
+  # at a single time.
   class SanitizedParameters
 
-    def initialize(params, the_class)
+    def initialize(parameters, the_class)
       @all_sanitized = false
       @the_class = the_class
 
       @parameters = {}
-      params.each { |param, value| @parameters[param.to_sym] = value }
+      parameters.each { |key, value| @parameters[key.to_sym] = value }
 
       ensure_no_nil_values
     end
@@ -23,20 +30,22 @@ module BinData
     end
     alias_method :size, :length
 
-    def [](param)
-      @parameters[param]
+    def [](key)
+      @parameters[key]
     end
 
-    def []=(param, value)
-      @parameters[param] = value unless @all_sanitized
+    def []=(key, value)
+      @parameters[key] = value unless @all_sanitized
     end
 
-    def has_parameter?(param)
-      @parameters.has_key?(param)
+    def has_parameter?(key)
+      @parameters.has_key?(key)
     end
 
-    def needs_sanitizing?(param)
-      has_parameter?(param) and not self[param].is_a?(SanitizedParameter)
+    def needs_sanitizing?(key)
+      parameter = @parameters[key]
+
+      parameter and not parameter.is_a?(SanitizedParameter)
     end
 
     def all_sanitized?
@@ -59,40 +68,42 @@ module BinData
     def move_unknown_parameters_to(dest)
       unless @all_sanitized
         unused_keys = @parameters.keys - @the_class.accepted_parameters.all
-        unused_keys.each do |param|
-          next if param == :onlyif
-          dest[param] = @parameters.delete(param)
+        unused_keys.each do |key|
+          dest[key] = @parameters.delete(key)
         end
       end
     end
 
-    def delete(param)
-      @parameters.delete(param)
+    def warn_replacement_parameter(bad_key, suggested_key)
+      if has_parameter?(bad_key)
+        warn ":#{bad_key} is not used with #{@the_class}.  " +
+        "You probably want to change this to :#{suggested_key}"
+      end
     end
 
     #---------------
     private
 
     def ensure_no_nil_values
-      @parameters.each do |param, value|
+      @parameters.each do |key, value|
         if value.nil?
           raise ArgumentError,
-                "parameter '#{param}' has nil value in #{@the_class}"
+                "parameter '#{key}' has nil value in #{@the_class}"
         end
       end
     end
 
     def merge_default_parameters!
-      @the_class.default_parameters.each do |param, value|
-        self[param] ||= value
+      @the_class.default_parameters.each do |key, value|
+        @parameters[key] ||= value
       end
     end
 
     def ensure_mandatory_parameters_exist
-      @the_class.mandatory_parameters.each do |param|
-        unless has_parameter?(param)
+      @the_class.mandatory_parameters.each do |key|
+        unless has_parameter?(key)
           raise ArgumentError,
-                  "parameter '#{param}' must be specified in #{@the_class}"
+                  "parameter '#{key}' must be specified in #{@the_class}"
         end
       end
     end
@@ -100,9 +111,9 @@ module BinData
     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}' " +
+      @the_class.mutually_exclusive_parameters.each do |key1, key2|
+        if has_parameter?(key1) and has_parameter?(key2)
+          raise ArgumentError, "params '#{key1}' and '#{key2}' " +
                                "are mutually exclusive in #{@the_class}"
         end
       end
@@ -142,20 +153,23 @@ module BinData
     end
 
     def create_sanitized_endian(endian)
-      SanitizedEndian.new(endian)
+      # memoize return value to reduce memory usage
+      if endian == :big
+        @@sbe ||= SanitizedBigEndian.new
+      elsif endian == :little
+        @@sle ||= SanitizedLittleEndian.new
+      else
+        raise ArgumentError, "unknown value for endian '#{endian}'"
+      end
     end
 
     def create_sanitized_choices(choices)
       SanitizedChoices.new(self, choices)
     end
 
-    def create_sanitized_fields
-      SanitizedFields.new(self)
-    end
-
-    def clone_sanitized_fields(fields)
+    def create_sanitized_fields(fields = nil)
       new_fields = SanitizedFields.new(self)
-      new_fields.copy_fields(fields)
+      new_fields.copy_fields(fields) if fields
       new_fields
     end
 
@@ -166,7 +180,7 @@ module BinData
     def with_endian(endian, &block)
       if endian != nil
         saved_endian = @endian
-        @endian = endian.is_a?(SanitizedEndian) ? endian.endian : endian
+        @endian = endian.respond_to?(:endian) ? endian.endian : endian
         yield
         @endian = saved_endian
       else
@@ -175,11 +189,7 @@ module BinData
     end
 
     def lookup_class(type)
-      registered_class = RegisteredClasses.lookup(type, @endian)
-      if registered_class.nil?
-        raise UnknownTypeError, type.to_s
-      end
-      registered_class
+      RegisteredClasses.lookup(type, @endian)
     end
 
     #---------------
@@ -228,9 +238,12 @@ module BinData
     def initialize(sanitizer)
       @sanitizer = sanitizer
       @fields = []
+      @field_names = nil
     end
+    attr_reader :fields
 
     def add_field(type, name, params, endian)
+      @field_names = nil
       @fields << SanitizedField.new(@sanitizer, name, type, params, endian)
     end
 
@@ -238,13 +251,18 @@ module BinData
       @fields[idx]
     end
 
+    def empty?
+      @fields.empty?
+    end
+
     def field_names
-      @fields.collect { |field| field.name }
+      # memoize field names to reduce duplicate copies
+      @field_names ||= @fields.collect { |field| field.name }
     end
 
     def copy_fields(other)
-      other_fields = other.instance_variable_get(:@fields)
-      @fields.concat(other_fields)
+      @field_names = nil
+      @fields.concat(other.fields)
     end
   end
   #----------------------------------------------------------------------------
@@ -265,15 +283,15 @@ module BinData
   end
   #----------------------------------------------------------------------------
 
-  class SanitizedEndian < SanitizedParameter
-    def initialize(endian)
-      unless [:little, :big].include?(endian)
-        raise ArgumentError, "unknown value for endian '#{endian}'"
-      end
-
-      @endian = endian
+  class SanitizedBigEndian < SanitizedParameter
+    def endian
+      :big
     end
+  end
 
-    attr_reader :endian
+  class SanitizedLittleEndian < SanitizedParameter
+    def endian
+      :little
+    end
   end
 end

data/lib/bindata/skip.rb

@@ -24,7 +24,8 @@ module BinData
   # <tt>:length</tt>:: The number of bytes to skip.
   #
   class Skip < BinData::BasePrimitive
-    register(self.name, self)
+
+    register_self
 
     mandatory_parameter :length
 

data/lib/bindata/string.rb

@@ -20,7 +20,7 @@ module BinData
   #   obj.value = "abcd"
   #   obj.value #=> "abcd\000\000"
   #
-  #   obj = BinData::String.new(:length => 6, :trim_value => true)
+  #   obj = BinData::String.new(:length => 6, :trim_padding => true)
   #   obj.value = "abcd"
   #   obj.value #=> "abcd"
   #   obj.to_binary_s #=> "abcd\000\000"
@@ -47,7 +47,7 @@ module BinData
   #                            not be trimmed when writing.
   class String < BinData::BasePrimitive
 
-    register(self.name, self)
+    register_self
 
     optional_parameters :read_length, :length, :trim_padding
     default_parameters  :pad_char => "\0"
@@ -57,7 +57,7 @@ module BinData
     class << self
 
       def sanitize_parameters!(params, sanitizer) #:nodoc:
-        warn_replacement_parameter(params, :initial_length, :read_length)
+        params.warn_replacement_parameter(:initial_length, :read_length)
 
         if params.has_parameter?(:pad_char)
           ch = params[:pad_char]