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
orfield_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 153 def [](key) find_obj_for_name(key) end
# File lib/bindata/struct.rb, line 157 def []=(key, value) obj = find_obj_for_name(key) if obj obj.assign(value) end end
# File lib/bindata/struct.rb, line 101 def assign(val) clear assign_fields(val) end
# 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
# 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
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
# File lib/bindata/struct.rb, line 89 def initialize_instance @field_objs = [] end
# File lib/bindata/struct.rb, line 164 def key?(key) @field_names.index(base_field_name(key)) end
# 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
# 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
# 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
# File lib/bindata/struct.rb, line 213 def base_field_name(name) name.to_s.sub(/(=|\?)\z/, "").to_sym end
# 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
# 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
# File lib/bindata/struct.rb, line 199 def find_index_of(obj) @field_objs.index { |el| el.equal?(obj) } end
# 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
# File lib/bindata/struct.rb, line 273 def include_obj?(obj) !obj.has_parameter?(:onlyif) || obj.eval_parameter(:onlyif) end
# 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
# File lib/bindata/struct.rb, line 217 def instantiate_all_objs @field_names.each_index { |i| instantiate_obj_at(i) } end
# 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
# 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
# File lib/bindata/struct.rb, line 251 def sum_num_bytes_for_all_fields sum_num_bytes_below_index(@field_objs.length) end