jbangert-bindata 1.5.0

data/lib/bindata/skip.rb

@@ -0,0 +1,48 @@
+require "bindata/base_primitive"
+
+module BinData
+  # Skip will skip over bytes from the input stream.  If the stream is not
+  # seekable, then the bytes are consumed and discarded.
+  #
+  # When writing, skip will write <tt>:length</tt> number of zero bytes.
+  #
+  #   require 'bindata'
+  #
+  #   class A < BinData::Record
+  #     skip :length => 5
+  #     string :a, :read_length => 5
+  #   end
+  #
+  #   obj = A.read("abcdefghij")
+  #   obj.a #=> "fghij"
+  #
+  # == Parameters
+  #
+  # Skip objects accept all the params that BinData::BasePrimitive
+  # does, as well as the following:
+  #
+  # <tt>:length</tt>:: The number of bytes to skip.
+  #
+  class Skip < BinData::BasePrimitive
+
+    mandatory_parameter :length
+
+    #---------------
+    private
+
+    def value_to_binary_string(val)
+      len = eval_parameter(:length)
+      "\000" * len
+    end
+
+    def read_and_return_value(io)
+      len = eval_parameter(:length)
+      io.seekbytes(len)
+      ""
+    end
+
+    def sensible_default
+      ""
+    end
+  end
+end

data/lib/bindata/string.rb

@@ -0,0 +1,145 @@
+require "bindata/base_primitive"
+
+module BinData
+  # A String is a sequence of bytes.  This is the same as strings in Ruby 1.8.
+  # 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 #=> "abcde"
+  #
+  #   obj = BinData::String.new(:length => 6)
+  #   obj.read(data)
+  #   obj #=> "abcdef"
+  #   obj.assign("abcdefghij")
+  #   obj #=> "abcdef"
+  #   obj.assign("abcd")
+  #   obj #=> "abcd\000\000"
+  #
+  #   obj = BinData::String.new(:length => 6, :trim_padding => true)
+  #   obj.assign("abcd")
+  #   obj #=> "abcd"
+  #   obj.to_binary_s #=> "abcd\000\000"
+  #
+  #   obj = BinData::String.new(:length => 6, :pad_byte => 'A')
+  #   obj.assign("abcd")
+  #   obj #=> "abcdAA"
+  #   obj.to_binary_s #=> "abcdAA"
+  #
+  # == Parameters
+  #
+  # String objects accept all the params that BinData::BasePrimitive
+  # does, as well as the following:
+  #
+  # <tt>:read_length</tt>::    The length in bytes to use when reading a value.
+  # <tt>:length</tt>::         The fixed length of the string.  If a shorter
+  #                            string is set, it will be padded to this length.
+  # <tt>:pad_byte</tt>::       The byte to use when padding a string to a
+  #                            set length.  Valid values are Integers and
+  #                            Strings of length 1.  "\0" is the default.
+  # <tt>:pad_front</tt>::      Signifies that the padding occurs at the front
+  #                            of the string rather than the end.  Default
+  #                            is false.
+  # <tt>:trim_padding</tt>::   Boolean, default false.  If set, #value will
+  #                            return the value with all pad_bytes trimmed
+  #                            from the end of the string.  The value will
+  #                            not be trimmed when writing.
+  class String < BinData::BasePrimitive
+
+    optional_parameters :read_length, :length, :trim_padding, :pad_front, :pad_left
+    default_parameters  :pad_byte => "\0"
+    mutually_exclusive_parameters :read_length, :length
+    mutually_exclusive_parameters :length, :value
+
+    class << self
+
+      def sanitize_parameters!(params) #:nodoc:
+        params.warn_replacement_parameter(:initial_length, :read_length)
+
+        params.warn_renamed_parameter(:pad_char, :pad_byte) # Remove this line in the future
+
+        if params.has_parameter?(:pad_left)
+          params[:pad_front] = params.delete(:pad_left)
+        end
+
+        if params.has_parameter?(:pad_byte)
+          byte = params[:pad_byte]
+          params[:pad_byte] = sanitized_pad_byte(byte)
+        end
+      end
+
+      #-------------
+      private
+
+      def sanitized_pad_byte(byte)
+        result = byte.is_a?(Integer) ? byte.chr : byte.to_s
+        len = result.respond_to?(:bytesize) ? result.bytesize : result.length
+        if len > 1
+          raise ArgumentError, ":pad_byte must not contain more than 1 byte"
+        end
+        result
+      end
+    end
+
+    def assign(val)
+      super(binary_string(val))
+    end
+
+    def snapshot
+      # override to trim padding
+      result = super
+      result = clamp_to_length(result)
+
+      if get_parameter(:trim_padding)
+        result = trim_padding(result)
+      end
+      result
+    end
+
+    #---------------
+    private
+
+    def clamp_to_length(str)
+      str = binary_string(str)
+
+      len = eval_parameter(:length) || str.length
+      if str.length == len
+        str
+      elsif str.length > len
+        str.slice(0, len)
+      else
+        padding = (eval_parameter(:pad_byte) * (len - str.length))
+        if get_parameter(:pad_front)
+          padding + str
+        else
+          str + padding
+        end
+      end
+    end
+
+    def trim_padding(str)
+      if get_parameter(:pad_front)
+        str.sub(/\A#{eval_parameter(:pad_byte)}*/, "")
+      else
+        str.sub(/#{eval_parameter(:pad_byte)}*\z/, "")
+      end
+    end
+
+    def value_to_binary_string(val)
+      clamp_to_length(val)
+    end
+
+    def read_and_return_value(io)
+      len = eval_parameter(:read_length) || eval_parameter(:length) || 0
+      io.readbytes(len)
+    end
+
+    def sensible_default
+      ""
+    end
+  end
+end

data/lib/bindata/stringz.rb

@@ -0,0 +1,96 @@
+require "bindata/base_primitive"
+
+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.
+  #
+  #   require 'bindata'
+  #
+  #   data = "abcd\x00efgh"
+  #
+  #   obj = BinData::Stringz.new
+  #   obj.read(data)
+  #   obj.snapshot #=> "abcd"
+  #   obj.num_bytes #=> 5
+  #   obj.to_binary_s #=> "abcd\000"
+  #
+  # == Parameters
+  #
+  # 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::BasePrimitive
+
+    optional_parameters :max_length
+
+    def assign(val)
+      super(binary_string(val))
+    end
+
+    def snapshot
+      # override to always remove trailing zero bytes
+      result = super
+      trim_and_zero_terminate(result).chomp("\0")
+    end
+
+    #---------------
+    private
+
+    def value_to_binary_string(val)
+      trim_and_zero_terminate(val)
+    end
+
+    def read_and_return_value(io)
+      max_length = eval_parameter(: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 = io.readbytes(1)
+        str << ch
+        i += 1
+      end
+
+      trim_and_zero_terminate(str)
+    end
+
+    def sensible_default
+      ""
+    end
+
+    def trim_and_zero_terminate(str)
+      result = binary_string(str)
+      truncate_after_first_zero_byte!(result)
+      trim_to!(result, eval_parameter(:max_length))
+      append_zero_byte_if_needed!(result)
+      result
+    end
+
+    def truncate_after_first_zero_byte!(str)
+      str.sub!(/([^\0]*\0).*/, '\1')
+    end
+
+    def trim_to!(str, max_length = nil)
+      if max_length
+        max_length = 1 if max_length < 1
+        str.slice!(max_length)
+        if str.length == max_length and str[-1, 1] != "\0"
+          str[-1, 1] = "\0"
+        end
+      end
+    end
+
+    def append_zero_byte_if_needed!(str)
+      if str.length == 0 or str[-1, 1] != "\0"
+        str << "\0"
+      end
+    end
+  end
+end

data/lib/bindata/struct.rb

@@ -0,0 +1,388 @@
+require 'bindata/base'
+
+module BinData
+
+  class Base
+    optional_parameter :onlyif  # Used by Struct
+  end
+
+  # A Struct is an ordered collection of named data objects.
+  #
+  #    require 'bindata'
+  #
+  #    class Tuple < BinData::Record
+  #      int8  :x
+  #      int8  :y
+  #      int8  :z
+  #    end
+  #
+  #    obj = BinData::Struct.new(:hide => :a,
+  #                              :fields => [ [:int32le, :a],
+  #                                           [:int16le, :b],
+  #                                           [:tuple, :s] ])
+  #    obj.field_names   =># ["b", "s"]
+  #
+  #
+  # == 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.  Params is an
+  #                      optional hash of parameters to pass to this field
+  #                      when instantiating it.  If name is "" or nil, then
+  #                      that field is anonymous and behaves as a hidden field.
+  # <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.
+  # <tt>:endian</tt>::   Either :little or :big.  This specifies the default
+  #                      endian of any numerics in this struct, or in any
+  #                      nested data objects.
+  #
+  # == Field Parameters
+  #
+  # Fields may have have extra parameters as listed below:
+  #
+  # [<tt>:onlyif</tt>]   Used to indicate a data object is optional.
+  #                      if +false+, this object will not be included in any
+  #                      calls to #read, #write, #num_bytes or #snapshot.
+  class Struct < BinData::Base
+
+    mandatory_parameter :fields
+    optional_parameters :endian, :hide
+
+    # These reserved words may not be used as field names
+    RESERVED = Hash[*
+                 (Hash.instance_methods +
+                  %w{alias and begin break case class def defined do else elsif
+                     end ensure false for if in module next nil not or redo
+                     rescue retry return self super then true undef unless until
+                     when while yield} +
+                  %w{array element index value} ).collect { |name| name.to_sym }.
+                  uniq.collect { |key| [key, true] }.flatten
+               ]
+
+    class << self
+
+      def sanitize_parameters!(params) #:nodoc:
+        sanitize_endian(params)
+        sanitize_fields(params)
+        sanitize_hide(params)
+      end
+
+      #-------------
+      private
+
+      def sanitize_endian(params)
+        if params.needs_sanitizing?(:endian)
+          endian = params.create_sanitized_endian(params[:endian])
+          params[:endian] = endian
+          params.endian   = endian # sync params[:endian] and params.endian
+        end
+      end
+
+      def sanitize_fields(params)
+        if params.needs_sanitizing?(:fields)
+          fields = params[:fields]
+
+          params[:fields] = params.create_sanitized_fields
+          fields.each do |ftype, fname, fparams|
+            params[:fields].add_field(ftype, fname, fparams)
+          end
+
+          field_names = sanitized_field_names(params[:fields])
+          ensure_field_names_are_valid(field_names)
+        end
+      end
+
+      def sanitize_hide(params)
+        if params.needs_sanitizing?(:hide) and params.has_parameter?(:fields)
+          field_names  = sanitized_field_names(params[:fields])
+          hfield_names = hidden_field_names(params[:hide])
+
+          params[:hide] = (hfield_names & field_names)
+        end
+      end
+
+      def sanitized_field_names(sanitized_fields)
+        sanitized_fields.field_names.compact
+      end
+
+      def hidden_field_names(hidden)
+        (hidden || []).collect do |h|
+          unless Symbol === h
+            warn "Hidden field '#{h}' should be provided as a symbol.  Using strings is deprecated"
+          end
+          h.to_sym
+        end
+      end
+
+      def ensure_field_names_are_valid(field_names)
+        reserved_names = RESERVED
+
+        field_names.each do |name|
+          if self.class.method_defined?(name)
+            raise NameError.new("Rename field '#{name}' in #{self}, " +
+                                "as it shadows an existing method.", name)
+          end
+          if reserved_names.include?(name)
+            raise NameError.new("Rename field '#{name}' in #{self}, " +
+                                "as it is a reserved name.", name)
+          end
+          if field_names.count(name) != 1
+            raise NameError.new("field '#{name}' in #{self}, " +
+                                "is defined multiple times.", name)
+          end
+        end
+      end
+    end
+
+    def initialize_shared_instance
+      @field_names = get_parameter(:fields).field_names.freeze
+    end
+
+    def initialize_instance
+      @field_objs  = []
+    end
+
+    def clear #:nodoc:
+      @field_objs.each { |f| f.clear unless f.nil? }
+    end
+
+    def clear? #:nodoc:
+      @field_objs.all? { |f| f.nil? or f.clear? }
+    end
+
+    def assign(val)
+      clear
+      assign_fields(val)
+    end
+
+    def snapshot
+      snapshot = Snapshot.new
+      field_names.each do |name|
+        obj = find_obj_for_name(name)
+        snapshot[name] = obj.snapshot if include_obj(obj)
+      end
+      snapshot
+    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)
+      if include_hidden
+        @field_names.compact
+      else
+        hidden = get_parameter(:hide) || []
+        @field_names.compact - hidden
+      end.collect { |x| x.to_s }
+    end
+
+    def respond_to?(symbol, include_private = false) #:nodoc:
+      @field_names.include?(base_field_name(symbol)) || super
+    end
+
+    def method_missing(symbol, *args, &block) #:nodoc:
+      obj = find_obj_for_name(symbol)
+      if obj
+        invoke_field(obj, symbol, args)
+      else
+        super
+      end
+    end
+
+    def debug_name_of(child) #:nodoc:
+      field_name = @field_names[find_index_of(child)]
+      "#{debug_name}.#{field_name}"
+    end
+
+    def offset_of(child) #:nodoc:
+      instantiate_all_objs
+      sum = sum_num_bytes_below_index(find_index_of(child))
+      child.do_num_bytes.is_a?(Integer) ? sum.ceil : sum.floor
+    end
+
+    def do_read(io) #:nodoc:
+      instantiate_all_objs
+      @field_objs.each { |f| f.do_read(io) if include_obj(f) }
+    end
+
+    def do_write(io) #:nodoc
+      instantiate_all_objs
+      @field_objs.each { |f| f.do_write(io) if include_obj(f) }
+    end
+
+    def do_num_bytes #:nodoc:
+      instantiate_all_objs
+      sum_num_bytes_for_all_fields
+    end
+
+    def [](key)
+      find_obj_for_name(key)
+    end
+
+    def []=(key, value)
+      obj = find_obj_for_name(key)
+      if obj
+        obj.assign(value)
+      end
+    end
+
+    def has_key?(key)
+      @field_names.index(base_field_name(key))
+    end
+
+    def each_pair
+      @field_names.compact.each do |name|
+        yield [name, find_obj_for_name(name)]
+      end
+    end
+
+    #---------------
+    private
+
+    def base_field_name(name)
+      name.to_s.chomp("=").to_sym
+    end
+
+    def invoke_field(obj, symbol, args)
+      name = symbol.to_s
+      is_writer = (name[-1, 1] == "=")
+
+      if is_writer
+        obj.assign(*args)
+      else
+        obj
+      end
+    end
+
+    def find_index_of(obj)
+      @field_objs.index { |el| el.equal?(obj) }
+    end
+
+    def find_obj_for_name(name)
+      index = @field_names.index(base_field_name(name))
+      if index
+        instantiate_obj_at(index)
+        @field_objs[index]
+      else
+        nil
+      end
+    end
+
+    def instantiate_all_objs
+      @field_names.each_index { |i| instantiate_obj_at(i) }
+    end
+
+    def instantiate_obj_at(index)
+      if @field_objs[index].nil?
+        field = get_parameter(:fields)[index]
+        @field_objs[index] = field.instantiate(nil, self)
+      end
+    end
+
+    def assign_fields(val)
+      src = as_stringified_hash(val)
+
+      @field_names.compact.each do |name|
+        obj = find_obj_for_name(name)
+        if obj and src.has_key?(name)
+          obj.assign(src[name])
+        end
+      end
+    end
+
+    def as_stringified_hash(val)
+      if BinData::Struct === val
+        val
+      elsif val.nil?
+        {}
+      else
+        hash = Snapshot.new
+        val.each_pair { |k,v| hash[k] = v }
+        hash
+      end
+    end
+
+    def sum_num_bytes_for_all_fields
+      sum_num_bytes_below_index(@field_objs.length)
+    end
+
+    def sum_num_bytes_below_index(index)
+      sum = 0
+      (0...index).each do |i|
+        obj = @field_objs[i]
+        if include_obj(obj)
+          nbytes = obj.do_num_bytes
+          sum = (nbytes.is_a?(Integer) ? sum.ceil : sum) + nbytes
+        end
+      end
+
+      sum
+    end
+
+    def include_obj(obj)
+      not obj.has_parameter?(:onlyif) or obj.eval_parameter(:onlyif)
+    end
+
+    if RUBY_VERSION <= "1.9"
+      module OrderedHash #:nodoc:
+        def keys
+          @order ||= []
+          k = super
+          @order & k
+        end
+
+        def []=(key, value)
+          @order ||= []
+          @order << key
+          super(key, value)
+        end
+
+        def each
+          keys.each do |k|
+            yield [k, self[k]]
+          end
+        end
+
+        def each_pair
+          each do |el|
+            yield *el
+          end
+        end
+      end
+    end
+
+    # A hash that can be accessed via attributes.
+    class Snapshot < ::Hash #:nodoc:
+      include OrderedHash if RUBY_VERSION <= "1.9"
+
+      def has_key?(key)
+        super(key.to_s)
+      end
+
+      def [](key)
+        super(key.to_s)
+      end
+
+      def []=(key, value)
+        if value != nil
+          super(key.to_s, value)
+        end
+      end
+
+      def respond_to?(symbol, include_private = false)
+        has_key?(symbol) || super
+      end
+
+      def method_missing(symbol, *args)
+        self[symbol] || super
+      end
+    end
+  end
+end