bindata 0.8.1 → 0.9.0

data/lib/bindata/choice.rb

@@ -1,29 +1,54 @@
+require 'forwardable'
 require 'bindata/base'
+require 'bindata/sanitize'
 
 module BinData
   # A Choice is a collection of data objects of which only one is active
   # at any particular time.
   #
   #   require 'bindata'
-  #   require 'stringio'
   #
-  #   choices = [ [:int8, {:value => 3}], [:int8, {:value => 5}] ]
+  #   type1 = [:string, {:value => "Type1"}]
+  #   type2 = [:string, {:value => "Type2"}]
+  #
+  #   choices = [ type1, type2 ]
   #   a = BinData::Choice.new(:choices => choices, :selection => 1)
-  #   a.value # => 5
+  #   a.value # => "Type2"
+  #
+  #   choices = [ nil, nil, nil, type1, nil, type2 ]
+  #   a = BinData::Choice.new(:choices => choices, :selection => 3)
+  #   a.value # => "Type1"
+  #
+  #   choices = {5 => type1, 17 => type2}
+  #   a = BinData::Choice.new(:choices => choices, :selection => 5)
+  #   a.value # => "Type1"
+  #
+  #   mychoice = 'big'
+  #   choices = {'big' => :uint16be, 'little' => :uint16le}
+  #   a = BinData::Choice.new(:choices => choices,
+  #                           :selection => lambda { mychoice })
+  #   a.value  = 256
+  #   a.to_s #=> "\001\000"
+  #   mychoice[0..-1] = 'little'
+  #   a.to_s #=> "\000\001"
+  #
   #
   # == Parameters
   #
   # Parameters may be provided at initialisation to control the behaviour of
   # an object.  These params are:
   #
-  # <tt>:choices</tt>::   An array specifying the possible data objects.
-  #                       The format of the array is a list of symbols
-  #                       representing the data object type.  If a choice
-  #                       is to have params passed to it, then it should be
-  #                       provided as [type_symbol, hash_params].
-  # <tt>:selection</tt>:: An index into the :choices array which specifies
-  #                       the currently active choice.
-  class Choice < Base
+  # <tt>:choices</tt>::   Either an array or a hash specifying the possible
+  #                       data objects.  The format of the array/hash.values is
+  #                       a list of symbols representing the data object type.
+  #                       If a choice is to have params passed to it, then it
+  #                       should be provided as [type_symbol, hash_params].
+  #                       An implementation gotcha is that the hash may not
+  #                       contain symbols as keys.
+  # <tt>:selection</tt>:: An index/key into the :choices array/hash which
+  #                       specifies the currently active choice.
+  class Choice < BinData::Base
+    extend Forwardable
 
     # Register this class
     register(self.name, self)
@@ -31,61 +56,93 @@ module BinData
     # These are the parameters used by this class.
     mandatory_parameters :choices, :selection
 
-    def initialize(params = {}, env = nil)
-      super(params, env)
-
-      # instantiate all choices
-      @choices = []
-      param(:choices).each do |choice_type, choice_params|
-        choice_params ||= {}
-        klass = klass_lookup(choice_type)
-        if klass.nil?
-          raise TypeError, "unknown type '#{choice_type.id2name}' for #{self}"
+    class << self
+
+      # Returns a sanitized +params+ that is of the form expected
+      # by #initialize.
+      def sanitize_parameters(params, endian = nil)
+        params = params.dup
+
+        if params.has_key?(:choices)
+          choices = params[:choices]
+
+          case choices
+          when ::Hash
+            new_choices = {}
+            choices.keys.each do |key|
+              # ensure valid hash keys
+              if Symbol === key
+                msg = ":choices hash may not have symbols for keys"
+                raise ArgumentError, msg
+              elsif key.nil?
+                raise ArgumentError, ":choices hash may not have nil key"
+              end
+
+              # collect sanitized choice values
+              type, param = choices[key]
+              klass = lookup(type, endian)
+              if klass.nil?
+                raise TypeError, "unknown type '#{type}' for #{self}"
+              end
+              val = [klass, SanitizedParameters.new(klass, param, endian)]
+              new_choices[key] = val
+            end
+            params[:choices] = new_choices
+          when ::Array
+            choices.collect! do |type, param|
+              if type.nil?
+                # allow sparse arrays
+                nil
+              else
+                klass = lookup(type, endian)
+                if klass.nil?
+                  raise TypeError, "unknown type '#{type}' for #{self}"
+                end
+                [klass, SanitizedParameters.new(klass, param, endian)]
+              end
+            end
+            params[:choices] = choices
+          else
+            raise ArgumentError, "unknown type for :choices (#{choices.class})"
+          end
         end
-        @choices << klass.new(choice_params, create_env)
-      end
-    end
-
-    # Resets the internal state to that of a newly created object.
-    def clear
-      the_choice.clear
-    end
 
-    # Returns if the selected data object is clear?.
-    def clear?
-      the_choice.clear?
-    end
-
-    # Reads the value of the selected data object from +io+.
-    def _do_read(io)
-      the_choice.do_read(io)
-    end
+        super(params, endian)
+      end
 
-    # To be called after calling #do_read.
-    def done_read
-      the_choice.done_read
-    end
+      # Returns all the possible field names a :choice may have.
+      def all_possible_field_names(sanitized_params)
+        unless SanitizedParameters === sanitized_params
+          raise ArgumentError, "parameters aren't sanitized"
+        end
 
-    # Writes the value of the selected data object to +io+.
-    def _write(io)
-      the_choice.write(io)
+        choices = sanitized_params[:choices]
+
+        names = []
+        if ::Array === choices
+          choices.each do |cklass, cparams|
+            names.concat(cklass.all_possible_field_names(cparams))
+          end
+        elsif ::Hash === choices
+          choices.values.each do |cklass, cparams|
+            names.concat(cklass.all_possible_field_names(cparams))
+          end
+        end
+        names
+      end
     end
 
-    # Returns the number of bytes it will take to write the
-    # selected data object.
-    def _num_bytes(what)
-      the_choice.num_bytes(what)
-    end
+    def initialize(params = {}, env = nil)
+      super(params, env)
 
-    # Returns a snapshot of the selected data object.
-    def snapshot
-      the_choice.snapshot
+      # prepare collection of instantiated choice objects
+      @choices = (param(:choices) === ::Array) ? [] : {}
+      @last_key = nil
     end
 
-    # Returns a list of the names of all fields of the selected data object.
-    def field_names
-      the_choice.field_names
-    end
+    def_delegators :the_choice, :clear, :clear?, :_do_read, :done_read
+    def_delegators :the_choice, :_write, :_num_bytes, :snapshot
+    def_delegators :the_choice, :single_value?, :field_names
 
     # Returns the data object that stores values for +name+.
     def find_obj_for_name(name)
@@ -110,11 +167,35 @@ module BinData
 
     # Returns the selected data object.
     def the_choice
-      index = eval_param(:selection)
-      if index < 0 or index >= @choices.length
-        raise IndexError, "selection #{index} is out of range"
+      key = eval_param(:selection)
+
+      if key.nil?
+        raise IndexError, ":selection returned nil value"
+      end
+
+      obj = @choices[key]
+      if obj.nil?
+        # instantiate choice object
+        choice_klass, choice_params = param(:choices)[key]
+        if choice_klass.nil?
+          raise IndexError, "selection #{key} does not exist in :choices"
+        end
+        obj = choice_klass.new(choice_params, create_env)
+        @choices[key] = obj
       end
-      @choices[index]
+
+      # for single_values copy the value when the selected object changes
+      if key != @last_key
+        if @last_key != nil
+          prev = @choices[@last_key]
+          if prev != nil and prev.single_value? and obj.single_value?
+            obj.value = prev.value
+          end
+        end
+        @last_key = key
+      end
+
+      obj
     end
   end
 end

data/lib/bindata/float.rb

@@ -64,21 +64,25 @@ module BinData
 
   # Single precision floating point number in little endian format
   class FloatLe < Single
+    register(self.name, self)
     Float.create_float_methods(self, true, :little)
   end
 
   # Single precision floating point number in big endian format
   class FloatBe < Single
+    register(self.name, self)
     Float.create_float_methods(self, true, :big)
   end
 
   # Double precision floating point number in little endian format
   class DoubleLe < Single
+    register(self.name, self)
     Float.create_float_methods(self, false, :little)
   end
 
   # Double precision floating point number in big endian format
   class DoubleBe < Single
+    register(self.name, self)
     Float.create_float_methods(self, false, :big)
   end
 end

data/lib/bindata/int.rb

@@ -101,71 +101,85 @@ module BinData
 
   # Unsigned 1 byte integer.
   class Uint8 < Single
+    register(self.name, self)
     Integer.create_uint_methods(self, 8, :little)
   end
 
   # Unsigned 2 byte little endian integer.
   class Uint16le < Single
+    register(self.name, self)
     Integer.create_uint_methods(self, 16, :little)
   end
 
   # Unsigned 2 byte big endian integer.
   class Uint16be < Single
+    register(self.name, self)
     Integer.create_uint_methods(self, 16, :big)
   end
 
   # Unsigned 4 byte little endian integer.
   class Uint32le < Single
+    register(self.name, self)
     Integer.create_uint_methods(self, 32, :little)
   end
 
   # Unsigned 4 byte big endian integer.
   class Uint32be < Single
+    register(self.name, self)
     Integer.create_uint_methods(self, 32, :big)
   end
 
   # Unsigned 8 byte little endian integer.
   class Uint64le < Single
+    register(self.name, self)
     Integer.create_uint_methods(self, 64, :little)
   end
 
   # Unsigned 8 byte big endian integer.
   class Uint64be < Single
+    register(self.name, self)
     Integer.create_uint_methods(self, 64, :big)
   end
 
   # Signed 1 byte integer.
   class Int8 < Single
+    register(self.name, self)
     Integer.create_int_methods(self, 8, :little)
   end
 
   # Signed 2 byte little endian integer.
   class Int16le < Single
+    register(self.name, self)
     Integer.create_int_methods(self, 16, :little)
   end
 
   # Signed 2 byte big endian integer.
   class Int16be < Single
+    register(self.name, self)
     Integer.create_int_methods(self, 16, :big)
   end
 
   # Signed 4 byte little endian integer.
   class Int32le < Single
+    register(self.name, self)
     Integer.create_int_methods(self, 32, :little)
   end
 
   # Signed 4 byte big endian integer.
   class Int32be < Single
+    register(self.name, self)
     Integer.create_int_methods(self, 32, :big)
   end
 
   # Signed 8 byte little endian integer.
   class Int64le < Single
+    register(self.name, self)
     Integer.create_int_methods(self, 64, :little)
   end
 
   # Signed 8 byte big endian integer.
   class Int64be < Single
+    register(self.name, self)
     Integer.create_int_methods(self, 64, :big)
   end
 end

data/lib/bindata/lazy.rb

@@ -16,6 +16,8 @@ module BinData
     # An empty hash shared by all instances
     @@empty_hash = Hash.new.freeze
 
+    @@variables_cache = {}
+
     # Creates a new environment.  +parent+ is the environment of the
     # parent data object.
     def initialize(parent = nil)
@@ -39,10 +41,25 @@ module BinData
     # will be accessible as a variable for any lambda evaluated
     # with #lazy_eval.
     def add_variable(sym, value)
+      sym = sym.to_sym
       if @variables.equal?(@@empty_hash)
-        @variables = {}
+        # optimise the case where only 1 variable is added as this
+        # is the most common occurance (BinData::Arrays adding index)
+        key = [sym, value]
+        @variables = @@variables_cache[key]
+        if @variables.nil?
+          # cache this variable and value so it can be shared with
+          # other LazyEvalEnvs to keep memory usage down
+          @variables = {sym => value}.freeze
+          @@variables_cache[key] = @variables
+        end
+      else
+        if @variables.length == 1
+          key = @variables.keys[0]
+          @variables = {key => @variables[key]}
+        end
+        @variables[sym] = value
       end
-      @variables[sym.to_sym] = value
     end
 
     # TODO: offset_of needs to be better thought out

data/lib/bindata/multi_value.rb

@@ -0,0 +1,144 @@
+require 'bindata/struct'
+
+module BinData
+  # A MultiValue is a declarative wrapper around Struct.
+  #
+  #    require 'bindata'
+  #
+  #    class Tuple < BinData::MultiValue
+  #      int8  :x
+  #      int8  :y
+  #      int8  :z
+  #    end
+  #
+  #    class SomeDataType < BinData::MultiValue
+  #      hide 'a'
+  #
+  #      int32le :a
+  #      int16le :b
+  #      tuple   nil
+  #    end
+  #
+  #    obj = SomeDataType.new
+  #    obj.field_names   =># ["b", "x", "y", "z"]
+  #
+  #
+  # == Parameters
+  #
+  # Parameters may be provided at initialisation to control the behaviour of
+  # an object.  These params are:
+  #
+  # <tt>:fields</tt>::   An array specifying the fields for this struct.
+  #                      Each element of the array is of the form [type, name,
+  #                      params].  Type is a symbol representing a registered
+  #                      type.  Name is the name of this field.  Name may be
+  #                      nil as in the example above.  Params is an optional
+  #                      hash of parameters to pass to this field when
+  #                      instantiating it.
+  # <tt>:hide</tt>::     A list of the names of fields that are to be hidden
+  #                      from the outside world.  Hidden fields don't appear
+  #                      in #snapshot or #field_names but are still accessible
+  #                      by name.
+  # <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 < Struct
+
+    class << self
+      # Register the names of all subclasses of this class.
+      def inherited(subclass) #:nodoc:
+        register(subclass.name, subclass)
+      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}'"
+        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 ||= []
+        args.each do |name|
+          next if name.nil?
+          @hide << name.to_s
+        end
+        @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
+
+        type = symbol
+        name = (name.nil? or name == "") ? nil : name.to_s
+        params ||= {}
+
+        # note that fields are stored in an instance variable not a class var
+        @fields ||= []
+
+        # check that type is known
+        if lookup(type, endian).nil?
+          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
+
+          # 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
+
+          # check that name isn't reserved
+          if ::Hash.instance_methods.include?(name)
+            raise NameError.new("", name),
+                  "field '#{name}' is a reserved name", caller
+          end
+        end
+
+        # remember this field.  These fields will be recalled upon creating
+        # an instance of this class
+        @fields.push([type, name, params])
+      end
+
+      # Returns a sanitized +params+ that is of the form expected
+      # by #initialize.
+      def sanitize_parameters(params, endian = nil)
+        params = params.dup
+
+        # possibly override endian
+        endian = params[:endian] || self.endian || endian
+        unless endian.nil?
+          params[:endian] = endian
+        end
+
+        params[:fields] = params[:fields] || self.fields
+        params[:hide] = params[:hide] || self.hide
+
+        super(params, endian)
+      end
+    end
+  end
+end