bindata 0.5.0

data/lib/bindata/choice.rb

@@ -0,0 +1,120 @@
+require 'bindata/base'
+
+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}] ]
+  #   a = BinData::Choice.new(:choices => choices, :selection => 1)
+  #   a.value # => 5
+  #
+  # == 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
+
+    # Register this class
+    register(self.name, self)
+
+    # 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 = self.class.lookup(choice_type)
+        if klass.nil?
+          raise TypeError, "unknown type '#{choice_type.id2name}' for #{self}"
+        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
+
+    # To be called after calling #do_read.
+    def done_read
+      the_choice.done_read
+    end
+
+    # Writes the value of the selected data object to +io+.
+    def _write(io)
+      the_choice.write(io)
+    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
+
+    # Returns a snapshot of the selected data object.
+    def snapshot
+      the_choice.snapshot
+    end
+
+    # Returns a list of the names of all fields of the selected data object.
+    def field_names
+      the_choice.field_names
+    end
+
+    # Returns the data object that stores values for +name+.
+    def find_obj_for_name(name)
+      field_names.include?(name) ? the_choice.find_obj_for_name(name) : nil
+    end
+
+    # Override to include selected data object.
+    def respond_to?(symbol, include_private = false)
+      super || the_choice.respond_to?(symbol, include_private)
+    end
+
+    def method_missing(symbol, *args)
+      if the_choice.respond_to?(symbol)
+        the_choice.__send__(symbol, *args)
+      else
+        super
+      end
+    end
+
+    #---------------
+    private
+
+    # 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"
+      end
+      @choices[index]
+    end
+  end
+end

data/lib/bindata/int.rb

@@ -0,0 +1,171 @@
+require 'bindata/single'
+
+module BinData
+  # Provides a number of classes that contain an integer.  The integer
+  # is defined by endian, signedness and number of bytes.
+
+  module BaseUint #:nodoc: all
+
+    def value=(val)
+      super(clamp(val))
+    end
+
+    #---------------
+    private
+
+    def sensible_default
+      0
+    end
+
+    def val_to_str(val)
+      _val_to_str(clamp(val))
+    end
+
+    # Clamps +val+ to the range 0 .. max_val
+    def clamp(val)
+      v = val
+      nbytes = val_num_bytes(0)
+      min = 0
+      max = (1 << (nbytes * 8)) - 1
+      val = min if val < min
+      val = max if val > max
+      val
+    end
+  end
+
+  module BaseInt #:nodoc: all
+    def uint2int(val)
+      nbytes = val_num_bytes(0)
+      mask = (1 << (nbytes * 8 - 1)) - 1
+      msb = (val >> (nbytes * 8 - 1)) & 0x1
+      (msb == 1) ? -(((~val) & mask) + 1) : val & mask
+    end
+
+    def int2uint(val)
+      nbytes = val_num_bytes(0)
+      mask = (1 << (nbytes * 8)) - 1
+      val & mask
+    end
+
+    def value=(val)
+      super(clamp(val))
+    end
+
+    #---------------
+    private
+
+    def sensible_default
+      0
+    end
+
+    def val_to_str(val)
+      _val_to_str(int2uint(clamp(val)))
+    end
+
+    def read_val(io)
+      uint2int(_read_val(io))
+    end
+
+    # Clamps +val+ to the range min_val .. max_val, where min and max
+    # are the largest representable integers.
+    def clamp(val)
+      nbytes = val_num_bytes(0)
+      max = (1 << (nbytes * 8 - 1)) - 1
+      min = -(max + 1)
+      val = min if val < min
+      val = max if val > max
+      val
+    end
+  end
+
+
+  # Unsigned 1 byte integer.
+  class Uint8 < Single
+    include BaseUint
+    private
+    def val_num_bytes(val) 1 end
+    def read_val(io)       readbytes(io,1)[0] end
+    def _val_to_str(val)   val.chr end
+  end
+
+  # Unsigned 2 byte little endian integer.
+  class Uint16le < Single
+    include BaseUint
+    private
+    def val_num_bytes(val) 2 end
+    def read_val(io)       readbytes(io,2).unpack("v")[0] end
+    def _val_to_str(val)   [val].pack("v") end
+  end
+
+  # Unsigned 2 byte big endian integer.
+  class Uint16be < Single
+    include BaseUint
+    private
+    def val_num_bytes(val) 2 end
+    def read_val(io)       readbytes(io,2).unpack("n")[0] end
+    def _val_to_str(val)   [val].pack("n") end
+  end
+
+  # Unsigned 4 byte little endian integer.
+  class Uint32le < Single
+    include BaseUint
+    private
+    def val_num_bytes(val) 4 end
+    def read_val(io)       readbytes(io,4).unpack("V")[0] end
+    def _val_to_str(val)   [val].pack("V") end
+  end
+
+  # Unsigned 4 byte big endian integer.
+  class Uint32be < Single
+    include BaseUint
+    private
+    def val_num_bytes(val) 4 end
+    def read_val(io)       readbytes(io,4).unpack("N")[0] end
+    def _val_to_str(val)   [val].pack("N") end
+  end
+
+  # Signed 1 byte integer.
+  class Int8 < Single
+    include BaseInt
+    private
+    def val_num_bytes(val) 1 end
+    def _read_val(io)      readbytes(io,1)[0] end
+    def _val_to_str(val)   val.chr end
+  end
+
+  # Signed 2 byte little endian integer.
+  class Int16le < Single
+    include BaseInt
+    private
+    def val_num_bytes(val) 2 end
+    def _read_val(io)      readbytes(io,2).unpack("v")[0] end
+    def _val_to_str(val)   [val].pack("v") end
+  end
+
+  # Signed 2 byte big endian integer.
+  class Int16be < Single
+    include BaseInt
+    private
+    def val_num_bytes(val) 2 end
+    def _read_val(io)      readbytes(io,2).unpack("n")[0] end
+    def _val_to_str(val)   [val].pack("n") end
+  end
+
+  # Signed 4 byte little endian integer.
+  class Int32le < Single
+    include BaseInt
+    private
+    def val_num_bytes(val) 4 end
+    def _read_val(io)      readbytes(io,4).unpack("V")[0] end
+    def _val_to_str(val)   [val].pack("V") end
+  end
+
+  # Signed 4 byte big endian integer.
+  class Int32be < Single
+    include BaseInt
+    private
+    def val_num_bytes(val) 4 end
+    def _read_val(io)      readbytes(io,4).unpack("N")[0] end
+    def _val_to_str(val)   [val].pack("N") end
+  end
+end

data/lib/bindata/lazy.rb

@@ -0,0 +1,71 @@
+module BinData
+  # The enviroment in which a lazily evaluated lamba is called.  These lambdas
+  # are those that are passed to data objects as parameters.  Each lambda
+  # has access to the following:
+  #
+  # parent:: the environment of the parent data object
+  # params:: any extra parameters that have been passed to the data object.
+  #          The value of a parameter is either a lambda, a symbol or a
+  #          literal value (such as a Fixnum).
+  # value::  the value of the data object if it is single
+  # index::  the index of the data object if it is in an array
+  # offset:: the current offset of the IO object when reading
+  #
+  # Unknown methods are resolved in the context of the parent data object,
+  # first as keys in the extra parameters, and secondly as methods in the
+  # parent data object.  This makes the lambda easier to read as we just write
+  # <tt>field</tt> instead of <tt>obj.field</tt>.
+  class LazyEvalEnv
+    # Creates a new environment.  +parent+ is the environment of the
+    # parent data object.
+    def initialize(parent = nil)
+      @parent = parent
+    end
+    attr_reader :parent
+    attr_accessor :data_object, :params, :index, :offset
+
+    # only accessible by another LazyEvalEnv
+    protected :data_object
+
+    # TODO: offset_of needs to be better thought out
+    def offset_of(sym)
+      if @parent and @parent.data_object and
+              @parent.data_object.respond_to?(:offset_of)
+        @parent.data_object.offset_of(sym)
+      else
+        nil
+      end
+    end
+
+    # Returns the value of the data object wrapped by this environment.
+    def value
+      @data_object.respond_to?(:value) ? @data_object.value : nil
+    end
+
+    # Evaluates +obj+ in the context of this environment.  Evaluation
+    # recurses until it yields a value that is not a symbol or lambda.
+    def lazy_eval(obj)
+      if obj.is_a? Symbol
+        # treat :foo as lambda { foo }
+        lazy_eval(__send__(obj))
+      elsif obj.respond_to? :arity
+        instance_eval(&obj)
+      else
+        obj
+      end
+    end
+
+    def method_missing(symbol, *args)
+      if @parent and @parent.params and @parent.params.has_key?(symbol)
+        # is there a param with this name?
+        @parent.lazy_eval(@parent.params[symbol])
+      elsif @parent and @parent.data_object and
+              @parent.data_object.respond_to?(symbol)
+        # how about a field or method in the parent?
+        @parent.data_object.__send__(symbol, *args)
+      else
+        super
+      end
+    end
+  end
+end

data/lib/bindata/registry.rb

@@ -0,0 +1,37 @@
+require 'singleton'
+
+module BinData
+  # This registry contains a register of name -> class mappings.
+  class Registry
+    include Singleton
+
+    def initialize
+      @registry = {}
+    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
+
+      # warn if replacing an existing class
+      if $VERBOSE and (existing = @registry[underscore_name])
+        warn "warning: replacing registered class #{existing} with #{klass}"
+      end
+
+      @registry[underscore_name] = klass
+      underscore_name.dup
+    end
+
+    # Returns the class matching a previously registered +name+.
+    def lookup(name)
+      @registry[name.to_s]
+    end
+  end
+end

data/lib/bindata/single.rb

@@ -0,0 +1,170 @@
+require 'bindata/base'
+
+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.
+  #
+  # == Parameters
+  #
+  # 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.
+  #                           Explicitly calling #value= is prohibited 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
+  #                           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.  A boolean return indicates
+  #                           success or failure.  Any other return is compared
+  #                           to the value just read in.
+  class Single < Base
+    # These are the parameters used by this class.
+    optional_parameters :initial_value, :value, :check_value
+
+    # Register the names of all subclasses of this class.
+    def self.inherited(subclass) #:nodoc:
+      register(subclass.name, subclass)
+    end
+
+    def initialize(params = {}, env = nil)
+      super(params, env)
+      ensure_mutual_exclusion(:initial_value, :value)
+      clear
+    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
+
+    # 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)
+        expected = eval_param(:check_value)
+        if not expected
+          raise ValidityError, "value not as expected"
+        elsif @value != expected and expected != true
+          raise ValidityError, "value is '#{@value}' but " +
+                               "expected '#{expected}'"
+        end
+      end
+    end
+
+    # To be called after calling #do_read.
+    def done_read
+      @in_read = false
+    end
+
+    # Writes the value for this data to +io+.
+    def _write(io)
+      raise "can't write whilst reading" if @in_read
+      io.write(val_to_str(_value))
+    end
+
+    # Returns the number of bytes it will take to write this data.
+    def _num_bytes(ignored)
+      val_to_str(_value).length
+    end
+
+    # Returns a snapshot of this data object.
+    def snapshot
+      value
+    end
+
+    # Single objects don't contain fields so this returns an empty list.
+    def field_names
+      []
+    end
+
+    # Returns the current value of this data.
+    def value
+      _value
+    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
+      end
+    end
+
+    #---------------
+    private
+
+    # The unmodified value of this data object.  Note that #value calls this
+    # method.  This is so that #value can be overridden in subclasses to 
+    # modify the value.
+    def _value
+      # Table of possible preconditions and expected outcome
+      #   1. :value and !in_read          ->   :value
+      #   2. :value and in_read           ->   @value
+      #   3. :initial_value and clear?    ->   :initial_value
+      #   4. :initial_value and !clear?   ->   @value
+      #   5. clear?                       ->   sensible_default
+      #   6. !clear?                      ->   @value
+
+      if not @in_read and (evaluated_value = eval_param(:value))
+        # rule 1 above
+        evaluated_value
+      else
+        # combining all other rules gives this simplified expression
+        @value || eval_param(:value) ||
+          eval_param(:initial_value) || sensible_default()
+      end
+    end
+
+    # Usuable by subclasses
+
+    # Reads exactly +n+ bytes from +io+.  This should be used by subclasses
+    # in preference to <tt>io.read(n)</tt>.
+    #
+    # If the data read is nil an EOFError is raised.
+    #
+    # If the data read is too short an IOError is raised.
+    def readbytes(io, n)
+      str = io.read(n)
+      raise EOFError, "End of file reached" if str == nil
+      raise IOError, "data truncated" if str.size < n
+      str
+    end
+
+=begin
+    # To be implemented by subclasses
+
+    # Return the string representation that +val+ will take when written.
+    def val_to_str(val)
+      raise NotImplementedError
+    end
+
+    # Read a number of bytes from +io+ and return the value they represent.
+    def read_val(io)
+      raise NotImplementedError
+    end
+
+    # Return a sensible default for this data.
+    def sensible_default
+      raise NotImplementedError
+    end
+
+    # To be implemented by subclasses
+=end
+  end
+end