Class: BinData::Struct

Inherits:
Base
  • Object
show all
Defined in:
lib/bindata/struct.rb,
lib/bindata/warnings.rb

Overview

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_namespace:: Allows namespaced type names. If a type is unrecognised, then each namespace is searched 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.

Direct Known Subclasses

Record

Defined Under Namespace

Modules: ByteAlignPlugin Classes: Snapshot

Constant Summary collapse

RESERVED =

These reserved words may not be used as field names

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] +
 %w[type initial_length read_until] +
 %w[fields endian search_namespace search_prefix hide onlyif byte_align] +
 %w[choices selection copy_on_change] +
 %w[read_abs_offset struct_params])
.collect(&:to_sym)
.uniq.collect { |key| [key, true]

Instance Method Summary collapse

Instance Method Details

#[](key) ⇒ Object 



155
156
157
 
# File 'lib/bindata/struct.rb', line 155

def [](key)
  find_obj_for_name(key)
end

#[]=(key, value) ⇒ Object 



159
160
161
 
# File 'lib/bindata/struct.rb', line 159

def []=(key, value)
  find_obj_for_name(key)&.assign(value)
end

#assign(val) ⇒ Object 



103
104
105
106
 
# File 'lib/bindata/struct.rb', line 103

def assign(val)
  clear
  assign_fields(val)
end

#clear ⇒ Object

:nodoc:



95
96
97
 
# File 'lib/bindata/struct.rb', line 95

def clear # :nodoc:
  @field_objs.each { |f| f.nil? || f.clear }
end

#clear? ⇒ Boolean

:nodoc:

Returns:

  • (Boolean) 


99
100
101
 
# File 'lib/bindata/struct.rb', line 99

def clear? # :nodoc:
  @field_objs.all? { |f| f.nil? || f.clear? }
end

#debug_name_of(child) ⇒ Object

:nodoc:



129
130
131
132
 
# File 'lib/bindata/struct.rb', line 129

def debug_name_of(child) # :nodoc:
  field_name = @field_names[find_index_of(child)]
  "#{debug_name}.#{field_name}"
end

#do_num_bytes ⇒ Object

:nodoc:



150
151
152
153
 
# File 'lib/bindata/struct.rb', line 150

def do_num_bytes # :nodoc:
  instantiate_all_objs
  sum_num_bytes_for_all_fields
end

#do_read(io) ⇒ Object

:nodoc:



140
141
142
143
 
# File 'lib/bindata/struct.rb', line 140

def do_read(io) # :nodoc:
  instantiate_all_objs
  @field_objs.each { |f| f.do_read(io) if include_obj_for_io?(f) }
end

#do_write(io) ⇒ Object

:nodoc:



145
146
147
148
 
# File 'lib/bindata/struct.rb', line 145

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(include_all = false) ⇒ Object

Calls the given block for each field_name-field_obj pair.

Does not include anonymous or hidden fields unless include_all is true.



171
172
173
174
175
176
177
178
179
180
181
182
183
 
# File 'lib/bindata/struct.rb', line 171

def each_pair(include_all = false)
  instantiate_all_objs

  pairs = @field_names.zip(@field_objs).select do |name, _obj|
    name || include_all
  end

  if block_given?
    pairs.each { |el| yield(el) }
  else
    pairs.each
  end
end

#field_names(include_hidden = false) ⇒ Object

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



120
121
122
123
124
125
126
127
 
# File 'lib/bindata/struct.rb', line 120

def field_names(include_hidden = false)
  if include_hidden
    @field_names.compact
  else
    hidden = get_parameter(:hide) || []
    @field_names.compact - hidden
  end
end

#initialize_instance ⇒ Object 



91
92
93
 
# File 'lib/bindata/struct.rb', line 91

def initialize_instance
  @field_objs = []
end

#initialize_shared_instance ⇒ Object 



83
84
85
86
87
88
89
 
# File 'lib/bindata/struct.rb', line 83

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) ⇒ Boolean Also known as: has_key?

Returns:

  • (Boolean) 


163
164
165
 
# File 'lib/bindata/struct.rb', line 163

def key?(key)
  @field_names.index(base_field_name(key))
end

#offset_of(child) ⇒ Object

:nodoc:



134
135
136
137
138
 
# File 'lib/bindata/struct.rb', line 134

def offset_of(child) # :nodoc:
  instantiate_all_objs
  sum = sum_num_bytes_below_index(find_index_of(child))
  child.bit_aligned? ? sum.floor : sum.ceil
end

#snapshot ⇒ Object 



108
109
110
111
112
113
114
115
 
# File 'lib/bindata/struct.rb', line 108

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