bindata 0.5.0

data/lib/bindata/string.rb

@@ -0,0 +1,98 @@
+require "bindata/single"
+
+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.
+  #
+  # == Parameters
+  #
+  # String objects accept all the params that BinData::Single
+  # does, as well as the following:
+  #
+  # <tt>:initial_length</tt>:: The initial length to use before a value is
+  #                            either read or set.
+  # <tt>:length</tt>::         The fixed length of the string.  If a shorter
+  #                            string is set, it will be padded to this length.
+  # <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
+  #                            return the value with all pad_chars trimmed
+  #                            from the end of the string.  The value will
+  #                            not be trimmed when writing.
+  class String < Single
+    # These are the parameters used by this class.
+    mandatory_parameters :pad_char
+    optional_parameters  :initial_length, :length, :trim_value
+
+    def initialize(params = {}, env = nil)
+      super(cleaned_params(params), env)
+
+      # the only valid param combinations of length and value are:
+      #   :initial_length and :value
+      #   :length and :initial_value
+      ensure_mutual_exclusion(:initial_value, :value)
+      ensure_mutual_exclusion(:initial_length, :length)
+      ensure_mutual_exclusion(:initial_length, :initial_value)
+      ensure_mutual_exclusion(:length, :value)
+    end
+
+    # Overrides value to return the value padded to the desired length or
+    # trimmed as required.
+    def value
+      v = val_to_str(_value)
+      v.sub!(/#{eval_param(:pad_char)}*$/, "") if param(:trim_value) == true
+      v
+    end
+
+    #---------------
+    private
+
+    # Returns +val+ ensuring that it is padded to the desired length.
+    def val_to_str(val)
+      # trim val if necessary
+      len = val_num_bytes(val)
+      str = val.slice(0, len)
+
+      # then pad to length if str is short
+      str << (eval_param(:pad_char) * (len - str.length))
+    end
+
+    # Read a number of bytes from +io+ and return the value they represent.
+    def read_val(io)
+      readbytes(io, val_num_bytes(""))
+    end
+
+    # Returns an empty string as default.
+    def sensible_default
+      ""
+    end
+
+    # Return the number of bytes that +val+ will occupy when written.
+    def val_num_bytes(val)
+      if clear? and (evaluated = eval_param(:initial_length))
+        evaluated
+      elsif (evaluated = eval_param(:length))
+        evaluated
+      else
+        val.length
+      end
+    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
+
+      # 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

data/lib/bindata/stringz.rb

@@ -0,0 +1,83 @@
+require "bindata/single"
+
+module BinData
+  # A BinData::Stringz object is a container for a zero ("\0") terminated
+  # string.
+  #
+  # For convenience, the zero terminator is not necessary when setting the
+  # value.  Likewise, the returned value will not be zero terminated.
+  #
+  # == Parameters
+  #
+  # Stringz objects accept all the params that BinData::Single
+  # does, as well as the following:
+  #
+  # <tt>:max_length</tt>:: The maximum length of the string including the zero
+  #                        byte.
+  class Stringz < Single
+    # These are the parameters used by this class.
+    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
+
+    #---------------
+    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))
+    end
+
+    # Read a number of bytes from +io+ and return the value they represent.
+    def read_val(io)
+      max_length = eval_param(:max_length)
+      str = ""
+      i = 0
+      ch = nil
+
+      # read until zero byte or we have read in the max number of bytes
+      while ch != "\0" and i != max_length
+        ch = readbytes(io, 1)
+        str << ch
+        i += 1
+      end
+
+      zero_terminate(str, max_length)
+    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
+      str = "\0" if str == ""
+
+      # remove anything after the first \0
+      str = str.sub(/([^\0]*\0).*/, '\1')
+
+      # trim string to be no longer than max_length including zero byte
+      if max_length
+        max_length = 1 if max_length < 1
+        str = str[0, max_length]
+        if str.length == max_length and str[-1, 1] != "\0"
+          str[-1, 1] = "\0"
+        end
+      end
+
+      # ensure last byte in the string is a zero byte
+      str << "\0" if str[-1, 1] != "\0"
+
+      str
+    end
+  end
+end

data/lib/bindata/struct.rb

@@ -0,0 +1,292 @@
+require 'bindata/base'
+
+module BinData
+  # A Struct is an ordered collection of named data objects.
+  #
+  #    require 'bindata'
+  #
+  #    class Tuple < BinData::Struct
+  #      int8  :x
+  #      int8  :y
+  #      int8  :z
+  #    end
+  #
+  #    class SomeStruct < BinData::Struct
+  #      hide 'a'
+  #
+  #      int32le :a
+  #      int16le :b
+  #      tuple   nil
+  #    end
+  #
+  #    obj = SomeStruct.new
+  #    obj.field_names   =># ["b", "x", "y", "z"]
+  #
+  # == Parameters
+  #
+  # Parameters may be provided at initialisation to control the behaviour of
+  # an object.  These params are:
+  #
+  # <tt>:fields</tt>:: An array specifying the fields for this struct.  Each
+  #                    element of the array is of the form
+  #                    [type, name, params].  Type is a symbol representing
+  #                    a registered type.  Name is the name of this field.
+  #                    Name may be nil as in the example above.  Params is an
+  #                    optional hash of parameters to pass to this field when
+  #                    instantiating it.
+  # <tt>:hide</tt>::   A list of the names of fields that are to be hidden
+  #                    from the outside world.  Hidden fields don't appear
+  #                    in #snapshot or #field_names but are still accessible
+  #                    by name.
+  class Struct < Base
+    # A hash that can be accessed via attributes.
+    class Snapshot < Hash #:nodoc:
+      def method_missing(symbol, *args)
+        self[symbol.id2name] || super
+      end
+    end
+
+    # Register this class
+    register(self.name, self)
+
+    class << self
+      # Register the names of all subclasses of this class.
+      def inherited(subclass) #:nodoc:
+        register(subclass.name, subclass)
+      end
+
+      # Returns the names of any hidden fields in this struct.  Any given args
+      # are appended to the hidden list.
+      def hide(*args)
+        # note that fields are stored in an instance variable not a class var
+        @hide ||= []
+        args.each do |name|
+          next if name.nil?
+          @hide << name.to_s
+        end
+        @hide
+      end
+
+      # Used to define fields for this structure.
+      def method_missing(symbol, *args)
+        name, params = args
+
+        type = symbol
+        name = name.to_s unless name.nil?
+        params ||= {}
+
+        if lookup(type).nil?
+          raise TypeError, "unknown type '#{type}' for #{self}", caller
+        end
+
+        # note that fields are stored in an instance variable not a class var
+
+        # check for duplicate names
+        @fields ||= []
+        if @fields.detect { |t, n, p| n == name and n != nil }
+          raise SyntaxError, "duplicate field '#{name}' in #{self}", caller
+        end
+
+        # remember this field.  These fields will be recalled upon creating
+        # an instance of this class
+        @fields.push([type, name, params])
+      end
+
+      # Returns all stored fields.  Should only be called by #cleaned_params.
+      def fields
+        @fields || []
+      end
+    end
+
+    # These are the parameters used by this class.
+    mandatory_parameter :fields
+    optional_parameter :hide
+
+    # Creates a new Struct.
+    def initialize(params = {}, env = nil)
+      super(cleaned_params(params), env)
+
+      # create instances of the fields
+      @fields = param(:fields).collect do |type, name, params|
+        klass = self.class.lookup(type)
+        raise TypeError, "unknown type '#{type}' for #{self}" if klass.nil?
+        [name, klass.new(params, create_env)]
+      end
+    end
+
+    # Clears the field represented by +name+.  If no +name+
+    # is given, clears all fields in the struct.
+    def clear(name = nil)
+      if name.nil?
+        bindata_objects.each { |f| f.clear }
+      else
+        find_obj_for_name(name.to_s).clear
+      end
+    end
+
+    # Returns if the field represented by +name+ is clear?.  If no +name+
+    # is given, returns whether all fields are clear.
+    def clear?(name = nil)
+      if name.nil?
+        bindata_objects.each { |f| return false if not f.clear? }
+        true
+      else
+        find_obj_for_name(name.to_s).clear?
+      end
+    end
+
+    # Reads the values for all fields in this object from +io+.
+    def _do_read(io)
+      bindata_objects.each { |f| f.do_read(io) }
+    end
+
+    # To be called after calling #read.
+    def done_read
+      bindata_objects.each { |f| f.done_read }
+    end
+
+    # Writes the values for all fields in this object to +io+.
+    def _write(io)
+      bindata_objects.each { |f| f.write(io) }
+    end
+
+    # Returns the number of bytes it will take to write the field represented
+    # by +name+.  If +name+ is nil then returns the number of bytes required
+    # to write all fields.
+    def _num_bytes(name)
+      if name.nil?
+        bindata_objects.inject(0) { |sum, f| sum + f.num_bytes }
+      else
+        find_obj_for_name(name.to_s).num_bytes
+      end
+    end
+
+    # Returns a snapshot of this struct as a hash.
+    def snapshot
+      # allow structs to fake single value
+      return value if single_value?
+
+      hash = Snapshot.new
+      field_names.each do |name|
+        hash[name] = find_obj_for_name(name).snapshot
+      end
+      hash
+    end
+
+    # Returns a list of the names of all fields accessible through this
+    # object.  +include_hidden+ specifies whether to include hidden names
+    # in the listing.
+    def field_names(include_hidden = false)
+      # single values don't have any fields
+      return [] if single_value?
+
+      names = []
+      @fields.each do |name, obj|
+        if name != ""
+          names << name unless (param(:hide).include?(name) and !include_hidden)
+        else
+          names.concat(obj.field_names)
+        end
+      end
+      names
+    end
+
+    # Returns the data object that stores values for +name+.
+    def find_obj_for_name(name)
+      @fields.each do |n, o|
+        if n == name
+          return o
+        elsif n == "" and o.field_names.include?(name)
+          return o.find_obj_for_name(name)
+        end
+      end
+      nil
+    end
+
+    def offset_of(field)
+      field_name = field.to_s
+      offset = 0
+      @fields.each do |name, obj|
+        if name != ""
+          break if name == field_name
+          offset += obj.num_bytes
+        elsif obj.field_names.include?(field_name)
+          offset += obj.offset_of(field)
+          break
+        end
+      end
+      offset
+    end
+
+    # Override to include field names.
+    alias_method :orig_respond_to?, :respond_to?
+    def respond_to?(symbol, include_private = false)
+      orig_respond_to?(symbol, include_private) ||
+        field_names(true).include?(symbol.id2name.chomp("="))
+    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?
+      # need to use original respond_to? to prevent infinite recursion
+      orig_respond_to?(:value)
+    end
+
+    def method_missing(symbol, *args)
+      name = symbol.id2name
+
+      is_writer = (name[-1, 1] == "=")
+      name.chomp!("=")
+
+      # find the object that is responsible for name
+      if (obj = find_obj_for_name(name))
+        # pass on the request
+        if obj.single_value? and is_writer
+          obj.value = *args
+        elsif obj.single_value?
+          obj.value
+        else
+          obj
+        end
+      else
+        super
+      end
+    end
+
+    #---------------
+    private
+
+    # Returns a list of all the bindata objects for this struct.
+    def bindata_objects
+      @fields.collect { |f| f[1] }
+    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
+
+      # use fields defined in this class if no fields are passed as params
+      fields = new_params[:fields] || self.class.fields
+
+      # ensure the names of fields are strings and that params is a hash
+      new_params[:fields] = fields.collect do |t, n, p|
+        [t, n.to_s, (p || {}).dup]
+      end
+
+      # collect all non blank field names
+      field_names = new_params[:fields].collect { |f| f[1] }
+      field_names = field_names.delete_if { |n| n == "" }
+
+      # collect all hidden names that correspond to a field name
+      hide = []
+      (new_params[:hide] || self.class.hide).each do |h|
+        h = h.to_s
+        hide << h if field_names.include?(h)
+      end
+      new_params[:hide] = hide
+
+      new_params
+    end
+  end
+end