bindata 0.9.3 → 0.10.0

data/lib/bindata/base.rb

@@ -16,11 +16,6 @@ module BinData
   # Parameters may be provided at initialisation to control the behaviour of
   # an object.  These params are:
   #
-  # [<tt>:readwrite</tt>]     Deprecated. An alias for :onlyif.
-  # [<tt>:onlyif</tt>]        Used to indicate a data object is optional.
-  #                           if false, calls to #read or #write will not
-  #                           perform any I/O, #num_bytes will return 0 and
-  #                           #snapshot will return nil.  Default is true.
   # [<tt>:check_offset</tt>]  Raise an error if the current IO offset doesn't
   #                           meet this criteria.  A boolean return indicates
   #                           success or failure.  Any other return is compared
@@ -35,94 +30,49 @@ module BinData
   class Base
 
     class << self
-      extend Parameters
 
-      # Define methods for:
-      #   bindata_mandatory_parameters
-      #   bindata_optional_parameters
-      #   bindata_default_parameters
-      #   bindata_mutually_exclusive_parameters
-
-      define_x_parameters(:bindata_mandatory, []) do |array, args|
-        args.each { |arg| array << arg.to_sym }
-        array.uniq!
-      end
-
-      define_x_parameters(:bindata_optional, []) do |array, args|
-        args.each { |arg| array << arg.to_sym }
-        array.uniq!
+      # Instantiates this class and reads from +io+, returning the newly
+      # created data object.
+      def read(io)
+        data = self.new
+        data.read(io)
+        data
       end
 
-      define_x_parameters(:bindata_default, {}) do |hash, args|
-        params = args.length > 0 ? args[0] : {}
-        hash.merge!(params)
+      def recursive?
+        # data objects do not self reference by default
+        false
       end
 
-      define_x_parameters(:bindata_mutually_exclusive, []) do |array, args|
-        array << [args[0].to_sym, args[1].to_sym]
-      end
+      AcceptedParameters.define_all_accessors(self, :internal)
 
-      # Returns a list of internal parameters that are accepted by this object
-      def internal_parameters
-        (bindata_mandatory_parameters + bindata_optional_parameters +
-         bindata_default_parameters.keys).uniq
+      def accepted_internal_parameters
+        internal = AcceptedParameters.get(self, :internal)
+        internal.all
       end
 
-      # Ensures that +params+ is of the form expected by #initialize.
       def sanitize_parameters!(sanitizer, params)
-        # replace :readwrite with :onlyif
-        if params.has_key?(:readwrite)
-          warn ":readwrite is deprecated. Replacing with :onlyif"
-          params[:onlyif] = params.delete(:readwrite)
-        end
-
-        # add default parameters
-        bindata_default_parameters.each do |k,v|
-          params[k] = v unless params.has_key?(k)
-        end
-
-        # ensure mandatory parameters exist
-        bindata_mandatory_parameters.each do |prm|
-          if not params.has_key?(prm)
-            raise ArgumentError, "parameter ':#{prm}' must be specified " +
-                                 "in #{self}"
-          end
-        end
-
-        # ensure mutual exclusion
-        bindata_mutually_exclusive_parameters.each do |param1, param2|
-          if params.has_key?(param1) and params.has_key?(param2)
-            raise ArgumentError, "params #{param1} and #{param2} " +
-                                 "are mutually exclusive"
-          end
-        end
+        internal = AcceptedParameters.get(self, :internal)
+        internal.sanitize_parameters!(sanitizer, params)
       end
 
-      # Can this data object self reference itself?
-      def recursive?
-        false
-      end
+      #-------------
+      private
 
-      # Instantiates this class and reads from +io+.  For single value objects
-      # just the value is returned, otherwise the newly created data object is
-      # returned.
-      def read(io)
-        data = self.new
-        data.read(io)
-        data.single_value? ? data.value : data
+      def warn_replacement_parameter(params, bad_key, suggested_key)
+        if params.has_key?(bad_key)
+          warn ":#{bad_key} is not used with #{self}.  " +
+               "You probably want to change this to :#{suggested_key}"
+        end
       end
 
-      # Registers the mapping of +name+ to +klass+.
-      def register(name, klass)
-        Registry.instance.register(name, klass)
+      def register(name, class_to_register)
+        RegisteredClasses.register(name, class_to_register)
       end
-      private :register
     end
 
-    # Define the parameters we use in this class.
-    bindata_optional_parameters :check_offset, :adjust_offset
-    bindata_default_parameters :onlyif => true
-    bindata_mutually_exclusive_parameters :check_offset, :adjust_offset
+    optional_parameters :check_offset, :adjust_offset
+    mutually_exclusive_parameters :check_offset, :adjust_offset
 
     # Creates a new data object.
     #
@@ -135,15 +85,29 @@ module BinData
       @parent = parent
     end
 
-    # The parent data object.
-    attr_accessor :parent
+    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)
+    end
+
+    # Returns the parameter referenced by +key+.
+    # Use this method if you are sure the parameter is not to be evaluated.
+    # You most likely want #eval_parameter.
+    def get_parameter(key)
+      @params[key]
+    end
 
-    # Returns all the custom parameters supplied to this data object.
-    def parameters
-      @params.extra_parameters
+    # Returns whether +key+ exists in the +parameters+ hash.
+    def has_parameter?(key)
+      @params.has_key?(key)
     end
 
-    # Reads data into this data object by calling #do_read then #done_read.
+    # Reads data into this data object.
     def read(io)
       io = BinData::IO.new(io) unless BinData::IO === io
 
@@ -152,19 +116,18 @@ module BinData
       self
     end
 
-    # Reads the value for this data from +io+.
     def do_read(io)
-      raise ArgumentError, "io must be a BinData::IO" unless BinData::IO === io
-
+      check_or_adjust_offset(io)
       clear
-      check_offset(io)
+      _do_read(io)
+    end
 
-      if eval_param(:onlyif)
-        _do_read(io)
-      end
+    def done_read
+      _done_read
     end
+    protected :do_read, :done_read
 
-    # Writes the value for this data to +io+ by calling #do_write.
+    # Writes the value for this data to +io+.
     def write(io)
       io = BinData::IO.new(io) unless BinData::IO === io
 
@@ -173,110 +136,110 @@ module BinData
       self
     end
 
-
-    # Writes the value for this data to +io+.
     def do_write(io)
-      raise ArgumentError, "io must be a BinData::IO" unless BinData::IO === io
-
-      if eval_param(:onlyif)
-        _do_write(io)
-      end
+      _do_write(io)
     end
+    protected :do_write
 
-    # Returns the number of bytes it will take to write this data by calling
-    # #do_num_bytes.
+    # Returns the number of bytes it will take to write this data.
     def num_bytes(what = nil)
       num = do_num_bytes(what)
       num.ceil
     end
 
-    # Returns the number of bytes it will take to write this data.
     def do_num_bytes(what = nil)
-      if eval_param(:onlyif)
-        _do_num_bytes(what)
-      else
-        0
-      end
+      _do_num_bytes(what)
+    end
+    protected :do_num_bytes
+
+    # Assigns the value of +val+ to this data object.  Note that +val+ will
+    # always be deep copied to ensure no aliasing problems can occur.
+    def assign(val)
+      _assign(val)
     end
 
     # Returns a snapshot of this data object.
-    # Returns nil if :onlyif is false
     def snapshot
-      if eval_param(:onlyif)
-        _snapshot
-      else
-        nil
-      end
+      _snapshot
     end
 
     # Returns the string representation of this data object.
-    def to_s
+    def to_binary_s
       io = StringIO.new
       write(io)
       io.rewind
       io.read
     end
 
-    # Return a human readable representation of this object.
+    # Return a human readable representation of this data object.
     def inspect
       snapshot.inspect
     end
 
-    # Returns the object this object represents.
-    def obj
-      self
+    # Return a string representing this data object.
+    def to_s
+      snapshot.to_s
     end
 
-    #---------------
-    private
+    # Returns a user friendly name of this object for debugging purposes.
+    def debug_name
+      if parent
+        parent.debug_name_of(self)
+      else
+        "obj"
+      end
+    end
 
-    # Returns the value of the evaluated parameter.  +key+ references a
-    # parameter from the +params+ hash used when creating the data object.
-    # +values+ contains data that may be accessed when evaluating +key+.
-    # Returns nil if +key+ does not refer to any parameter.
-    def eval_param(key, values = nil)
-      LazyEvaluator.eval(no_eval_param(key), self, values)
+    # Returns the offset of this object wrt to its most distant ancestor.
+    def offset
+      if parent
+        parent.offset_of(self)
+      else
+        0
+      end
     end
 
-    # Returns the parameter from the +params+ hash referenced by +key+.
-    # Use this method if you are sure the parameter is not to be evaluated.
-    # You most likely want #eval_param.
-    def no_eval_param(key)
-      @params.internal_parameters[key]
+    def ==(other)
+      # double dispatch
+      other == snapshot
     end
 
-    # Returns whether +key+ exists in the +params+ hash used when creating
-    # this data object.
-    def has_param?(key)
-      @params.internal_parameters.has_key?(key)
+    #---------------
+    private
+
+    def check_or_adjust_offset(io)
+      if has_parameter?(:check_offset)
+        check_offset(io)
+      elsif has_parameter?(:adjust_offset)
+        adjust_offset(io)
+      end
     end
 
-    # Checks that the current offset of +io+ is as expected.  This should
-    # be called from #do_read before performing the reading.
     def check_offset(io)
-      if has_param?(:check_offset)
-        actual_offset = io.offset
-        expected = eval_param(:check_offset, :offset => actual_offset)
-
-        if not expected
-          raise ValidityError, "offset not as expected"
-        elsif actual_offset != expected and expected != true
-          raise ValidityError, "offset is '#{actual_offset}' but " +
-                               "expected '#{expected}'"
-        end
-      elsif has_param?(:adjust_offset)
-        actual_offset = io.offset
-        expected = eval_param(:adjust_offset)
-        if actual_offset != expected
-          begin
-            seek = expected - actual_offset
-            io.seekbytes(seek)
-            warn "adjusting stream position by #{seek} bytes" if $VERBOSE
-          rescue
-            # could not seek so raise an error
-            raise ValidityError, "offset is '#{actual_offset}' but " +
-                                 "couldn't seek to expected '#{expected}'"
-          end
+      actual_offset = io.offset
+      expected = eval_parameter(:check_offset, :offset => actual_offset)
+
+      if not expected
+        raise ValidityError, "offset not as expected for #{debug_name}"
+      elsif actual_offset != expected and expected != true
+        raise ValidityError,
+              "offset is '#{actual_offset}' but " +
+              "expected '#{expected}' for #{debug_name}"
+      end
+    end
+
+    def adjust_offset(io)
+      actual_offset = io.offset
+      expected = eval_parameter(:adjust_offset)
+      if actual_offset != expected
+        begin
+          seek = expected - actual_offset
+          io.seekbytes(seek)
+          warn "adjusting stream position by #{seek} bytes" if $VERBOSE
+        rescue
+          raise ValidityError,
+                "offset is '#{actual_offset}' but couldn't seek to " +
+                "expected '#{expected}' for #{debug_name}"
         end
       end
     end
@@ -294,14 +257,15 @@ module BinData
       raise NotImplementedError
     end
 
-    # Returns whether this data object contains a single value.  Single
-    # value data objects respond to <tt>#value</tt> and <tt>#value=</tt>.
-    def single_value?
+    # Returns the debug name of +child+.  This only needs to be implemented
+    # by objects that contain child objects.
+    def debug_name_of(child)
       raise NotImplementedError
     end
 
-    # To be called after calling #do_read.
-    def done_read
+    # Returns the offset of +child+.  This only needs to be implemented
+    # by objects that contain child objects.
+    def offset_of(child)
       raise NotImplementedError
     end
 
@@ -310,13 +274,24 @@ module BinData
       raise NotImplementedError
     end
 
+    # Trigger function that is called after #do_read.
+    def _done_read
+      raise NotImplementedError
+    end
+
     # Writes the value for this data to +io+.
     def _do_write(io)
       raise NotImplementedError
     end
 
     # Returns the number of bytes it will take to write this data.
-    def _do_num_bytes
+    def _do_num_bytes(what)
+      raise NotImplementedError
+    end
+
+    # Assigns the value of +val+ to this data object.  Note that +val+ will
+    # always be deep copied to ensure no aliasing problems can occur.
+    def _assign(val)
       raise NotImplementedError
     end
 
@@ -326,8 +301,14 @@ module BinData
     end
 
     # Set visibility requirements of methods to implement
-    public :clear, :clear?, :single_value?, :done_read
-    private :_do_read, :_do_write, :_do_num_bytes, :_snapshot
+    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
     ###########################################################################

data/lib/bindata/{single.rb → base_primitive.rb}

@@ -1,10 +1,11 @@
 require 'bindata/base'
+require 'bindata/trace'
 
 module BinData
-  # A BinData::Single object is a container for a value that has a particular
-  # binary representation.  A value corresponds to a primitive type such as
-  # as integer, float or string.  Only one value can be contained by this
-  # object.  This value can be read from or written to an IO stream.
+  # A BinData::BasePrimitive object is a container for a value that has a
+  # particular binary representation.  A value corresponds to a primitive type
+  # such as as integer, float or string.  Only one value can be contained by
+  # this object.  This value can be read from or written to an IO stream.
   #
   #   require 'bindata'
   #
@@ -34,7 +35,7 @@ module BinData
   # [<tt>:initial_value</tt>] This is the initial value to use before one is
   #                           either #read or explicitly set with #value=.
   # [<tt>:value</tt>]         The object will always have this value.
-  #                           Explicitly calling #value= is prohibited when
+  #                           Calls to #value= are ignored when
   #                           using this param.  In the interval between
   #                           calls to #do_read and #done_read, #value
   #                           will return the value of the data read from the
@@ -45,90 +46,115 @@ module BinData
   #                           parameter.  A boolean return indicates success
   #                           or failure.  Any other return is compared to
   #                           the value just read in.
-  class Single < BinData::Base
-    # These are the parameters used by this class.
-    bindata_optional_parameters :initial_value, :value, :check_value
-    bindata_mutually_exclusive_parameters :initial_value, :value
+  class BasePrimitive < BinData::Base
+
+    optional_parameters :initial_value, :value, :check_value
+    mutually_exclusive_parameters :initial_value, :value
 
     def initialize(params = {}, parent = nil)
       super(params, parent)
-      clear
+
+      @value   = nil
+      @in_read = false
     end
 
-    # Resets the internal state to that of a newly created object.
     def clear
       @value = nil
       @in_read = false
     end
 
-    # Returns if the value of this data has been read or explicitly set.
     def clear?
       @value.nil?
     end
 
-    # Single objects are single_values
-    def single_value?
-      true
+    def value
+      # TODO: warn "#value is deprecated, use #snapshot instead"
+      snapshot
     end
 
-    # To be called after calling #do_read.
-    def done_read
-      @in_read = false
+    def value=(val)
+      # TODO: warn "#value= is deprecated, use #assign instead"
+      assign(val)
     end
 
-    # Returns the current value of this data.
-    def value
-      _value
+    def respond_to?(symbol, include_private=false)
+      super || value.respond_to?(symbol, include_private)
     end
 
-    # Sets the value of this data.
-    def value=(v)
-      # only allow modification if the value isn't predefined
-      unless has_param?(:value)
-        raise ArgumentError, "can't set a nil value" if v.nil?
-        @value = v
-
-        # Note that this doesn't do anything in ruby 1.8.x so ignore for now
-        # # explicitly return the output of #value as v may be different
-        # self.value
+    def method_missing(symbol, *args, &block)
+      if value.respond_to?(symbol)
+        value.__send__(symbol, *args, &block)
+      else
+        super
       end
     end
 
     #---------------
     private
 
-    # Reads the value for this data from +io+.
     def _do_read(io)
       @in_read = true
-      @value   = read_val(io)
-
-      # does the value meet expectations?
-      if has_param?(:check_value)
-        current_value = self.value
-        expected = eval_param(:check_value, :value => current_value)
-        if not expected
-          raise ValidityError, "value '#{current_value}' not as expected"
-        elsif current_value != expected and expected != true
-          raise ValidityError, "value is '#{current_value}' but " +
-                               "expected '#{expected}'"
+      @value   = read_and_return_value(io)
+
+      trace_value
+
+      if has_parameter?(:check_value)
+        check_value(value)
+      end
+    end
+
+    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}")
+      end
+    end
+
+    def check_value(current_value)
+      expected = eval_parameter(:check_value, :value => current_value)
+      if not expected
+        raise ValidityError,
+              "value '#{current_value}' not as expected for #{debug_name}"
+      elsif current_value != expected and expected != true
+        raise ValidityError,
+              "value is '#{current_value}' but " +
+              "expected '#{expected}' for #{debug_name}"
       end
     end
 
-    # Writes the value for this data to +io+.
+    def _done_read
+      @in_read = false
+    end
+
     def _do_write(io)
-      raise "can't write whilst reading" if @in_read
-      io.writebytes(val_to_str(_value))
+      raise "can't write whilst reading #{debug_name}" if @in_read
+      io.writebytes(value_to_binary_string(_value))
     end
 
-    # Returns the number of bytes it will take to write this data.
     def _do_num_bytes(ignored)
-      val_to_str(_value).length
+      value_to_binary_string(_value).length
+    end
+
+    def _assign(val)
+      raise ArgumentError, "can't set a nil value for #{debug_name}" if val.nil?
+
+      unless has_parameter?(:value)
+        raw_val = val.respond_to?(:snapshot) ? val.snapshot : val
+        @value = begin
+                   raw_val.dup
+                 rescue TypeError
+                   # can't dup Fixnums
+                   raw_val
+                 end
+      end
     end
 
-    # Returns a snapshot of this data object.
     def _snapshot
-      value
+      _value
     end
 
     # The unmodified value of this data object.  Note that #value calls this
@@ -143,13 +169,13 @@ module BinData
       #   5. clear?                       ->   sensible_default
       #   6. !clear?                      ->   @value
 
-      if not @in_read and (evaluated_value = eval_param(:value))
+      if not @in_read and has_parameter?(:value)
         # rule 1 above
-        evaluated_value
+        eval_parameter(:value)
       else
         # combining all other rules gives this simplified expression
-        @value || eval_param(:value) ||
-          eval_param(:initial_value) || sensible_default()
+        @value || eval_parameter(:value) ||
+          eval_parameter(:initial_value) || sensible_default()
       end
     end
 
@@ -157,12 +183,12 @@ module BinData
     # To be implemented by subclasses
 
     # Return the string representation that +val+ will take when written.
-    def val_to_str(val)
+    def value_to_binary_string(val)
       raise NotImplementedError
     end
 
     # Read a number of bytes from +io+ and return the value they represent.
-    def read_val(io)
+    def read_and_return_value(io)
       raise NotImplementedError
     end