bindata 0.10.0 → 0.11.0

data/ChangeLog

@@ -1,6 +1,12 @@
 = BinData Changelog
 
-== Version
+== Version 0.11.0 (2009-06-28)
+
+* Sanitizing code was refactored for speed.
+* Arbitrary sized integers and bit fields are now automatically instantiated.
+* Add ability to wrap existing types and override their parameters.
+
+== Version 0.10.0 (2009-04-17)
 
 * Arbitrary byte sized integers are now supported (e.g. 24bit, 808bit).
 * Renamed String :trim_value parameter to :trim_padding.

data/INSTALL

@@ -1,3 +1,7 @@
+This package is designed to be installed with rubygems.  If you don't
+have rubygems installed on your system, the older setup.rb is
+included as a convenience.
+
   ($ su)
   # ruby setup.rb
 

data/Rakefile

@@ -0,0 +1,17 @@
+$:.unshift(File.join(File.dirname(__FILE__), 'lib'))
+
+require 'bindata'
+require 'rake/clean'
+
+CURRENT_VERSION = BinData::VERSION
+
+PKG_FILES = FileList[
+  "[A-Z]*",
+  "{examples,spec,lib}/**/*.rb",
+  "tasks/**/*.rake",
+  "setup.rb",
+]
+
+task :default => :spec
+
+Dir['tasks/**/*.rake'].each { |t| load t }

data/TODO

@@ -1,26 +1,5 @@
-* Write a Rakefile
-
-* Registry should auto create integers and bits. (e.g. 24bit int, 191bit int)
-
-* Improve speed of Sanitizer for recursive records
-    rework it so that sanitizing is done during definition (before initialising).
-
 * Write a detailed tutorial (probably as a web page).
 
 * Need more examples.
 
-* Need wrapper to be able to define new wrapped classes - with parameters
-
------------------------------------------------------------------------------
-define_wrapped_class("MyInt", :uint32be, :initial_value => 3) #=> MyInt
-define_wrapped_class("ByteArray", :array, :type => :uint8) #=> ByteArray
-define_wrapped_class("MyInt", :uint32be, {:initial_value => :mult}, [], [], {:mult => 3}) #=> MyInt
-          # mandatory, optional, default
------------------------------------------------------------------------------
-
-
-
-
-
-refactor snapshot -> _snapshot et al
-
+* Perhaps refactor snapshot -> _snapshot et al

data/lib/bindata.rb

@@ -1,5 +1,5 @@
 # BinData -- Binary data manipulator.
-# Copyright (c) 2007,2008 Dion Mendel.
+# Copyright (c) 2007 - 2009 Dion Mendel.
 
 require 'bindata/array'
 require 'bindata/bits'
@@ -13,11 +13,13 @@ require 'bindata/string'
 require 'bindata/stringz'
 require 'bindata/struct'
 require 'bindata/trace'
+require 'bindata/wrapper'
+require 'bindata/deprecated'
 
 # = BinData
 # 
 # A declarative way to read and write structured binary data.
 # 
 module BinData
-  VERSION = "0.10.0"
+  VERSION = "0.11.0"
 end

data/lib/bindata/array.rb

@@ -1,5 +1,4 @@
 require 'bindata/base'
-require 'bindata/sanitize'
 
 module BinData
   # An Array is a list of data objects of the same type.
@@ -63,72 +62,38 @@ module BinData
 
     class << self
 
-      def sanitize_parameters!(sanitizer, params)
-        unless params.has_key?(:initial_length) or params.has_key?(:read_until)
+      def sanitize_parameters!(params, sanitizer)
+        unless params.has_parameter?(:initial_length) or
+                 params.has_parameter?(:read_until)
           # ensure one of :initial_length and :read_until exists
           params[:initial_length] = 0
         end
 
         warn_replacement_parameter(params, :read_length, :initial_length)
 
-        if params.has_key?(:type)
-          type, el_params = params[:type]
-          klass = sanitizer.lookup_class(type)
-          sanitized_params = sanitizer.sanitized_params(klass, el_params)
-          params[:type] = [klass, sanitized_params]
+        if params.needs_sanitizing?(:type)
+          el_type, el_params = params[:type]
+          params[:type] = sanitizer.create_sanitized_object_prototype(el_type, el_params)
         end
-
-        super(sanitizer, params)
       end
     end
 
     def initialize(params = {}, parent = nil)
       super(params, parent)
 
-      el_class, el_params = get_parameter(:type)
-
-      @element_list    = nil
-      @element_class   = el_class
-      @element_params  = el_params
+      @element_list      = nil
+      @element_prototype = get_parameter(:type)
     end
 
-    # Returns if the element at position +index+ is clear?.  If +index+
-    # is not given, then returns whether all elements are clear.
-    def clear?(index = nil)
-      if index.nil?
-        @element_list.nil? or elements.inject(true) { |all_clear, f| all_clear and f.clear? }
-      elsif index < elements.length
-        warn "'obj.clear?(n)' is deprecated.  Replacing with 'obj[n].clear?'"
-        elements[index].clear?
-      else
-        true
-      end
+    def clear?
+      @element_list.nil? or
+        elements.inject(true) { |all_clear, el| all_clear and el.clear? }
     end
 
-    # Clears the element at position +index+.  If +index+ is not given, then
-    # the internal state of the array is reset to that of a newly created
-    # object.
-    def clear(index = nil)
-      if index.nil?
-        @element_list = nil
-      elsif index < elements.length
-        warn "'obj.clear(n)' is deprecated.  Replacing with 'obj[n].clear'"
-        elements[index].clear
-      end
+    def clear
+      @element_list = nil
     end
 
-    # Returns the first index of +obj+ in self.
-    #
-    # a = BinData::String.new; a.value = "a"
-    # b = BinData::String.new; b.value = "b"
-    # c = BinData::String.new; c.value = "c"
-    #
-    # arr = BinData::Array.new(:type => :string)
-    # arr.push(a, b, c)
-    #
-    # arr.find_index("b") #=> 1
-    # arr.find_index(c) #=> 2
-    #
     def find_index(obj)
       elements.find_index(obj)
     end
@@ -163,16 +128,6 @@ module BinData
       self
     end
 
-    def append(value = nil)
-      warn "#append is deprecated, use push or slice instead"
-      if value.nil?
-        slice(length)
-      else
-        push(value)
-      end
-      self.last
-    end
-
     # Returns the element at +index+.
     def [](arg1, arg2 = nil)
       if arg1.respond_to?(:to_int) and arg2.nil?
@@ -240,13 +195,11 @@ module BinData
       end
     end
 
-    # The number of elements in this array.
     def length
       elements.length
     end
     alias_method :size, :length
 
-    # Returns true if self array contains no elements.
     def empty?
       length.zero?
     end
@@ -256,7 +209,6 @@ module BinData
       collect { |el| el }
     end
 
-    # Iterate over each element in the array.
     def each
       elements.each { |el| yield el }
     end
@@ -297,7 +249,7 @@ module BinData
 
     def _do_read(io)
       if has_parameter?(:initial_length)
-        elements.each { |f| f.do_read(io) }
+        elements.each { |el| el.do_read(io) }
       elsif has_parameter?(:read_until)
         read_until(io)
       end
@@ -312,46 +264,37 @@ module BinData
     end
 
     def read_until_eof(io)
-      finished = false
-      while not finished
+      loop do
         element = append_new_element
         begin
           element.do_read(io)
         rescue
           elements.pop
-          finished = true
+          break
         end
       end
     end
 
     def read_until_condition(io)
-      finished = false
-      while not finished
+      loop do
         element = append_new_element
         element.do_read(io)
         variables = { :index => self.length - 1, :element => self.last,
                       :array => self }
-        finished = eval_parameter(:read_until, variables)
+        break if eval_parameter(:read_until, variables)
       end
     end
 
     def _done_read
-      elements.each { |f| f.done_read }
+      elements.each { |el| el.done_read }
     end
 
     def _do_write(io)
-      elements.each { |f| f.do_write(io) }
+      elements.each { |el| el.do_write(io) }
     end
 
-    def _do_num_bytes(index)
-      if index.nil?
-        sum_num_bytes_for_all_elements.ceil
-      elsif index < elements.length
-        warn "'obj.num_bytes(n)' is deprecated.  Replacing with 'obj[n].num_bytes'"
-        elements[index].do_num_bytes
-      else
-        0
-      end
+    def _do_num_bytes(deprecated)
+      sum_num_bytes_for_all_elements.ceil
     end
 
     def _assign(array)
@@ -361,7 +304,7 @@ module BinData
     end
 
     def _snapshot
-      elements.collect { |e| e.snapshot }
+      elements.collect { |el| el.snapshot }
     end
 
     def elements
@@ -383,7 +326,7 @@ module BinData
     end
 
     def new_element
-      @element_class.new(@element_params, self)
+      @element_prototype.instantiate(self)
     end
 
     def sum_num_bytes_for_all_elements

data/lib/bindata/base.rb

@@ -39,28 +39,45 @@ module BinData
         data
       end
 
-      def recursive?
-        # data objects do not self reference by default
-        false
+      def mandatory_parameters(*args)
+        accepted_parameters.mandatory(*args)
       end
 
-      AcceptedParameters.define_all_accessors(self, :internal)
+      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)
+      end
 
-      def accepted_internal_parameters
-        internal = AcceptedParameters.get(self, :internal)
-        internal.all
+      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)
+        end
+        @accepted_parameters
       end
 
-      def sanitize_parameters!(sanitizer, params)
-        internal = AcceptedParameters.get(self, :internal)
-        internal.sanitize_parameters!(sanitizer, params)
+      def sanitize_parameters!(params, sanitizer)
       end
 
       #-------------
       private
 
       def warn_replacement_parameter(params, bad_key, suggested_key)
-        if params.has_key?(bad_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
@@ -81,7 +98,7 @@ module BinData
     # parent data object (e.g. struct, array, choice) this object resides
     # under.
     def initialize(params = {}, parent = nil)
-      @params = Sanitizer.sanitize(self.class, params)
+      @params = Sanitizer.sanitize(params, self.class)
       @parent = parent
     end
 
@@ -104,7 +121,7 @@ module BinData
 
     # Returns whether +key+ exists in the +parameters+ hash.
     def has_parameter?(key)
-      @params.has_key?(key)
+      @params.has_parameter?(key)
     end
 
     # Reads data into this data object.
@@ -142,13 +159,13 @@ module BinData
     protected :do_write
 
     # Returns the number of bytes it will take to write this data.
-    def num_bytes(what = nil)
-      num = do_num_bytes(what)
+    def num_bytes(deprecated = nil)
+      num = do_num_bytes(deprecated)
       num.ceil
     end
 
-    def do_num_bytes(what = nil)
-      _do_num_bytes(what)
+    def do_num_bytes(deprecated = nil)
+      _do_num_bytes(deprecated)
     end
     protected :do_num_bytes
 
@@ -253,7 +270,7 @@ module BinData
     end
 
     # Returns true if the object has not been changed since creation.
-    def clear?(*args)
+    def clear?
       raise NotImplementedError
     end
 
@@ -285,7 +302,7 @@ module BinData
     end
 
     # Returns the number of bytes it will take to write this data.
-    def _do_num_bytes(what)
+    def _do_num_bytes(deprecated)
       raise NotImplementedError
     end
 
@@ -304,12 +321,6 @@ module BinData
     public :clear, :clear?, :debug_name_of, :offset_of
     private :_do_read, :_done_read, :_do_write, :_do_num_bytes, :_assign, :_snapshot
 
-def single_value?
-  warn "#single_value? is deprecated.  It should no longer be needed"
-  false
-end
-public :single_value?
-
     # End To be implemented by subclasses
     ###########################################################################
   end

data/lib/bindata/base_primitive.rb

@@ -89,6 +89,15 @@ module BinData
       end
     end
 
+    def eql?(other)
+      # double dispatch
+      other.eql?(snapshot)
+    end
+
+    def hash
+      snapshot.hash
+    end
+
     #---------------
     private
 

data/lib/bindata/choice.rb

@@ -1,6 +1,4 @@
-require 'forwardable'
 require 'bindata/base'
-require 'bindata/sanitize'
 require 'bindata/trace'
 
 module BinData
@@ -55,7 +53,6 @@ module BinData
   #                            selection to the current selection whenever the
   #                            selection changes.  Default is false.
   class Choice < BinData::Base
-    extend Forwardable
 
     register(self.name, self)
 
@@ -64,14 +61,12 @@ module BinData
 
     class << self
 
-      def sanitize_parameters!(sanitizer, params)
-        if params.has_key?(:choices)
+      def sanitize_parameters!(params, sanitizer)
+        if params.needs_sanitizing?(:choices)
           choices = choices_as_hash(params[:choices])
           ensure_valid_keys(choices)
-          params[:choices] = sanitized_choices(sanitizer, choices)
+          params[:choices] = sanitizer.create_sanitized_choices(choices)
         end
-
-        super(sanitizer, params)
       end
 
       #-------------
@@ -97,21 +92,10 @@ module BinData
         if choices.has_key?(nil)
           raise ArgumentError, ":choices hash may not have nil key"
         end
-        if choices.keys.detect { |k| Symbol === k }
+        if choices.keys.detect { |key| Symbol === key }
           raise ArgumentError, ":choices hash may not have symbols for keys"
         end
       end
-
-      def sanitized_choices(sanitizer, choices)
-        result = {}
-        choices.each_pair do |key, val|
-          type, param = val
-          the_class = sanitizer.lookup_class(type)
-          sanitized_params = sanitizer.sanitized_params(the_class, param)
-          result[key] = [the_class, sanitized_params]
-        end
-        result
-      end
     end
 
     def initialize(params = {}, parent = nil)
@@ -133,9 +117,9 @@ module BinData
     # If you really *must* be able to programmatically adjust the selection
     # then try something like the following.
     #
-    #   class ProgrammaticChoice < BinData::Record
-    #     choice :data, :choices => :choices, :selection => :selection
-    #     attrib_accessor :selection
+    #   class ProgrammaticChoice < BinData::Wrapper
+    #     choice :selection => :selection
+    #     attr_accessor :selection
     #   end
     #
     #   type1 = [:string, {:value => "Type1"}]
@@ -145,26 +129,20 @@ module BinData
     #   pc = ProgrammaticChoice.new(:choices => choices)
     #
     #   pc.selection = 5
-    #   pc.data #=> "Type1"
+    #   pc #=> "Type1"
     #
     #   pc.selection = 17
-    #   pc.data #=> "Type2"
+    #   pc #=> "Type2"
     def selection=(v)
       raise NoMethodError
     end
 
-    def_delegators :current_choice, :clear, :clear?
-
-    def respond_to?(symbol, include_private = false)
-      super || current_choice.respond_to?(symbol, include_private)
+    def clear
+      current_choice.clear
     end
 
-    def method_missing(symbol, *args, &block)
-      if current_choice.respond_to?(symbol)
-        current_choice.__send__(symbol, *args, &block)
-      else
-        super
-      end
+    def clear?
+      current_choice.clear?
     end
 
     def debug_name_of(child)
@@ -175,6 +153,14 @@ module BinData
       offset
     end
 
+    def respond_to?(symbol, include_private = false)
+      super || current_choice.respond_to?(symbol, include_private)
+    end
+
+    def method_missing(symbol, *args, &block)
+      current_choice.__send__(symbol, *args, &block)
+    end
+
     #---------------
     private
 
@@ -202,8 +188,8 @@ module BinData
       current_choice.do_write(io)
     end
 
-    def _do_num_bytes(what)
-      current_choice.do_num_bytes(what)
+    def _do_num_bytes(deprecated)
+      current_choice.do_num_bytes(deprecated)
     end
 
     def _assign(val)
@@ -236,11 +222,11 @@ module BinData
     end
 
     def instantiate_choice(selection)
-      choice_class, choice_params = get_parameter(:choices)[selection]
-      if choice_class.nil?
+      prototype = get_parameter(:choices)[selection]
+      if prototype.nil?
         raise IndexError, "selection '#{selection}' does not exist in :choices for #{debug_name}"
       end
-      choice_class.new(choice_params, self)
+      prototype.instantiate(self)
     end
 
     def copy_previous_value_if_required(selection, obj)