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_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.

Direct Known Subclasses

Record

Defined Under Namespace

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_prefix hide only_if byte_align} +
%w{choices selection copy_on_change} +
%w{read_abs_offset struct_params}).collect(&:to_sym).
uniq.collect { |key| [key, true]

Instance Attribute Summary

Attributes inherited from Base

#parent

Instance Method Summary collapse

Methods inherited from Base

#==, #=~, #abs_offset, arg_processor, auto_call_delayed_io, bindata_name, #debug_name, #eval_parameter, #get_parameter, #has_parameter?, #initialize_with_warning, #inspect, #lazy_evaluator, #new, #num_bytes, #pretty_print, #read, read, register_subclasses, #rel_offset, #safe_respond_to?, #to_binary_s, #to_hex, #to_s, unregister_self, #write

Methods included from AcceptedParametersPlugin

#accepted_parameters, #default_parameters, #mandatory_parameters, #mutually_exclusive_parameters, #optional_parameters

Methods included from CheckOrAdjustOffsetPlugin

included

Methods included from RegisterNamePlugin

included

Methods included from Framework

#bit_aligned?

Instance Method Details

#[](key) ⇒ Object 



153
154
155
 
# File 'lib/bindata/struct.rb', line 153

def [](key)
  find_obj_for_name(key)
end

#[]=(key, value) ⇒ Object 



157
158
159
160
161
162
 
# 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) ⇒ Object 



101
102
103
104
 
# File 'lib/bindata/struct.rb', line 101

def assign(val)
  clear
  assign_fields(val)
end

#clear ⇒ Object

:nodoc:



93
94
95
 
# File 'lib/bindata/struct.rb', line 93

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

#clear? ⇒ Boolean

:nodoc:

Returns:

  • (Boolean) 


97
98
99
 
# File 'lib/bindata/struct.rb', line 97

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

#debug_name_of(child) ⇒ Object

:nodoc:



127
128
129
130
 
# File 'lib/bindata/struct.rb', line 127

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

#do_num_bytes ⇒ Object

:nodoc:



148
149
150
151
 
# File 'lib/bindata/struct.rb', line 148

def do_num_bytes #:nodoc:
  instantiate_all_objs
  sum_num_bytes_for_all_fields
end

#do_read(io) ⇒ Object

:nodoc:



138
139
140
141
 
# File 'lib/bindata/struct.rb', line 138

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



143
144
145
146
 
# 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 ⇒ Object 



168
169
170
171
172
 
# 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) ⇒ 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.



118
119
120
121
122
123
124
125
 
# 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

#initialize_instance ⇒ Object 



89
90
91
 
# File 'lib/bindata/struct.rb', line 89

def initialize_instance
  @field_objs = []
end

#initialize_shared_instance ⇒ Object 



81
82
83
84
85
86
87
 
# 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) ⇒ Boolean Also known as: has_key?

Returns:

  • (Boolean) 


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

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

#offset_of(child) ⇒ Object

:nodoc:



132
133
134
135
136
 
# File 'lib/bindata/struct.rb', line 132

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 



106
107
108
109
110
111
112
113
 
# 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