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:
Constants
- RESERVED
These reserved words may not be used as field names
Public Instance Methods
# File lib/bindata/struct.rb, line 147 def [](key) find_obj_for_name(key) end
# File lib/bindata/struct.rb, line 151 def []=(key, value) obj = find_obj_for_name(key) if obj obj.assign(value) end end
# File lib/bindata/struct.rb, line 95 def assign(val) clear assign_fields(val) end
# File lib/bindata/struct.rb, line 137 def do_write(io) #:nodoc instantiate_all_objs @field_objs.each { |f| f.do_write(io) if include_obj?(f) } end
# File lib/bindata/struct.rb, line 162 def each_pair @field_names.compact.each do |name| yield [name, find_obj_for_name(name)] end 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.
# File lib/bindata/struct.rb, line 112 def field_names(include_hidden = false) if include_hidden @field_names.compact else hidden = get_parameter(:hide) || [] @field_names.compact - hidden end end
# File lib/bindata/struct.rb, line 158 def has_key?(key) @field_names.index(base_field_name(key)) end
# File lib/bindata/struct.rb, line 83 def initialize_instance @field_objs = [] end
# File lib/bindata/struct.rb, line 100 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
# File lib/bindata/struct.rb, line 233 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
# File lib/bindata/struct.rb, line 222 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
# File lib/bindata/struct.rb, line 207 def base_field_name(name) name.to_s.sub(/(=|\?)\z/, "").to_sym end
# File lib/bindata/struct.rb, line 171 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
# File lib/bindata/struct.rb, line 178 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
# File lib/bindata/struct.rb, line 193 def find_index_of(obj) @field_objs.index { |el| el.equal?(obj) } end
# File lib/bindata/struct.rb, line 197 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
# File lib/bindata/struct.rb, line 261 def include_obj?(obj) not obj.has_parameter?(:onlyif) or obj.eval_parameter(:onlyif) end
# File lib/bindata/struct.rb, line 211 def instantiate_all_objs @field_names.each_index { |i| instantiate_obj_at(i) } end
# File lib/bindata/struct.rb, line 215 def instantiate_obj_at(index) if @field_objs[index].nil? field = get_parameter(:fields)[index] @field_objs[index] = field.instantiate(nil, self) end end
# File lib/bindata/struct.rb, line 249 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
# File lib/bindata/struct.rb, line 245 def sum_num_bytes_for_all_fields sum_num_bytes_below_index(@field_objs.length) end