class BinData::Struct

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:

:fields

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.

:hide

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.

:endian

Either :little or :big. This specifies the default endian of any numerics in this struct, or in any nested data objects.

:search_prefix

Allows abbreviated type names. If a type is unrecognised, then each prefix is applied until a match is found.

Field Parameters

Fields may have have extra parameters as listed below:

:onlyif

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.

:byte_align

This field’s rel_offset must be a multiple of :byte_align.

Constants

RESERVED

These reserved words may not be used as field names

Public Instance Methods

[](key) click to toggle source
# File lib/bindata/struct.rb, line 153
def [](key)
  find_obj_for_name(key)
end
[]=(key, value) click to toggle source
# File lib/bindata/struct.rb, line 157
def []=(key, value)
  obj = find_obj_for_name(key)
  if obj
    obj.assign(value)
  end
end
assign(val) click to toggle source
# File lib/bindata/struct.rb, line 101
def assign(val)
  clear
  assign_fields(val)
end
do_write(io) click to toggle source
# File lib/bindata/struct.rb, line 143
def do_write(io) #:nodoc
  instantiate_all_objs
  @field_objs.each { |f| f.do_write(io) if include_obj_for_io?(f) }
end
each_pair() { |name, find_obj_for_name(name)| ... } click to toggle source
# File lib/bindata/struct.rb, line 168
def each_pair
  @field_names.compact.each do |name|
    yield [name, find_obj_for_name(name)]
  end
end
field_names(include_hidden = false) click to toggle source

Returns a list of the names of all fields accessible through this object. include_hidden specifies whether to include hidden names in the listing.

# File lib/bindata/struct.rb, line 118
def field_names(include_hidden = false)
  if include_hidden
    @field_names.compact
  else
    hidden = get_parameter(:hide) || []
    @field_names.compact - hidden
  end
end
has_key?(key)

has_key? is deprecated

Alias for: key?
initialize_instance() click to toggle source
# File lib/bindata/struct.rb, line 89
def initialize_instance
  @field_objs = []
end
initialize_shared_instance() click to toggle source
# File lib/bindata/struct.rb, line 81
def initialize_shared_instance
  fields = get_parameter(:fields)
  @field_names = fields.field_names.freeze
  extend ByteAlignPlugin if fields.any_field_has_parameter?(:byte_align)
  define_field_accessors
  super
end
key?(key) click to toggle source
# File lib/bindata/struct.rb, line 164
def key?(key)
  @field_names.index(base_field_name(key))
end
Also aliased as: has_key?
snapshot() click to toggle source
# File lib/bindata/struct.rb, line 106
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

Private Instance Methods

as_stringified_hash(val) click to toggle source
# File lib/bindata/struct.rb, line 239
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
assign_fields(val) click to toggle source
# File lib/bindata/struct.rb, line 228
def assign_fields(val)
  src = as_stringified_hash(val)

  @field_names.compact.each do |name|
    obj = find_obj_for_name(name)
    if obj && src.key?(name)
      obj.assign(src[name])
    end
  end
end
base_field_name(name) click to toggle source
# File lib/bindata/struct.rb, line 213
def base_field_name(name)
  name.to_s.sub(/(=|\?)\z/, "").to_sym
end
define_field_accessors() click to toggle source
# File lib/bindata/struct.rb, line 177
def define_field_accessors
  get_parameter(:fields).each_with_index do |field, i|
    name = field.name_as_sym
    define_field_accessors_for(name, i) if name
  end
end
define_field_accessors_for(name, index) click to toggle source
# File lib/bindata/struct.rb, line 184
def define_field_accessors_for(name, index)
  define_singleton_method(name) do
    instantiate_obj_at(index) if @field_objs[index].nil?
    @field_objs[index]
  end
  define_singleton_method("#{name}=") do |*vals|
    instantiate_obj_at(index) if @field_objs[index].nil?
    @field_objs[index].assign(*vals)
  end
  define_singleton_method("#{name}?") do
    instantiate_obj_at(index) if @field_objs[index].nil?
    include_obj?(@field_objs[index])
  end
end
find_index_of(obj) click to toggle source
# File lib/bindata/struct.rb, line 199
def find_index_of(obj)
  @field_objs.index { |el| el.equal?(obj) }
end
find_obj_for_name(name) click to toggle source
# File lib/bindata/struct.rb, line 203
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
include_obj?(obj) click to toggle source
# File lib/bindata/struct.rb, line 273
def include_obj?(obj)
  !obj.has_parameter?(:onlyif) || obj.eval_parameter(:onlyif)
end
include_obj_for_io?(obj) click to toggle source
# File lib/bindata/struct.rb, line 267
def include_obj_for_io?(obj)
  # Used by #do_read and #do_write, to ensure the stream is passed to
  # DelayedIO objects for delayed processing.
  include_obj?(obj) || DelayedIO === obj
end
instantiate_all_objs() click to toggle source
# File lib/bindata/struct.rb, line 217
def instantiate_all_objs
  @field_names.each_index { |i| instantiate_obj_at(i) }
end
instantiate_obj_at(index) click to toggle source
# File lib/bindata/struct.rb, line 221
def instantiate_obj_at(index)
  if @field_objs[index].nil?
    field = get_parameter(:fields)[index]
    @field_objs[index] = field.instantiate(nil, self)
  end
end
sum_num_bytes_below_index(index) click to toggle source
# File lib/bindata/struct.rb, line 255
def sum_num_bytes_below_index(index)
  (0...index).inject(0) do |sum, i|
    obj = @field_objs[i]
    if include_obj?(obj)
      nbytes = obj.do_num_bytes
      (nbytes.is_a?(Integer) ? sum.ceil : sum) + nbytes
    else
      sum
    end
  end
end
sum_num_bytes_for_all_fields() click to toggle source
# File lib/bindata/struct.rb, line 251
def sum_num_bytes_for_all_fields
  sum_num_bytes_below_index(@field_objs.length)
end