bindata 1.1.0 → 1.2.0

data/lib/bindata.rb

@@ -1,5 +1,5 @@
 # BinData -- Binary data manipulator.
-# Copyright (c) 2007 - 2009 Dion Mendel.
+# Copyright (c) 2007 - 2010 Dion Mendel.
 
 require 'bindata/array'
 require 'bindata/bits'
@@ -28,7 +28,7 @@ require 'bindata/deprecated'
 #
 # BinData is released under the same license as Ruby.
 #
-# Copyright (c) 2007 - 2009 Dion Mendel.
+# Copyright (c) 2007 - 2010 Dion Mendel.
 module BinData
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end

data/lib/bindata/array.rb

@@ -54,7 +54,7 @@ module BinData
   class Array < BinData::Base
     include Enumerable
 
-    register(self.name, self)
+    register_self
 
     mandatory_parameter :type
     optional_parameters :initial_length, :read_until
@@ -69,7 +69,7 @@ module BinData
           params[:initial_length] = 0
         end
 
-        warn_replacement_parameter(params, :read_length, :initial_length)
+        params.warn_replacement_parameter(:read_length, :initial_length)
 
         if params.needs_sanitizing?(:type)
           el_type, el_params = params[:type]
@@ -78,16 +78,15 @@ module BinData
       end
     end
 
-    def initialize(params = {}, parent = nil)
-      super(params, parent)
+    def initialize(parameters = {}, parent = nil)
+      super
 
       @element_list      = nil
       @element_prototype = get_parameter(:type)
     end
 
     def clear?
-      @element_list.nil? or
-        elements.inject(true) { |all_clear, el| all_clear and el.clear? }
+      @element_list.nil? or elements.all? { |el| el.clear? }
     end
 
     def clear

data/lib/bindata/base.rb

@@ -13,7 +13,7 @@ module BinData
   # == Parameters
   #
   # Parameters may be provided at initialisation to control the behaviour of
-  # an object.  These params are:
+  # an object.  These parameters are:
   #
   # [<tt>:check_offset</tt>]  Raise an error if the current IO offset doesn't
   #                           meet this criteria.  A boolean return indicates
@@ -27,6 +27,11 @@ module BinData
   #                           <tt>:check_offset</tt>, except that it will
   #                           adjust the IO offset instead of raising an error.
   class Base
+    include AcceptedParametersMixin
+
+    optional_parameters :check_offset, :adjust_offset
+    optional_parameter  :onlyif                            # Used by Struct
+    mutually_exclusive_parameters :check_offset, :adjust_offset
 
     class << self
 
@@ -38,74 +43,46 @@ module BinData
         data
       end
 
-      def mandatory_parameters(*args)
-        accepted_parameters.mandatory(*args)
-      end
-
-      def optional_parameters(*args)
-        accepted_parameters.optional(*args)
-      end
-
-      def default_parameters(*args)
-        accepted_parameters.default(*args)
-      end
-
-      def mutually_exclusive_parameters(*args)
-        accepted_parameters.mutually_exclusive(*args)
+      # Registers this class for use.
+      def register_self
+        register_class(self)
       end
 
-      alias_method :mandatory_parameter, :mandatory_parameters
-      alias_method :optional_parameter, :optional_parameters
-      alias_method :default_parameter, :default_parameters
-
-      def accepted_parameters
-        unless defined? @accepted_parameters
-          ancestor = ancestors[1..-1].find { |cls|
-                                        cls.respond_to?(:accepted_parameters)
-                                       }
-          ancestor_params = ancestor.nil? ? nil : ancestor.accepted_parameters
-          @accepted_parameters = AcceptedParameters.new(ancestor_params)
+      # Registers all subclasses of this class for use
+      def register_subclasses
+        class << self
+          define_method(:inherited) do |subclass|
+            register_class(subclass)
+          end
         end
-        @accepted_parameters
       end
 
-      def sanitize_parameters!(params, sanitizer) #:nodoc:
-      end
-
-      #-------------
-      private
-
-      def warn_replacement_parameter(params, bad_key, suggested_key)
-        if params.has_parameter?(bad_key)
-          warn ":#{bad_key} is not used with #{self}.  " +
-               "You probably want to change this to :#{suggested_key}"
-        end
+      def register_class(class_to_register) #:nodoc:
+        RegisteredClasses.register(class_to_register.name, class_to_register)
       end
 
-      def register(name, class_to_register)
-        RegisteredClasses.register(name, class_to_register)
-      end
+      private :register_self, :register_subclasses, :register_class
     end
 
-    optional_parameters :check_offset, :adjust_offset
-    mutually_exclusive_parameters :check_offset, :adjust_offset
-
     # Creates a new data object.
     #
-    # +params+ is a hash containing symbol keys.  Some params may
-    # reference callable objects (methods or procs).  +parent+ is the
-    # parent data object (e.g. struct, array, choice) this object resides
-    # under.
-    def initialize(params = {}, parent = nil)
-      @params = Sanitizer.sanitize(params, self.class)
+    # +parameters+ is a hash containing symbol keys.  Some parameters may
+    # reference callable objects (methods or procs).
+    #
+    # +parent+ is the parent data object (e.g. struct, array, choice) this
+    # object resides under.
+    def initialize(parameters = {}, parent = nil)
+      @params = Sanitizer.sanitize(parameters, self.class)
       @parent = parent
     end
 
     attr_reader :parent
 
     # Returns the result of evaluating the parameter identified by +key+.
+    #
     # +overrides+ is an optional +parameters+ like hash that allow the
     # parameters given at object construction to be overridden.
+    #
     # Returns nil if +key+ does not refer to any parameter.
     def eval_parameter(key, overrides = {})
       LazyEvaluator.eval(self, get_parameter(key), overrides)
@@ -143,7 +120,7 @@ module BinData
     end
     protected :do_read, :done_read
 
-    # Writes the value for this data to +io+.
+    # Writes the value for this data object to +io+.
     def write(io)
       io = BinData::IO.new(io) unless BinData::IO === io
 
@@ -157,7 +134,7 @@ module BinData
     end
     protected :do_write
 
-    # Returns the number of bytes it will take to write this data.
+    # Returns the number of bytes it will take to write this data object.
     def num_bytes
       do_num_bytes.ceil
     end
@@ -203,8 +180,8 @@ module BinData
 
     # Returns a user friendly name of this object for debugging purposes.
     def debug_name
-      if parent
-        parent.debug_name_of(self)
+      if @parent
+        @parent.debug_name_of(self)
       else
         "obj"
       end
@@ -212,8 +189,8 @@ module BinData
 
     # Returns the offset of this object wrt to its most distant ancestor.
     def offset
-      if parent
-        parent.offset + parent.offset_of(self)
+      if @parent
+        @parent.offset + @parent.offset_of(self)
       else
         0
       end
@@ -221,8 +198,8 @@ module BinData
 
     # Returns the offset of this object wrt to its parent.
     def rel_offset
-      if parent
-        parent.offset_of(self)
+      if @parent
+        @parent.offset_of(self)
       else
         0
       end
@@ -276,6 +253,11 @@ module BinData
     ###########################################################################
     # To be implemented by subclasses
 
+    # Performs sanity checks on the given parameters.  This method converts
+    # the parameters to the form expected by this data object.
+    def self.sanitize_parameters!(parameters, sanitizer) #:nodoc:
+    end
+
     # Resets the internal state to that of a newly created object.
     def clear
       raise NotImplementedError

data/lib/bindata/base_primitive.rb

@@ -51,8 +51,8 @@ module BinData
     optional_parameters :initial_value, :value, :check_value
     mutually_exclusive_parameters :initial_value, :value
 
-    def initialize(params = {}, parent = nil)
-      super(params, parent)
+    def initialize(parameters = {}, parent = nil)
+      super
 
       @value   = nil
       @in_read = false
@@ -77,8 +77,8 @@ module BinData
       assign(val)
     end
 
-    def respond_to?(symbol, include_private=false) #:nodoc:
-      super || value.respond_to?(symbol, include_private)
+    def respond_to?(symbol, include_private = false) #:nodoc:
+      value.respond_to?(symbol, include_private) || super
     end
 
     def method_missing(symbol, *args, &block) #:nodoc:
@@ -115,11 +115,7 @@ module BinData
     def trace_value
       BinData::trace_message do |tracer|
         value_string = _value.inspect
-        if value_string.length > 30
-          value_string = value_string.slice(0 .. 30) + "..."
-        end
-
-        tracer.trace("#{debug_name} => #{value_string}")
+        tracer.trace_obj(debug_name, value_string)
       end
     end
 
@@ -167,8 +163,8 @@ module BinData
     end
 
     # The unmodified value of this data object.  Note that #value calls this
-    # method.  This is so that #value can be overridden in subclasses to 
-    # modify the value.
+    # method.  This indirection is so that #value can be overridden in
+    # subclasses to modify the value.
     def _value
       # Table of possible preconditions and expected outcome
       #   1. :value and !in_read          ->   :value

data/lib/bindata/bits.rb

@@ -5,60 +5,63 @@ module BinData
   # The integer is defined by endian and number of bits.
 
   module BitField #:nodoc: all
-    def self.define_class(nbits, endian)
-      name = "Bit#{nbits}"
-      name += "le" if endian == :little
-      unless BinData.const_defined?(name)
-        BinData.module_eval <<-END
-          class #{name} < BinData::BasePrimitive
-            register(self.name, self)
-            BitField.create_methods(self, #{nbits}, :#{endian.to_s})
-          end
-        END
-      end
-      BinData.const_get(name)
-    end
-
-    def self.create_methods(bit_class, nbits, endian)
-      min = 0
-      max = (1 << nbits) - 1
-      clamp = "val = (val < #{min}) ? #{min} : (val > #{max}) ? #{max} : val"
+    class << self
+      def define_class(nbits, endian)
+        name = "Bit#{nbits}"
+        name += "le" if endian == :little
+        unless BinData.const_defined?(name)
+          BinData.module_eval <<-END
+            class #{name} < BinData::BasePrimitive
+              register_self
+              BitField.define_methods(self, #{nbits}, :#{endian})
+            end
+          END
+        end
 
-      # allow single bits to be used as booleans
-      if nbits == 1
-        clamp = "val = (val == true) ? 1 : (not val) ? 0 : #{clamp}"
+        BinData.const_get(name)
       end
 
-      define_methods(bit_class, nbits, endian.to_s, clamp)
-    end
+      def define_methods(bit_class, nbits, endian)
+        bit_class.module_eval <<-END
+          #---------------
+          private
 
-    def self.define_methods(bit_class, nbits, endian, clamp)
-      bit_class.module_eval <<-END
-        #---------------
-        private
+          def _assign(val)
+            #{create_clamp_code(nbits)}
+            super(val)
+          end
 
-        def _assign(val)
-          #{clamp}
-          super(val)
-        end
+          def _do_write(io)
+            raise "can't write whilst reading \#{debug_name}" if @in_read
+            io.writebits(_value, #{nbits}, :#{endian})
+          end
 
-        def _do_write(io)
-          raise "can't write whilst reading \#{debug_name}" if @in_read
-          io.writebits(_value, #{nbits}, :#{endian})
-        end
+          def _do_num_bytes
+            #{nbits / 8.0}
+          end
 
-        def _do_num_bytes
-          #{nbits} / 8.0
-        end
+          def read_and_return_value(io)
+            io.readbits(#{nbits}, :#{endian})
+          end
 
-        def read_and_return_value(io)
-          io.readbits(#{nbits}, :#{endian})
-        end
+          def sensible_default
+            0
+          end
+        END
+      end
 
-        def sensible_default
-          0
+      def create_clamp_code(nbits)
+        min = 0
+        max = (1 << nbits) - 1
+        clamp = "val = (val < #{min}) ? #{min} : (val > #{max}) ? #{max} : val"
+
+        if nbits == 1
+          # allow single bits to be used as booleans
+          "val = (val == true) ? 1 : (not val) ? 0 : #{clamp}"
+        else
+          clamp
         end
-      END
+      end
     end
   end
 

data/lib/bindata/choice.rb

@@ -54,7 +54,7 @@ module BinData
   #                            selection changes.  Default is false.
   class Choice < BinData::Base
 
-    register(self.name, self)
+    register_self
 
     mandatory_parameters :choices, :selection
     optional_parameter   :copy_on_change
@@ -98,8 +98,8 @@ module BinData
       end
     end
 
-    def initialize(params = {}, parent = nil)
-      super(params, parent)
+    def initialize(parameters = {}, parent = nil)
+      super
 
       @choices = {}
       @last_selection = nil
@@ -133,8 +133,8 @@ module BinData
     #
     #   pc.selection = 17
     #   pc #=> "Type2"
-    def selection=(v)
-      raise NoMethodError
+    def selection=(sel)
+      raise NoMethodError, "See rdoc BinData::Choice.selection= for details"
     end
 
     def clear #:nodoc:
@@ -146,7 +146,7 @@ module BinData
     end
 
     def respond_to?(symbol, include_private = false) #:nodoc:
-      super || current_choice.respond_to?(symbol, include_private)
+      current_choice.respond_to?(symbol, include_private) || super
     end
 
     def method_missing(symbol, *args, &block) #:nodoc:
@@ -164,11 +164,7 @@ module BinData
     def trace_selection
       BinData::trace_message do |tracer|
         selection_string = eval_parameter(:selection).inspect
-        if selection_string.length > 30
-          selection_string = selection_string.slice(0 .. 30) + "..."
-        end
-
-        tracer.trace("#{debug_name}-selection- => #{selection_string}")
+        tracer.trace_obj("#{debug_name}-selection-", selection_string)
       end
     end
 

data/lib/bindata/deprecated.rb

@@ -1,8 +1,23 @@
 module BinData
+  class Base
+    class << self
+      def register(name, class_to_register)
+        if class_to_register == self
+          warn "#{caller[0]} `register(name, class_to_register)' is deprecated as of BinData 1.2.0.  Replace with `register_self'"
+        elsif /inherited/ =~ caller[0]
+          warn "#{caller[0]} `def self.inherited(subclass); register(subclass.name, subclass); end' is deprecated as of BinData 1.2.0.  Replace with `register_subclasses'"
+        else
+          warn "#{caller[0]} `register(name, class_to_register)' is deprecated as of BinData 1.2.0.  Replace with `register_class(class_to_register)'"
+        end
+        register_class(class_to_register)
+      end
+    end
+  end
+
   class SingleValue
     class << self
       def inherited(subclass) #:nodoc:
-        fail "BinData::SingleValue is deprecated.  Downgrade to BinData 0.11.1.\nYou will need to make changes to your code before you can use BinData 1.0.0"
+        fail "BinData::SingleValue is deprecated.  Downgrade to BinData 0.11.1.\nYou will need to make changes to your code before you can use BinData >= 1.0.0"
       end
     end
   end
@@ -10,7 +25,7 @@ module BinData
   class MultiValue
     class << self
       def inherited(subclass) #:nodoc:
-        fail "BinData::MultiValue is deprecated.  Downgrade to BinData 0.11.1.\nYou will need to make changes to your code before you can use BinData 1.0.0"
+        fail "BinData::MultiValue is deprecated.  Downgrade to BinData 0.11.1.\nYou will need to make changes to your code before you can use BinData >= 1.0.0"
       end
     end
   end