bindata 1.5.1 → 1.6.0

data/lib/bindata/base_primitive.rb

@@ -31,49 +31,46 @@ module BinData
   # Parameters may be provided at initialisation to control the behaviour of
   # an object.  These params include those for BinData::Base as well as:
   #
-  # [<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.
-  #                           Calls to #value= are ignored when
-  #                           using this param.  While reading, #value
-  #                           will return the value of the data read from the
-  #                           IO, not the result of the <tt>:value</tt> param.
-  # [<tt>:check_value</tt>]   Raise an error unless the value read in meets
-  #                           this criteria.  The variable +value+ is made
-  #                           available to any lambda assigned to this
-  #                           parameter.  A boolean return indicates success
-  #                           or failure.  Any other return is compared to
-  #                           the value just read in.
+  # [<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.
+  #                            Calls to #value= are ignored when
+  #                            using this param.  While reading, #value
+  #                            will return the value of the data read from the
+  #                            IO, not the result of the <tt>:value</tt> param.
+  # [<tt>:assert</tt>]         Raise an error unless the value read or assigned
+  #                            meets this criteria.  The variable +value+ is
+  #                            made available to any lambda assigned to this
+  #                            parameter.  A boolean return indicates success
+  #                            or failure.  Any other return is compared to
+  #                            the value just read in.
+  # [<tt>:asserted_value</tt>] Equavalent to <tt>:assert</tt> and <tt>:value</tt>.
+  #
   class BasePrimitive < BinData::Base
     unregister_self
 
-    optional_parameters :initial_value, :value, :check_value
+    optional_parameters :initial_value, :value, :check_value, :assert, :asserted_value
     mutually_exclusive_parameters :initial_value, :value
+    mutually_exclusive_parameters :asserted_value, :value, :assert
+    mutually_exclusive_parameters :check_value, :assert
+    mutually_exclusive_parameters :check_value, :asserted_value
 
     def initialize_shared_instance
-      if has_parameter?(:check_value)
-        class << self
-          alias_method :do_read_without_check_value, :do_read
-          alias_method :do_read, :do_read_with_check_value
-        end
-      end
-      if has_parameter?(:value)
-        class << self
-          alias_method :_value, :_value_with_value
-        end
-      end
-      if has_parameter?(:initial_value)
-        class << self
-          alias_method :_value, :_value_with_initial_value
-        end
+      if has_parameter?(:check_value) and has_parameter?(:value)
+        warn ":check_value has been deprecated.  Consider using :asserted_value instead of :check_value and :value in #{self.class}."
+      elsif has_parameter?(:check_value)
+        warn ":check_value has been deprecated.  Use :assert instead in #{self.class}."
       end
-    end
 
-    def initialize_instance
-      @value = nil
+      extend InitialValuePlugin  if has_parameter?(:initial_value)
+      extend ValuePlugin         if has_parameter?(:value)
+      extend CheckValuePlugin    if has_parameter?(:check_value)
+      extend AssertPlugin        if has_parameter?(:assert)
+      extend AssertedValuePlugin if has_parameter?(:asserted_value)
+      super
     end
 
-    def clear #:nodoc:
+    def initialize_instance
       @value = nil
     end
 
@@ -84,15 +81,13 @@ module BinData
     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
+      raw_val = val.respond_to?(:snapshot) ? val.snapshot : val
+      @value = begin
+                 raw_val.dup
+               rescue TypeError
+                 # can't dup Fixnums
+                 raw_val
+               end
     end
 
     def snapshot
@@ -133,12 +128,6 @@ module BinData
 
     def do_read(io) #:nodoc:
       @value = read_and_return_value(io)
-      hook_after_do_read
-    end
-
-    def do_read_with_check_value(io) #:nodoc:
-      do_read_without_check_value(io)
-      check_value(snapshot)
     end
 
     def do_write(io) #:nodoc:
@@ -152,42 +141,108 @@ module BinData
     #---------------
     private
 
-    def hook_after_do_read; 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
-
     # The unmodified value of this data object.  Note that #snapshot calls this
     # method.  This indirection is so that #snapshot can be overridden in
     # subclasses to modify the presentation value.
-    #
-    # Table of possible preconditions and expected outcome
-    #   1. :value and !reading?         ->   :value
-    #   2. :value and reading?          ->   @value
-    #   3. :initial_value and clear?    ->   :initial_value
-    #   4. :initial_value and !clear?   ->   @value
-    #   5. clear?                       ->   sensible_default
-    #   6. !clear?                      ->   @value
-
     def _value
       @value != nil ? @value : sensible_default()
     end
 
-    def _value_with_value #:nodoc:
-      reading?      ? @value : eval_parameter(:value)
+    # Logic for the :value parameter
+    module ValuePlugin
+      def assign(val)
+        # Ignored
+      end
+
+      def _value
+        reading? ? @value : eval_parameter(:value)
+      end
+    end
+
+    # Logic for the :initial_value parameter
+    module InitialValuePlugin
+      def _value
+        @value != nil ? @value : eval_parameter(:initial_value)
+      end
     end
 
-    def _value_with_initial_value #:nodoc:
-      @value != nil ? @value : eval_parameter(:initial_value)
+    # Logic for the :check_value parameter
+    module CheckValuePlugin
+      def do_read(io) #:nodoc:
+        super(io)
+        check_value(snapshot)
+      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
+    end
+
+    # Logic for the :assert parameter
+    module AssertPlugin
+      def assign(val)
+        super(val)
+        assert!
+      end
+
+      def do_read(io) #:nodoc:
+        super(io)
+        assert!
+      end
+
+      def assert!
+        current_value = snapshot
+        expected = eval_parameter(:assert, :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
+    end
+
+    # Logic for the :asserted_value parameter
+    module AssertedValuePlugin
+      def assign(val)
+        assert_value(val)
+        super(val)
+      end
+
+      def _value
+        reading? ? @value : eval_parameter(:asserted_value)
+      end
+
+      def do_read(io) #:nodoc:
+        super(io)
+        assert!
+      end
+
+      def assert!
+        assert_value(snapshot)
+      end
+
+      def assert_value(current_value)
+        expected = eval_parameter(:asserted_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
     end
 
     ###########################################################################

data/lib/bindata/bits.rb

@@ -64,24 +64,22 @@ module BinData
   end
 
   # Create classes on demand
-  class << self
-    alias_method :const_missing_without_bits, :const_missing
-    def const_missing_with_bits(name)
-      name = name.to_s
+  module BitFieldFactory
+    def const_missing(name)
       mappings = {
         /^Bit(\d+)$/ => :big,
         /^Bit(\d+)le$/ => :little
       }
 
       mappings.each_pair do |regex, endian|
-        if regex =~ name
+        if regex =~ name.to_s
           nbits = $1.to_i
           return BitField.define_class(nbits, endian)
         end
       end
 
-      const_missing_without_bits(name)
+      super(name)
     end
-    alias_method :const_missing, :const_missing_with_bits
   end
+  BinData.extend BitFieldFactory
 end

data/lib/bindata/choice.rb

@@ -107,11 +107,8 @@ module BinData
     end
 
     def initialize_shared_instance
-      if eval_parameter(:copy_on_change) == true
-        class << self
-          alias_method :hook_after_current_choice, :copy_previous_value
-        end
-      end
+      extend CopyOnChangePlugin if eval_parameter(:copy_on_change) == true
+      super
     end
 
     def initialize_instance
@@ -119,13 +116,13 @@ module BinData
       @last_selection = nil
     end
 
-    # A convenience method that returns the current selection.
+    # Returns the current selection.
     def selection
-      eval_parameter(:selection)
-    end
-
-    def clear #:nodoc:
-      initialize_instance
+      selection = eval_parameter(:selection)
+      if selection.nil?
+        raise IndexError, ":selection returned nil for #{debug_name}"
+      end
+      selection
     end
 
     def clear? #:nodoc:
@@ -145,7 +142,7 @@ module BinData
     end
 
     def safe_respond_to?(symbol, include_private = false) #:nodoc:
-      orig_respond_to?(symbol, include_private)
+      base_respond_to?(symbol, include_private)
     end
 
     def method_missing(symbol, *args, &block) #:nodoc:
@@ -153,7 +150,6 @@ module BinData
     end
 
     def do_read(io) #:nodoc:
-      hook_before_do_read
       current_choice.do_read(io)
     end
 
@@ -168,23 +164,9 @@ module BinData
     #---------------
     private
 
-    def hook_before_do_read; end
-    def hook_after_current_choice(*args); end
-
     def current_choice
-      selection = eval_parameter(:selection)
-      if selection.nil?
-        raise IndexError, ":selection returned nil for #{debug_name}"
-      end
-
-      obj = get_or_instantiate_choice(selection)
-      hook_after_current_choice(selection, obj)
-
-      obj
-    end
-
-    def get_or_instantiate_choice(selection)
-      @choices[selection] ||= instantiate_choice(selection)
+      current_selection = selection
+      @choices[current_selection] ||= instantiate_choice(current_selection)
     end
 
     def instantiate_choice(selection)
@@ -194,11 +176,21 @@ module BinData
       end
       prototype.instantiate(nil, self)
     end
+  end
+
+  # Logic for the :copy_on_change parameter
+  module CopyOnChangePlugin
+    def current_choice
+      obj = super
+      copy_previous_value(obj)
+      obj
+    end
 
-    def copy_previous_value(selection, obj)
-      prev = get_previous_choice(selection)
+    def copy_previous_value(obj)
+      current_selection = selection
+      prev = get_previous_choice(current_selection)
       obj.assign(prev) unless prev.nil?
-      remember_current_selection(selection)
+      remember_current_selection(current_selection)
     end
 
     def get_previous_choice(selection)

data/lib/bindata/dsl.rb

@@ -53,12 +53,7 @@ module BinData
 
       def hide(*args)
         if option?(:hidden_fields)
-          hidden = args.collect do |name|
-                     unless Symbol === name
-                       warn "Hidden field '#{name}' should be provided as a symbol.  Using strings is deprecated"
-                     end
-                     name.to_sym
-                   end
+          hidden = args.collect { |name| name.to_sym }
 
           unless defined? @hide
             @hide = parent_attribute(:hide, []).dup

data/lib/bindata/framework.rb

@@ -0,0 +1,81 @@
+module BinData
+  # Error raised when unexpected results occur when reading data from IO.
+  class ValidityError < StandardError ; end
+
+  # All methods provided by the framework are to be implemented or overridden 
+  # by subclasses of BinData::Base.
+  module Framework
+    def self.included(base) #:nodoc:
+      base.extend ClassMethods
+    end
+
+    module ClassMethods #:nodoc:
+      # Performs sanity checks on the given parameters.  This method converts
+      # the parameters to the form expected by this data object.
+      def sanitize_parameters!(parameters)
+      end
+    end
+
+    # Initializes the state of the object.  All instance variables that
+    # are used by the object must be initialized here.
+    def initialize_instance
+    end
+
+    # Initialises state that is shared by objects with the same parameters.
+    #
+    # This should only be used when optimising for performance.  Instance
+    # variables set here, and changes to the singleton class will be shared
+    # between all objects that are initialized with the same parameters.
+    # This method is called only once for a particular set of parameters.
+    def initialize_shared_instance
+    end
+
+    # Returns true if the object has not been changed since creation.
+    def clear?
+      raise NotImplementedError
+    end
+
+    # Assigns the value of +val+ to this data object.  Note that +val+ must
+    # always be deep copied to ensure no aliasing problems can occur.
+    def assign(val)
+      raise NotImplementedError
+    end
+
+    # Returns a snapshot of this data object.
+    def snapshot
+      raise NotImplementedError
+    end
+
+    # Returns the debug name of +child+.  This only needs to be implemented
+    # by objects that contain child objects.
+    def debug_name_of(child) #:nodoc:
+      debug_name
+    end
+
+    # Returns the offset of +child+.  This only needs to be implemented
+    # by objects that contain child objects.
+    def offset_of(child) #:nodoc:
+      0
+    end
+
+    # Reads the data for this data object from +io+.
+    def do_read(io) #:nodoc:
+      raise NotImplementedError
+    end
+
+    # Writes the value for this data to +io+.
+    def do_write(io) #:nodoc:
+      raise NotImplementedError
+    end
+
+    # Returns the number of bytes it will take to write this data.
+    def do_num_bytes #:nodoc:
+      raise NotImplementedError
+    end
+
+    # Set visibility requirements of methods to implement
+    public :clear?, :assign, :snapshot, :debug_name_of, :offset_of
+    protected :initialize_instance, :initialize_shared_instance
+    protected :do_read, :do_write, :do_num_bytes
+  end
+end