bindata 0.8.1 → 0.9.0

data/lib/bindata/registry.rb

@@ -9,24 +9,29 @@ module BinData
       @registry = {}
     end
 
+    # Convert camelCase +name+ to underscore style.
+    def underscore_name(name)
+      name.to_s.sub(/.*::/, "").
+                gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+                gsub(/([a-z\d])([A-Z])/,'\1_\2').
+                tr("-", "_").
+                downcase
+    end
+
     # Registers the mapping of +name+ to +klass+.  +name+ is converted
     # from camelCase to underscore style.
     # Returns the converted name
     def register(name, klass)
       # convert camelCase name to underscore style
-      underscore_name = name.to_s.sub(/.*::/, "").
-                             gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
-                             gsub(/([a-z\d])([A-Z])/,'\1_\2').
-                             tr("-", "_").
-                             downcase
+      name = underscore_name(name)
 
       # warn if replacing an existing class
-      if $VERBOSE and (existing = @registry[underscore_name])
+      if $VERBOSE and (existing = @registry[name])
         warn "warning: replacing registered class #{existing} with #{klass}"
       end
 
-      @registry[underscore_name] = klass
-      underscore_name.dup
+      @registry[name] = klass
+      name.dup
     end
 
     # Returns the class matching a previously registered +name+.

data/lib/bindata/rest.rb

@@ -0,0 +1,41 @@
+require "bindata/single"
+
+module BinData
+  # Rest will consume the input stream from the current position to the end of
+  # the stream.  This will mainly be useful for debugging and developing.
+  #
+  #   require 'bindata'
+  #
+  #   class A < BinData::MultiValue
+  #     string :a, :read_length => 5
+  #     rest   :rest
+  #   end
+  #
+  #   obj = A.read("abcdefghij")
+  #   obj.a #=> "abcde"
+  #   obj.rest #=" "fghij"
+  #
+  class Rest < Single
+
+    # Register this class
+    register(self.name, self)
+
+    #---------------
+    private
+
+    # Return the string representation that +val+ will take when written.
+    def val_to_str(val)
+      val
+    end
+
+    # Read a number of bytes from +io+ and return the value they represent.
+    def read_val(io)
+      io.read
+    end
+
+    # Returns an empty string as default.
+    def sensible_default
+      ""
+    end
+  end
+end

data/lib/bindata/sanitize.rb

@@ -0,0 +1,36 @@
+require 'forwardable'
+
+module BinData
+  # A BinData object accepts arbitrary parameters.  This class ensures that
+  # the parameters have been sanitized, and categorizes them according to
+  # whether they are BinData::Base.accepted_parameters or are extra.
+  class SanitizedParameters
+    extend Forwardable
+
+    # Sanitize the given parameters.
+    def initialize(klass, params, *args)
+      params ||= {}
+      @hash = klass.sanitize_parameters(params, *args)
+      @accepted_parameters = {}
+      @extra_parameters = {}
+
+      # partition parameters into known and extra parameters
+      @hash.each do |k,v|
+        k = k.to_sym
+        if v.nil?
+          raise ArgumentError, "parameter :#{k} has nil value in #{klass}"
+        end
+
+        if klass.accepted_parameters.include?(k)
+          @accepted_parameters[k] = v
+        else
+          @extra_parameters[k] = v
+        end
+      end
+    end
+
+    attr_reader :accepted_parameters, :extra_parameters
+
+    def_delegators :@hash, :[], :has_key?, :include?, :keys
+  end
+end

data/lib/bindata/single.rb

@@ -6,6 +6,26 @@ module BinData
   # 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'
+  #
+  #   obj = BinData::Uint8.new(:initial_value => 42)
+  #   obj.value #=> 42
+  #   obj.value = 5
+  #   obj.value #=> 5
+  #   obj.clear
+  #   obj.value #=> 42
+  #
+  #   obj = BinData::Uint8.new(:value => 42)
+  #   obj.value #=> 42
+  #   obj.value = 5
+  #   obj.value #=> 42
+  #
+  #   obj = BinData::Uint8.new(:check_value => 3)
+  #   obj.read("\005") #=> BinData::ValidityError: value is '5' but expected '3'
+  #
+  #   obj = BinData::Uint8.new(:check_value => lambda { value < 5 })
+  #   obj.read("\007") #=> BinData::ValidityError: value not as expected
+  #
   # == Parameters
   #
   # Parameters may be provided at initialisation to control the behaviour of
@@ -28,15 +48,15 @@ module BinData
   class Single < Base
     # These are the parameters used by this class.
     optional_parameters :initial_value, :value, :check_value
+    mutually_exclusive_parameters :initial_value, :value
 
-    # Register the names of all subclasses of this class.
-    def self.inherited(subclass) #:nodoc:
-      register(subclass.name, subclass)
+    # Single objects don't contain fields so this returns an empty list.
+    def self.all_possible_field_names(sanitized_params)
+      []
     end
 
     def initialize(params = {}, env = nil)
       super(params, env)
-      ensure_mutual_exclusion(:initial_value, :value)
       clear
     end
 
@@ -90,6 +110,11 @@ module BinData
       value
     end
 
+    # Single objects are single_values
+    def single_value?
+      true
+    end
+
     # Single objects don't contain fields so this returns an empty list.
     def field_names
       []
@@ -149,7 +174,7 @@ module BinData
       str
     end
 
-=begin
+    ###########################################################################
     # To be implemented by subclasses
 
     # Return the string representation that +val+ will take when written.
@@ -168,6 +193,6 @@ module BinData
     end
 
     # To be implemented by subclasses
-=end
+    ###########################################################################
   end
 end

data/lib/bindata/single_value.rb

@@ -0,0 +1,203 @@
+require 'bindata/single'
+require 'bindata/struct'
+
+module BinData
+  # A SingleValue is a declarative way to define a new BinData data type.
+  # The data type must contain a single value only.  For new data types
+  # that contain multiple values see BinData::MultiValue.
+  #
+  # To define a new data type, set fields as if for MultiValue and add a
+  # #get and #set method to extract / convert the data between the fields
+  # and the #value of the object.
+  #
+  #    require 'bindata'
+  #
+  #    class PascalString < BinData::SingleValue
+  #      uint8  :len,  :value => lambda { data.length }
+  #      string :data, :read_length => :len
+  #    
+  #      def get
+  #        self.data
+  #      end
+  #    
+  #      def set(v)
+  #        self.data = v
+  #      end
+  #    end
+  #
+  #    ps = PascalString.new(:initial_value => "hello")
+  #    ps.to_s #=> "\005hello"
+  #    ps.read("\003abcde")
+  #    ps.value #=> "abc"
+  #
+  #    # Unsigned 24 bit big endian integer
+  #    class Uint24be < BinData::SingleValue
+  #      uint8 :byte1
+  #      uint8 :byte2
+  #      uint8 :byte3
+  #
+  #      def get
+  #        (self.byte1 << 16) | (self.byte2 << 8) | self.byte3
+  #      end
+  #
+  #      def set(v)
+  #        v = 0 if v < 0
+  #        v = 0xffffff if v > 0xffffff
+  #
+  #        self.byte1 = (v >> 16) & 0xff
+  #        self.byte2 = (v >>  8) & 0xff
+  #        self.byte3 =  v        & 0xff
+  #      end
+  #    end
+  #
+  #    u24 = Uint24be.new
+  #    u24.read("\x12\x34\x56")
+  #    "0x%x" % u24.value #=> 0x123456
+  #
+  # == Parameters
+  #
+  # SingleValue objects accept all the parameters that BinData::Single do.
+  #
+  class SingleValue < Single
+
+    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 all stored fields.  Should only be called by
+      # #sanitize_parameters
+      def fields
+        @fields || []
+      end
+
+      # Used to define fields for the internal 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
+        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 = self.endian || endian
+
+        hash = {}
+        hash[:fields] = self.fields
+
+        unless endian.nil?
+          hash[:endian] = endian
+        end
+        
+        params[:struct_params] = hash
+
+        super(params, endian)
+      end
+    end
+
+    # These are the parameters used by this class.
+    mandatory_parameter :struct_params
+
+    def initialize(params = {}, env = nil)
+      super(params, env)
+
+      @struct = BinData::Struct.new(param(:struct_params), create_env)
+    end
+
+    # Forward method calls to the internal struct.
+    def method_missing(symbol, *args, &block)
+      if @struct.respond_to?(symbol)
+        @struct.__send__(symbol, *args, &block)
+      else
+        super
+      end
+    end
+
+    #---------------
+    private
+
+    # Retrieve a sensible default from the internal struct.
+    def sensible_default
+      get
+    end
+
+    # Read data into the fields of the internal struct then return the value.
+    def read_val(io)
+      @struct.read(io)
+      get
+    end
+
+    # Sets +val+ into the fields of the internal struct then returns the
+    # string representation.
+    def val_to_str(val)
+      set(val)
+      @struct.to_s
+    end
+
+    ###########################################################################
+    # To be implemented by subclasses
+
+    # Extracts the value for this data object from the fields of the
+    # internal struct.
+    def get
+      raise NotImplementedError
+    end
+
+    # Sets the fields of the internal struct to represent +v+.
+    def set(v)
+      raise NotImplementedError
+    end
+
+    # To be implemented by subclasses
+    ###########################################################################
+  end
+end

data/lib/bindata/string.rb

@@ -4,6 +4,32 @@ module BinData
   # A String is a sequence of bytes.  This is the same as strings in Ruby.
   # The issue of character encoding is ignored by this class.
   #
+  #   require 'bindata'
+  #
+  #   data = "abcdefghij"
+  #
+  #   obj = BinData::String.new(:read_length => 5)
+  #   obj.read(data)
+  #   obj.value #=> "abcde"
+  #
+  #   obj = BinData::String.new(:length => 6)
+  #   obj.read(data)
+  #   obj.value #=> "abcdef"
+  #   obj.value = "abcdefghij"
+  #   obj.value #=> "abcdef"
+  #   obj.value = "abcd"
+  #   obj.value #=> "abcd\000\000"
+  #
+  #   obj = BinData::String.new(:length => 6, :trim_value => true)
+  #   obj.value = "abcd"
+  #   obj.value #=> "abcd"
+  #   obj.to_s #=> "abcd\000\000"
+  #
+  #   obj = BinData::String.new(:length => 6, :pad_char => 'A')
+  #   obj.value = "abcd"
+  #   obj.value #=> "abcdAA"
+  #   obj.to_s #=> "abcdAA"
+  #
   # == Parameters
   #
   # String objects accept all the params that BinData::Single
@@ -20,20 +46,41 @@ module BinData
   #                            from the end of the string.  The value will
   #                            not be trimmed when writing.
   class String < Single
+
+    # Register this class
+    register(self.name, self)
+
     # These are the parameters used by this class.
-    mandatory_parameters :pad_char
     optional_parameters  :read_length, :length, :trim_value
+    default_parameters   :pad_char => "\0"
+    mutually_exclusive_parameters :read_length, :length
+    mutually_exclusive_parameters :length, :value
+
+    class << self
+
+      # Returns a sanitized +params+ that is of the form expected
+      # by #initialize.
+      def sanitize_parameters(params, *args)
+        params = params.dup
 
-    def initialize(params = {}, env = nil)
-      super(cleaned_params(params), env)
+        # 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
 
-      # the only valid param combinations of length and value are:
-      #   :read_length and :value
-      #   :read_length and :initial_value
-      #   :length and :initial_value
-      ensure_mutual_exclusion(:initial_value, :value)
-      ensure_mutual_exclusion(:read_length, :length)
-      ensure_mutual_exclusion(:length, :value)
+        # 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
+        end
+
+        super(params, *args)
+      end
     end
 
     # Overrides value to return the value padded to the desired length or
@@ -67,27 +114,5 @@ module BinData
     def sensible_default
       ""
     end
-
-    # Returns a hash of cleaned +params+.  Cleaning means that param
-    # values are converted to a desired format.
-    def cleaned_params(params)
-      new_params = params.dup
-
-      # warn about deprecated param - remove before releasing 1.0
-      if params[:initial_length]
-        warn ":initial_length is deprecated. Replacing with :read_length"
-        new_params[:read_length] = params[:initial_length]
-      end
-
-      # set :pad_char to be a single length character string
-      ch = new_params[:pad_char] || 0
-      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
-      new_params[:pad_char] = ch
-
-      new_params
-    end
   end
 end