bindata 0.9.3 → 0.10.0

data/lib/bindata/{single_value.rb → primitive.rb}

@@ -1,18 +1,19 @@
-require 'bindata/single'
+require 'bindata/base_primitive'
+require 'bindata/registry'
 require 'bindata/struct'
 
 module BinData
-  # A SingleValue is a declarative way to define a new BinData data type.
-  # The data type must contain a single value only.  For new data types
-  # that contain multiple values see BinData::MultiValue.
+  # A Primitive is a declarative way to define a new BinData data type.
+  # The data type must contain a primitive value only, i.e numbers or strings.
+  # For new data types that contain multiple values see BinData::Record.
   #
-  # To define a new data type, set fields as if for MultiValue and add a
+  # To define a new data type, set fields as if for Record and add a
   # #get and #set method to extract / convert the data between the fields
   # and the #value of the object.
   #
   #    require 'bindata'
   #
-  #    class PascalString < BinData::SingleValue
+  #    class PascalString < BinData::Primitive
   #      uint8  :len,  :value => lambda { data.length }
   #      string :data, :read_length => :len
   #    
@@ -26,12 +27,12 @@ module BinData
   #    end
   #
   #    ps = PascalString.new(:initial_value => "hello")
-  #    ps.to_s #=> "\005hello"
+  #    ps.to_binary_s #=> "\005hello"
   #    ps.read("\003abcde")
   #    ps.value #=> "abc"
   #
   #    # Unsigned 24 bit big endian integer
-  #    class Uint24be < BinData::SingleValue
+  #    class Uint24be < BinData::Primitive
   #      uint8 :byte1
   #      uint8 :byte2
   #      uint8 :byte3
@@ -56,100 +57,93 @@ module BinData
   #
   # == Parameters
   #
-  # SingleValue objects accept all the parameters that BinData::Single do.
+  # Primitive objects accept all the parameters that BinData::BasePrimitive do.
   #
-  class SingleValue < Single
+  class Primitive < BasePrimitive
 
     class << self
 
-      # Register the names of all subclasses of this class.
       def inherited(subclass) #:nodoc:
+        # Register the names of all subclasses of this class.
         register(subclass.name, subclass)
       end
 
-      # Can this data object self reference itself?
       def recursive?
+        # A Primitive can possibly self reference itself.
         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.
       def endian(endian = nil)
         @endian ||= nil
         if [:little, :big].include?(endian)
           @endian = endian
         elsif endian != nil
-          raise ArgumentError, "unknown value for endian '#{endian}'"
+          raise ArgumentError, "unknown value for endian '#{endian}'", caller(1)
         end
         @endian
       end
 
-      # Returns all stored fields.  Should only be called by
-      # #sanitize_parameters
-      def fields
-        @fields || []
-      end
-
-      # Used to define fields for the internal structure.
       def method_missing(symbol, *args)
         name, params = args
 
         type = symbol
-        name = (name.nil? or name == "") ? nil : name.to_s
+        name = name.to_s
         params ||= {}
 
-        # note that fields are stored in an instance variable not a class var
-        @fields ||= []
-
-        # check that type is known
-        unless Sanitizer.type_exists?(type, endian)
-          raise TypeError, "unknown type '#{type}' for #{self}", caller
-        end
-
-        # check that name is okay
-        if name != nil
-          # check for duplicate names
-          @fields.each do |t, n, p|
-            if n == name
-              raise SyntaxError, "duplicate field '#{name}' in #{self}", caller
-            end
-          end
+        ensure_type_exists(type)
+        ensure_valid_name(name) unless name.nil?
 
-          # check that name doesn't shadow an existing method
-          if self.instance_methods.include?(name)
-            raise NameError.new("", name),
-                  "field '#{name}' shadows an existing method", caller
-          end
-        end
-
-        # remember this field.  These fields will be recalled upon creating
-        # an instance of this class
-        @fields.push([type, name, params])
+        append_field(type, name, params)
       end
 
-      # Ensures that +params+ is of the form expected by #initialize.
       def sanitize_parameters!(sanitizer, params)
         struct_params = {}
-        struct_params[:fields] = self.fields
-        struct_params[:endian] = self.endian unless self.endian.nil?
+        struct_params[:fields] = fields
+        struct_params[:endian] = endian unless endian.nil?
         
         params[:struct_params] = struct_params
 
         super(sanitizer, params)
       end
+
+      #-------------
+      private
+
+      def ensure_type_exists(type)
+        unless RegisteredClasses.is_registered?(type, endian)
+          raise TypeError, "unknown type '#{type}' for #{self}", caller(2)
+        end
+      end
+
+      def ensure_valid_name(name)
+        fields.each do |t, n, p|
+          if n == name
+            raise SyntaxError, "duplicate field '#{name}' in #{self}", caller(4)
+          end
+        end
+        if self.instance_methods.include?(name)
+          raise NameError.new("", name),
+                "field '#{name}' shadows an existing method", caller(2)
+        end
+      end
+
+      def append_field(type, name, params)
+        fields.push([type, name, params])
+      end
+
+      def fields
+        @fields ||= []
+      end
     end
 
-    # These are the parameters used by this class.
-    bindata_mandatory_parameter :struct_params
+    mandatory_parameter :struct_params
 
     def initialize(params = {}, parent = nil)
       super(params, parent)
 
-      @struct = BinData::Struct.new(no_eval_param(:struct_params), self)
+      @struct = BinData::Struct.new(get_parameter(:struct_params), self)
     end
 
-    # Forward method calls to the internal struct.
     def method_missing(symbol, *args, &block)
       if @struct.respond_to?(symbol)
         @struct.__send__(symbol, *args, &block)
@@ -158,25 +152,29 @@ module BinData
       end
     end
 
+    def debug_name_of(child)
+      debug_name + "-internal-"
+    end
+
+    def offset_of(child)
+      offset
+    end
+
     #---------------
     private
 
-    # Retrieve a sensible default from the internal struct.
     def sensible_default
       get
     end
 
-    # Read data into the fields of the internal struct then return the value.
-    def read_val(io)
+    def read_and_return_value(io)
       @struct.read(io)
       get
     end
 
-    # Sets +val+ into the fields of the internal struct then returns the
-    # string representation.
-    def val_to_str(val)
+    def value_to_binary_string(val)
       set(val)
-      @struct.to_s
+      @struct.to_binary_s
     end
 
     ###########################################################################
@@ -196,4 +194,13 @@ module BinData
     # To be implemented by subclasses
     ###########################################################################
   end
+
+  class SingleValue < Primitive
+    class << self
+      def inherited(subclass) #:nodoc:
+        warn "BinData::BasePrimitiveValue is deprecated.  Replacing with BinData::Primitive"
+        super
+      end
+    end
+  end
 end

data/lib/bindata/{multi_value.rb → record.rb}

@@ -1,18 +1,18 @@
-require 'bindata/params'
+require 'bindata/registry'
 require 'bindata/struct'
 
 module BinData
-  # A MultiValue is a declarative wrapper around Struct.
+  # A Record is a declarative wrapper around Struct.
   #
   #    require 'bindata'
   #
-  #    class Tuple < BinData::MultiValue
+  #    class Tuple < BinData::Record
   #      int8  :x
   #      int8  :y
   #      int8  :z
   #    end
   #
-  #    class SomeDataType < BinData::MultiValue
+  #    class SomeDataType < BinData::Record
   #      hide 'a'
   #
   #      int32le :a
@@ -42,50 +42,36 @@ 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.
-  class MultiValue < BinData::Struct
+  class Record < BinData::Struct
 
     class << self
-      extend Parameters
 
-      # Register the names of all subclasses of this class.
       def inherited(subclass) #:nodoc:
+        # Register the names of all subclasses of this class.
         register(subclass.name, subclass)
       end
 
-      # Can this data object self reference itself?
       def recursive?
+        # A Record can self reference itself.
         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.
       def endian(endian = nil)
         @endian ||= nil
         if [:little, :big].include?(endian)
           @endian = endian
         elsif endian != nil
-          raise ArgumentError, "unknown value for endian '#{endian}'"
+          raise ArgumentError, "unknown value for endian '#{endian}'", caller(1)
         end
         @endian
       end
 
-      # Returns the names of any hidden fields in this struct.  Any given args
-      # are appended to the hidden list.
       def hide(*args)
-        # note that fields are stored in an instance variable not a class var
         @hide ||= []
         @hide.concat(args.collect { |name| name.to_s })
         @hide
       end
 
-      # Returns all stored fields.
-      # Should only be called by #sanitize_parameters
-      def fields
-        @fields ||= []
-      end
-
-      # Used to define fields for this structure.
       def method_missing(symbol, *args)
         name, params = args
 
@@ -93,78 +79,74 @@ module BinData
         name = name.to_s
         params ||= {}
 
-        # note that fields are stored in an instance variable not a class var
-        @fields ||= []
+        ensure_type_exists(type)
+        ensure_valid_name(name)
+
+        append_field(type, name, params)
+      end
+
+      def sanitize_parameters!(sanitizer, params)
+        merge_endian!(params)
+        merge_fields!(params)
+        merge_hide!(params)
+
+        super(sanitizer, params)
+      end
+
+      #-------------
+      private
 
-        # check that type is known
-        unless Sanitizer.type_exists?(type, endian)
-          raise TypeError, "unknown type '#{type}' for #{self}", caller
+      def ensure_type_exists(type)
+        unless RegisteredClasses.is_registered?(type, endian)
+          raise TypeError, "unknown type '#{type}' for #{self}", caller(2)
         end
+      end
 
-        # check for duplicate names
+      def ensure_valid_name(name)
+        @fields ||= []
         @fields.each do |t, n, p|
           if n == name
-            raise SyntaxError, "duplicate field '#{name}' in #{self}", caller
+            raise SyntaxError, "duplicate field '#{name}' in #{self}", caller(4)
           end
         end
-
-        # check that name doesn't shadow an existing method
         if self.instance_methods.include?(name)
           raise NameError.new("", name),
-                "field '#{name}' shadows an existing method", caller
+                "field '#{name}' shadows an existing method", caller(2)
         end
-
-        # check that name isn't reserved
         if self::RESERVED.include?(name)
           raise NameError.new("", name),
-                "field '#{name}' is a reserved name", caller
+                "field '#{name}' is a reserved name", caller(2)
         end
+      end
 
-        # remember this field.  These fields will be recalled upon creating
-        # an instance of this class
+      def append_field(type, name, params)
+        @fields ||= []
         @fields.push([type, name, params])
       end
 
-      # Ensures that +params+ is of the form expected by #initialize.
-      def sanitize_parameters!(sanitizer, params)
+      def merge_endian!(params)
         endian = params[:endian] || self.endian
-        fields = params[:fields] || self.fields
-        hide   = params[:hide]   || self.hide
-
         params[:endian] = endian unless endian.nil?
-        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!
+      def merge_fields!(params)
+        @fields ||= []
+        fields = params[:fields] || @fields || []
+        params[:fields] = fields
       end
 
-      # Sets the default parameters used by this class.
-      def default_parameters(params = {}); end
+      def merge_hide!(params)
+        hide = params[:hide] || self.hide
+        params[:hide] = hide
+      end
+    end
+  end
 
-      define_x_parameters(:default, {}) do |hash, args|
-        params = args.length > 0 ? args[0] : {}
-        hash.merge!(params)
+  class MultiValue < Record
+    class << self
+      def inherited(subclass) #:nodoc:
+        warn "BinData::MultiValue is deprecated.  Replacing with BinData::Record"
+        super
       end
     end
   end

data/lib/bindata/registry.rb

@@ -1,14 +1,34 @@
-require 'singleton'
-
 module BinData
   # This registry contains a register of name -> class mappings.
+  #
+  # Names are stored in under_score_style, not camelCase.
   class Registry
-    include Singleton
 
     def initialize
       @registry = {}
     end
 
+    def register(name, class_to_register)
+      formatted_name = underscore_name(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)
+
+      result = @registry[key]
+      if result.nil?
+        result = @registry[merge_key_and_endian(key, endian)]
+      end
+      result
+    end
+
+    def is_registered?(name, endian = nil)
+      lookup(name, endian) != nil
+    end
+
     # Convert camelCase +name+ to underscore style.
     def underscore_name(name)
       name.to_s.sub(/.*::/, "").
@@ -18,25 +38,37 @@ module BinData
                 downcase
     end
 
-    # Registers the mapping of +name+ to +klass+.  +name+ is converted
-    # from camelCase to underscore style.
-    # Returns the converted name
-    def register(name, klass)
-      # convert camelCase name to underscore style
-      key = underscore_name(name)
+    #---------------
+    private
 
-      # warn if replacing an existing class
-      if $VERBOSE and (existing = @registry[key])
-        warn "warning: replacing registered class #{existing} with #{klass}"
+    def merge_key_and_endian(key, endian)
+      result = key
+      if endian != nil
+        if /^u?int\d+$/ =~ key
+          result = key + ((endian == :little) ? "le" : "be")
+        elsif /^(float|double)$/ =~ key
+          result = key + ((endian == :little) ? "_le" : "_be")
+        end
       end
+      result
+    end
 
-      @registry[key] = klass
-      key.dup
+    def warn_if_name_is_already_registered(name, class_to_register)
+      if $VERBOSE and @registry.has_key?(name)
+        prev_class = @registry[name]
+        warn "warning: replacing registered class #{prev_class} " +
+             "with #{class_to_register}"
+      end
     end
+  end
+
+  # A singleton registry of all registered classes.
+  RegisteredClasses = Registry.new
 
-    # Returns the class matching a previously registered +name+.
-    def lookup(name)
-      @registry[name.to_s]
+  class Registry
+    def Registry.instance
+      warn "'Registry.instance' is deprecated.  Replacing with 'RegisteredClasses'"
+      RegisteredClasses
     end
   end
 end