bindata 0.9.3 → 0.10.0

data/lib/bindata/rest.rb

@@ -1,4 +1,4 @@
-require "bindata/single"
+require "bindata/base_primitive"
 
 module BinData
   # Rest will consume the input stream from the current position to the end of
@@ -6,7 +6,7 @@ module BinData
   #
   #   require 'bindata'
   #
-  #   class A < BinData::MultiValue
+  #   class A < BinData::Record
   #     string :a, :read_length => 5
   #     rest   :rest
   #   end
@@ -15,25 +15,21 @@ module BinData
   #   obj.a #=> "abcde"
   #   obj.rest #=" "fghij"
   #
-  class Rest < BinData::Single
+  class Rest < BinData::BasePrimitive
 
-    # Register this class
     register(self.name, self)
 
     #---------------
     private
 
-    # Return the string representation that +val+ will take when written.
-    def val_to_str(val)
+    def value_to_binary_string(val)
       val
     end
 
-    # Read a number of bytes from +io+ and return the value they represent.
-    def read_val(io)
-      io.raw_io.read
+    def read_and_return_value(io)
+      io.read_all_bytes
     end
 
-    # Returns an empty string as default.
     def sensible_default
       ""
     end

data/lib/bindata/sanitize.rb

@@ -1,37 +1,29 @@
+require 'bindata/registry'
 require 'forwardable'
 
 module BinData
 
   # A BinData object accepts arbitrary parameters.  This class only contains
-  # parameters that have been sanitized, and categorizes them according to
-  # whether they are BinData::Base.internal_parameters or are extra.
+  # parameters that have been sanitized.
   class SanitizedParameters
     extend Forwardable
 
-    # Sanitize the given parameters.
-    def initialize(klass, params)
-      @hash = params
-      @internal_parameters = {}
-      @extra_parameters = {}
+    def initialize(the_class, params)
+      @parameters = {}
 
-      # partition parameters into known and extra parameters
-      @hash.each do |k,v|
+      params.each do |k,v|
         k = k.to_sym
         if v.nil?
-          raise ArgumentError, "parameter :#{k} has nil value in #{klass}"
+          raise ArgumentError, "parameter :#{k} has nil value in #{the_class}"
         end
 
-        if klass.internal_parameters.include?(k)
-          @internal_parameters[k] = v
-        else
-          @extra_parameters[k] = v
-        end
+        @parameters[k] = v
       end
     end
 
-    attr_reader :internal_parameters, :extra_parameters
+    attr_reader :parameters
 
-    def_delegators :@hash, :[], :has_key?, :include?, :keys
+    def_delegators :@parameters, :[], :has_key?, :include?, :keys
   end
 
   # The Sanitizer sanitizes the parameters that are passed when creating a
@@ -41,45 +33,21 @@ module BinData
   class Sanitizer
 
     class << self
-
-      # Sanitize +params+ for +obj+.
+      # Sanitize +params+ for +the_class+.
       # Returns sanitized parameters.
-      def sanitize(klass, params)
+      def sanitize(the_class, params)
         if SanitizedParameters === params
           params
         else
           sanitizer = self.new
-          sanitizer.sanitize_params(klass, params)
+          sanitizer.sanitized_params(the_class, params)
         end
       end
-
-      # Returns true if +type+ is registered.
-      def type_exists?(type, endian = nil)
-        lookup(type, endian) != nil
-      end
-
-      # Returns the class matching a previously registered +name+.
-      def lookup(name, endian)
-        name = name.to_s
-        klass = Registry.instance.lookup(name)
-        if klass.nil? and endian != nil
-          # lookup failed so attempt endian lookup
-          if /^u?int\d{1,3}$/ =~ name
-            new_name = name + ((endian == :little) ? "le" : "be")
-            klass = Registry.instance.lookup(new_name)
-          elsif ["float", "double"].include?(name)
-            new_name = name + ((endian == :little) ? "_le" : "_be")
-            klass = Registry.instance.lookup(new_name)
-          end
-        end
-        klass
-      end
     end
 
-    # Create a new Sanitizer.
     def initialize
-      @seen   = []
       @endian = nil
+      @seen   = []
     end
 
     # Executes the given block with +endian+ set as the current endian.
@@ -94,44 +62,61 @@ module BinData
       end
     end
 
-    # Converts +type+ into the appropriate class.
-    def lookup_klass(type)
-      klass = self.class.lookup(type, @endian)
-      raise TypeError, "unknown type '#{type}'" if klass.nil?
-      klass
+    def lookup_class(type)
+      registered_class = RegisteredClasses.lookup(type, @endian)
+      if registered_class.nil?
+        raise TypeError, "unknown type '#{type}'"
+      end
+      registered_class
     end
 
-    # Sanitizes +params+ for +klass+.
-    # Returns +sanitized_params+.
-    def sanitize_params(klass, params)
+    def sanitized_params(the_class, params)
       new_params = params.nil? ? {} : params.dup
 
-      if klass.recursive? and @seen.include?(klass)
-        # This klass is defined recursively.  Remember the current endian
-        # and delay sanitizing the parameters until later.
-        new_params[:endian] = @endian if can_store_endian?(klass, new_params)
-        ret_val = new_params
+      if can_sanitize_parameters?(the_class)
+        get_sanitized_params(the_class, new_params)
       else
-        @seen.push(klass)
+        store_current_endian!(the_class, new_params)
+        new_params
+      end
+    end
 
-        # Sanitize new_params.  This may recursively call this method again.
-        klass.sanitize_parameters!(self, new_params)
-        ret_val = SanitizedParameters.new(klass, new_params)
+    #---------------
+    private
+
+    def can_sanitize_parameters?(the_class)
+      not need_to_delay_sanitizing?(the_class)
+    end
+
+    def need_to_delay_sanitizing?(the_class)
+      the_class.recursive? and @seen.include?(the_class)
+    end
 
-        @seen.pop
+    def get_sanitized_params(the_class, params)
+      result = nil
+      with_class_to_sanitize(the_class) do
+        the_class.sanitize_parameters!(self, params)
+        result = SanitizedParameters.new(the_class, params)
       end
+      result
+    end
 
-      ret_val
+    def with_class_to_sanitize(the_class, &block)
+      @seen.push(the_class)
+      yield
+      @seen.pop
     end
 
-    #---------------
-    private
+    def store_current_endian!(the_class, params)
+      if can_store_endian?(the_class, params)
+        params[:endian] = @endian 
+      end
+    end
 
-    # Can we store the current endian for later?
-    def can_store_endian?(klass, params)
-      (@endian != nil and klass.internal_parameters.include?(:endian) and
+    def can_store_endian?(the_class, params)
+      (@endian != nil and 
+       the_class.accepted_internal_parameters.include?(:endian) and
        not params.has_key?(:endian))
     end
   end
 end
-

data/lib/bindata/string.rb

@@ -1,4 +1,4 @@
-require "bindata/single"
+require "bindata/base_primitive"
 
 module BinData
   # A String is a sequence of bytes.  This is the same as strings in Ruby.
@@ -23,16 +23,16 @@ module BinData
   #   obj = BinData::String.new(:length => 6, :trim_value => true)
   #   obj.value = "abcd"
   #   obj.value #=> "abcd"
-  #   obj.to_s #=> "abcd\000\000"
+  #   obj.to_binary_s #=> "abcd\000\000"
   #
   #   obj = BinData::String.new(:length => 6, :pad_char => 'A')
   #   obj.value = "abcd"
   #   obj.value #=> "abcdAA"
-  #   obj.to_s #=> "abcdAA"
+  #   obj.to_binary_s #=> "abcdAA"
   #
   # == Parameters
   #
-  # String objects accept all the params that BinData::Single
+  # String objects accept all the params that BinData::BasePrimitive
   # does, as well as the following:
   #
   # <tt>:read_length</tt>::    The length to use when reading a value.
@@ -41,75 +41,93 @@ module BinData
   # <tt>:pad_char</tt>::       The character to use when padding a string to a
   #                            set length.  Valid values are Integers and
   #                            Strings of length 1.  "\0" is the default.
-  # <tt>:trim_value</tt>::     Boolean, default false.  If set, #value will
+  # <tt>:trim_padding</tt>::   Boolean, default false.  If set, #value will
   #                            return the value with all pad_chars trimmed
   #                            from the end of the string.  The value will
   #                            not be trimmed when writing.
-  class String < BinData::Single
+  class String < BinData::BasePrimitive
 
-    # Register this class
     register(self.name, self)
 
-    # These are the parameters used by this class.
-    bindata_optional_parameters :read_length, :length, :trim_value
-    bindata_default_parameters  :pad_char => "\0"
-    bindata_mutually_exclusive_parameters :read_length, :length
-    bindata_mutually_exclusive_parameters :length, :value
+    optional_parameters :read_length, :length, :trim_padding
+    default_parameters  :pad_char => "\0"
+    mutually_exclusive_parameters :read_length, :length
+    mutually_exclusive_parameters :length, :value
 
     class << self
 
-      # Ensures that +params+ is of the form expected by #initialize.
+      def deprecate!(params, old_key, new_key)
+        if params.has_key?(old_key)
+          warn ":#{old_key} is deprecated. Replacing with :#{new_key}"
+          params[new_key] = params.delete(old_key)
+        end
+      end
+
       def sanitize_parameters!(sanitizer, params)
         # warn about deprecated param - remove before releasing 1.0
-        if params[:initial_length]
-          warn ":initial_length is deprecated. Replacing with :read_length"
-          params[:read_length] = params.delete(:initial_length)
-        end
+        deprecate!(params, :trim_value, :trim_padding)
+
+        warn_replacement_parameter(params, :initial_length, :read_length)
 
-        # set :pad_char to be a single length character string
         if params.has_key?(:pad_char)
           ch = params[:pad_char]
-          ch = ch.respond_to?(:chr) ? ch.chr : ch.to_s
-          if ch.length > 1
-            raise ArgumentError, ":pad_char must not contain more than 1 char"
-          end
-          params[:pad_char] = ch
+          params[:pad_char] = sanitized_pad_char(ch)
         end
 
         super(sanitizer, params)
       end
-    end
 
-    # Overrides value to return the value padded to the desired length or
-    # trimmed as required.
-    def value
-      v = val_to_str(_value)
-      if no_eval_param(:trim_value) == true
-        v.sub!(/#{eval_param(:pad_char)}*$/, "")
+      #-------------
+      private
+
+      def sanitized_pad_char(ch)
+        result = ch.respond_to?(:chr) ? ch.chr : ch.to_s
+        if result.length > 1
+          raise ArgumentError, ":pad_char must not contain more than 1 char"
+        end
+        result
       end
-      v
     end
 
     #---------------
     private
 
-    # Returns +val+ ensuring that it is padded to the desired length.
-    def val_to_str(val)
-      # trim val if necessary
-      len = eval_param(:length) || val.length
-      str = val.slice(0, len)
+    def _snapshot
+      # override to ensure length and optionally trim padding
+      result = super
+      if has_parameter?(:length)
+        result = truncate_or_pad_to_length(result)
+      end
+      if get_parameter(:trim_padding) == true
+        result = trim_padding(result)
+      end
+      result
+    end
+
+    def truncate_or_pad_to_length(str)
+      len = eval_parameter(:length) || str.length
+      if str.length == len
+        str
+      elsif str.length > len
+        str.slice(0, len)
+      else
+        str + (eval_parameter(:pad_char) * (len - str.length))
+      end
+    end
+
+    def trim_padding(str)
+      str.sub(/#{eval_parameter(:pad_char)}*$/, "")
+    end
 
-      # then pad to length if str is short
-      str << (eval_param(:pad_char) * (len - str.length))
+    def value_to_binary_string(val)
+      truncate_or_pad_to_length(val)
     end
 
-    # Read a number of bytes from +io+ and return the value they represent.
-    def read_val(io)
-      len = eval_param(:read_length) || eval_param(:length) || 0
+    def read_and_return_value(io)
+      len = eval_parameter(:read_length) || eval_parameter(:length) || 0
       io.readbytes(len)
     end
 
-    # Returns an empty string as default.
     def sensible_default
       ""
     end

data/lib/bindata/stringz.rb

@@ -1,4 +1,4 @@
-require "bindata/single"
+require "bindata/base_primitive"
 
 module BinData
   # A BinData::Stringz object is a container for a zero ("\0") terminated
@@ -16,42 +16,36 @@ module BinData
   #   obj.snapshot #=> "abcd"
   #   obj.value #=> "abcd"
   #   obj.num_bytes #=> 5
-  #   obj.to_s #=> "abcd\000"
+  #   obj.to_binary_s #=> "abcd\000"
   #
   # == Parameters
   #
-  # Stringz objects accept all the params that BinData::Single
+  # Stringz objects accept all the params that BinData::BasePrimitive
   # does, as well as the following:
   #
   # <tt>:max_length</tt>:: The maximum length of the string including the zero
   #                        byte.
-  class Stringz < BinData::Single
+  class Stringz < BinData::BasePrimitive
 
-    # Register this class
     register(self.name, self)
 
-    # These are the parameters used by this class.
-    bindata_optional_parameters :max_length
-
-    # Overrides value to return the value of this data excluding the trailing
-    # zero byte.
-    def value
-      v = super
-      val_to_str(v).chomp("\0")
-    end
+    optional_parameters :max_length
 
     #---------------
     private
 
-    # Returns +val+ ensuring it is zero terminated and no longer
-    # than <tt>:max_length</tt> bytes.
-    def val_to_str(val)
-      zero_terminate(val, eval_param(:max_length))
+    def _snapshot
+      # override to always remove trailing zero bytes
+      result = super
+      trim_and_zero_terminate(result).chomp("\0")
+    end
+
+    def value_to_binary_string(val)
+      trim_and_zero_terminate(val)
     end
 
-    # Read a number of bytes from +io+ and return the value they represent.
-    def read_val(io)
-      max_length = eval_param(:max_length)
+    def read_and_return_value(io)
+      max_length = eval_parameter(:max_length)
       str = ""
       i = 0
       ch = nil
@@ -63,24 +57,25 @@ module BinData
         i += 1
       end
 
-      zero_terminate(str, max_length)
+      trim_and_zero_terminate(str)
     end
 
-    # Returns an empty string as default.
     def sensible_default
       ""
     end
 
-    # Returns +str+ after it has been zero terminated.  The returned string
-    # will not be longer than +max_length+.
-    def zero_terminate(str, max_length = nil)
-      # str must not be empty
-      result = (str == "") ? "\0" : str
+    def trim_and_zero_terminate(str)
+      str = truncate_at_first_zero_byte(str)
+      str = trim_to(str, eval_parameter(:max_length))
+      append_zero_byte_if_needed(str)
+    end
 
-      # remove anything after the first \0
-      result = result.sub(/([^\0]*\0).*/, '\1')
+    def truncate_at_first_zero_byte(str)
+      str.sub(/([^\0]*\0).*/, '\1')
+    end
 
-      # trim string to be no longer than max_length including zero byte
+    def trim_to(str, max_length = nil)
+      result = str
       if max_length
         max_length = 1 if max_length < 1
         result = result[0, max_length]
@@ -88,11 +83,15 @@ module BinData
           result[-1, 1] = "\0"
         end
       end
-
-      # ensure last byte in the string is a zero byte
-      result << "\0" if result[-1, 1] != "\0"
-
       result
     end
+
+    def append_zero_byte_if_needed(str)
+      if str.length == 0 or str[-1, 1] != "\0"
+        str + "\0"
+      else
+        str
+      end
+    end
   end
 end