Class: Cosmos::Structure

Inherits:
Object show all
Defined in:
lib/cosmos/packets/structure.rb,
ext/cosmos/ext/structure/structure.c

Overview

Maintains knowledge of a raw binary structure. Uses structure_item to create individual structure items which are read and written by binary_accessor.

Defined Under Namespace

Modules: MethodMissing

Constant Summary collapse

ASCII_8BIT_STRING =

Used to force encoding

"ASCII-8BIT".freeze
ZERO_STRING =

String providing a single 0 byte

"\000".freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(*args) ⇒ Object

Structure constructor



69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/cosmos/packets/structure.rb', line 69

def initialize(default_endianness = BinaryAccessor::HOST_ENDIANNESS, buffer = '', item_class = StructureItem)
  if (default_endianness == :BIG_ENDIAN) || (default_endianness == :LITTLE_ENDIAN)
    @default_endianness = default_endianness
    if buffer
      raise TypeError, "wrong argument type #{buffer.class} (expected String)" unless String === buffer

      @buffer = buffer.force_encoding(ASCII_8BIT_STRING)
    else
      @buffer = nil
    end
    @item_class = item_class
    @items = {}
    @sorted_items = []
    @defined_length = 0
    @defined_length_bits = 0
    @pos_bit_size = 0
    @neg_bit_size = 0
    @fixed_size = true
    @short_buffer_allowed = false
    @mutex = nil
  else
    raise(ArgumentError, "Unknown endianness '#{default_endianness}', must be :BIG_ENDIAN or :LITTLE_ENDIAN")
  end
end

Instance Attribute Details

#default_endianness ⇒ Symbol (readonly) 



31
32
33
 
# File 'lib/cosmos/packets/structure.rb', line 31

def default_endianness
  @default_endianness
end

#defined_length ⇒ Integer (readonly) 



41
42
43
 
# File 'lib/cosmos/packets/structure.rb', line 41

def defined_length
  @defined_length
end

#defined_length_bits ⇒ Integer (readonly) 



44
45
46
 
# File 'lib/cosmos/packets/structure.rb', line 44

def defined_length_bits
  @defined_length_bits
end

#fixed_size ⇒ Boolean (readonly) 



48
49
50
 
# File 'lib/cosmos/packets/structure.rb', line 48

def fixed_size
  @fixed_size
end

#items ⇒ Hash (readonly) 



35
36
37
 
# File 'lib/cosmos/packets/structure.rb', line 35

def items
  @items
end

#short_buffer_allowed ⇒ Boolean 



52
53
54
 
# File 'lib/cosmos/packets/structure.rb', line 52

def short_buffer_allowed
  @short_buffer_allowed
end

#sorted_items ⇒ Array (readonly) 



38
39
40
 
# File 'lib/cosmos/packets/structure.rb', line 38

def sorted_items
  @sorted_items
end

Instance Method Details

#append(item) ⇒ StrutureItem

Adds an item at the end of the structure. It adds the item to the items hash and resizes the buffer to accomodate the new item.

Raises:

  • (ArgumentError) 


287
288
289
290
291
292
293
294
295
296
 
# File 'lib/cosmos/packets/structure.rb', line 287

def append(item)
  raise ArgumentError, "Can't append an item after a variably sized item" if !@fixed_size

  if item.data_type == :DERIVED
    item.bit_offset = 0
  else
    item.bit_offset = @defined_length_bits
  end
  return define(item)
end

#append_item(name, bit_size, data_type, array_size = nil, endianness = @default_endianness, overflow = :ERROR) ⇒ StrutureItem

Define an item at the end of the structure. This creates a new instance of the item_class as given in the constructor and adds it to the items hash. It also resizes the buffer to accomodate the new item.

Raises:

  • (ArgumentError) 


273
274
275
276
277
278
279
280
 
# File 'lib/cosmos/packets/structure.rb', line 273

def append_item(name, bit_size, data_type, array_size = nil, endianness = @default_endianness, overflow = :ERROR)
  raise ArgumentError, "Can't append an item after a variably sized item" if !@fixed_size
  if data_type == :DERIVED
    return define_item(name, 0, bit_size, data_type, array_size, endianness, overflow)
  else
    return define_item(name, @defined_length_bits, bit_size, data_type, array_size, endianness, overflow)
  end
end

#buffer(copy = true) ⇒ String

Get the buffer used by the structure. The current buffer is copied and thus modifications to the returned buffer will have no effect on the structure items.



434
435
436
437
438
439
440
441
442
443
444
 
# File 'lib/cosmos/packets/structure.rb', line 434

def buffer(copy = true)
  if @buffer
    if copy
      return @buffer.dup
    else
      return @buffer
    end
  else
    return nil
  end
end

#buffer=(buffer) ⇒ Object

Set the buffer to be used by the structure. The buffer is copied and thus further modifications to the buffer have no effect on the structure items.



451
452
453
454
455
 
# File 'lib/cosmos/packets/structure.rb', line 451

def buffer=(buffer)
  synchronize() do
    internal_buffer_equals(buffer)
  end
end

#clone ⇒ Structure Also known as: dup

Make a light weight clone of this structure. This only creates a new buffer of data. The defined structure items are the same.



462
463
464
465
466
467
468
 
# File 'lib/cosmos/packets/structure.rb', line 462

def clone
  structure = super()
  # Use instance_variable_set since we have overriden buffer= to do
  # additional work that isn't neccessary here
  structure.instance_variable_set("@buffer".freeze, @buffer.clone) if @buffer
  return structure
end

#define(item) ⇒ StrutureItem

Adds the given item to the items hash. It also resizes the buffer to accomodate the new item.



189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
 
# File 'lib/cosmos/packets/structure.rb', line 189

def define(item)
  # Handle Overwriting Existing Item
  if @items[item.name]
    item_index = nil
    @sorted_items.each_with_index do |sorted_item, index|
      if sorted_item.name == item.name
        item_index = index
        break
      end
    end
    @sorted_items.delete_at(item_index) if item_index < @sorted_items.length
  end

  # Add to Sorted Items
  unless @sorted_items.empty?
    last_item = @sorted_items[-1]
    @sorted_items << item
    # If the current item or last item have a negative offset then we have
    # to re-sort. We also re-sort if the current item is less than the last
    # item because we are inserting.
    if last_item.bit_offset <= 0 or item.bit_offset <= 0 or item.bit_offset < last_item.bit_offset
      @sorted_items = @sorted_items.sort
    end
  else
    @sorted_items << item
  end

  # Add to the overall hash of defined items
  @items[item.name] = item
  # Update fixed size knowledge
  @fixed_size = false if (item.data_type != :DERIVED and item.bit_size <= 0) or (item.array_size and item.array_size <= 0)

  # Recalculate the overall defined length of the structure
  update_needed = false
  if item.bit_offset >= 0
    if item.bit_size > 0
      if item.array_size
        if item.array_size >= 0
          item_defined_length_bits = item.bit_offset + item.array_size
        else
          item_defined_length_bits = item.bit_offset
        end
      else
        item_defined_length_bits = item.bit_offset + item.bit_size
      end
      if item_defined_length_bits > @pos_bit_size
        @pos_bit_size = item_defined_length_bits
        update_needed = true
      end
    else
      if item.bit_offset > @pos_bit_size
        @pos_bit_size = item.bit_offset
        update_needed = true
      end
    end
  else
    if item.bit_offset.abs > @neg_bit_size
      @neg_bit_size = item.bit_offset.abs
      update_needed = true
    end
  end
  if update_needed
    @defined_length_bits = @pos_bit_size + @neg_bit_size
    @defined_length = @defined_length_bits / 8
    @defined_length += 1 if @defined_length_bits % 8 != 0
  end

  # Resize the buffer if necessary
  resize_buffer() if @buffer

  return item
end

#define_item(name, bit_offset, bit_size, data_type, array_size = nil, endianness = @default_endianness, overflow = :ERROR) ⇒ StrutureItem

Define an item in the structure. This creates a new instance of the item_class as given in the constructor and adds it to the items hash. It also resizes the buffer to accomodate the new item.



175
176
177
178
179
180
181
182
 
# File 'lib/cosmos/packets/structure.rb', line 175

def define_item(name, bit_offset, bit_size, data_type, array_size = nil, endianness = @default_endianness, overflow = :ERROR)
  # Handle case-insensitive naming
  name_upcase = name.upcase

  # Create the item
  item = @item_class.new(name_upcase, bit_offset, bit_size, data_type, endianness, array_size, overflow)
  define(item)
end

#defined? ⇒ TrueClass or FalseClass

Indicates if any items have been defined for this structure



140
141
142
 
# File 'lib/cosmos/packets/structure.rb', line 140

def defined?
  @sorted_items.length > 0
end

#delete_item(name) ⇒ Object

Raises:

  • (ArgumentError) 


318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
 
# File 'lib/cosmos/packets/structure.rb', line 318

def delete_item(name)
  item = @items[name.upcase]
  raise ArgumentError, "Unknown item: #{name}" unless item

  # Find the item to delete in the sorted_items array
  item_index = nil
  @sorted_items.each_with_index do |sorted_item, index|
    if sorted_item.name == item.name
      item_index = index
      break
    end
  end
  @sorted_items.delete_at(item_index)
  @items.delete(name.upcase)
end

#enable_method_missing ⇒ Object

Enable the ability to read and write item values as if they were methods to the class



473
474
475
 
# File 'lib/cosmos/packets/structure.rb', line 473

def enable_method_missing
  extend(MethodMissing)
end

#formatted(value_type = :RAW, indent = 0, buffer = @buffer, ignored = nil) ⇒ String

Create a string that shows the name and value of each item in the structure



403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
 
# File 'lib/cosmos/packets/structure.rb', line 403

def formatted(value_type = :RAW, indent = 0, buffer = @buffer, ignored = nil)
  indent_string = ' ' * indent
  string = ''
  synchronize_allow_reads(true) do
    @sorted_items.each do |item|
      next if ignored && ignored.include?(item.name)

      if (item.data_type != :BLOCK) ||
         (item.data_type == :BLOCK and value_type != :RAW and
          item.respond_to? :read_conversion and item.read_conversion)
        string << "#{indent_string}#{item.name}: #{read_item(item, value_type, buffer)}\n"
      else
        value = read_item(item, value_type, buffer)
        if String === value
          string << "#{indent_string}#{item.name}:\n"
          string << value.formatted(1, 16, ' ', indent + 2)
        else
          string << "#{indent_string}#{item.name}: #{value}\n"
        end
      end
    end
  end
  return string
end

#get_item(name) ⇒ StructureItem

Returns StructureItem or one of its subclasses.

Raises:

  • (ArgumentError) 


300
301
302
303
304
305
 
# File 'lib/cosmos/packets/structure.rb', line 300

def get_item(name)
  item = @items[name.upcase]
  raise ArgumentError, "Unknown item: #{name}" unless item

  return item
end

#length ⇒ Object

Returns the actual structure length.

structure.length #=> 324



119
120
121
122
123
 
# File 'lib/cosmos/packets/structure.rb', line 119

def length
  return @buffer.length if @buffer

  return 0
end

#read(name, value_type = :RAW, buffer = @buffer) ⇒ Object

Read an item in the structure by name



362
363
364
 
# File 'lib/cosmos/packets/structure.rb', line 362

def read(name, value_type = :RAW, buffer = @buffer)
  return read_item(get_item(name), value_type, buffer)
end

#read_all(value_type = :RAW, buffer = @buffer, top = true) ⇒ Array<Array>

Read all items in the structure into an array of arrays

[[item name, item value], ...]



387
388
389
390
391
392
393
 
# File 'lib/cosmos/packets/structure.rb', line 387

def read_all(value_type = :RAW, buffer = @buffer, top = true)
  item_array = []
  synchronize_allow_reads(top) do
    @sorted_items.each { |item| item_array << [item.name, read_item(item, value_type, buffer)] }
  end
  return item_array
end

#read_item(*args) ⇒ Object

Read an item in the structure



102
103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/cosmos/packets/structure.rb', line 102

def read_item(item, value_type = :RAW, buffer = @buffer)
  return nil if item.data_type == :DERIVED

  if buffer
    if item.array_size
      return BinaryAccessor.read_array(item.bit_offset, item.bit_size, item.data_type, item.array_size, buffer, item.endianness)
    else
      return BinaryAccessor.read(item.bit_offset, item.bit_size, item.data_type, buffer, item.endianness)
    end
  else
    raise "No buffer given to read_item"
  end
end

#rename_item(item_name, new_item_name) ⇒ Object

Rename an existing item



148
149
150
151
152
153
154
155
156
 
# File 'lib/cosmos/packets/structure.rb', line 148

def rename_item(item_name, new_item_name)
  item = get_item(item_name)
  item.name = new_item_name
  @items.delete(item_name)
  @items[new_item_name] = item
  # Since @sorted_items contains the actual item reference it is
  # updated when we set the item.name
  item
end

#resize_buffer ⇒ Object

Resize the buffer at least the defined length of the structure



126
127
128
129
130
131
132
133
134
135
 
# File 'lib/cosmos/packets/structure.rb', line 126

def resize_buffer
  if @buffer
    # Extend data size
    if @buffer.length < @defined_length
      @buffer << (ZERO_STRING * (@defined_length - @buffer.length))
    end
  end

  return self
end

#set_item(item) ⇒ Object 



309
310
311
312
313
314
315
 
# File 'lib/cosmos/packets/structure.rb', line 309

def set_item(item)
  if @items[item.name]
    @items[item.name] = item
  else
    raise ArgumentError, "Unknown item: #{item.name} - Ensure item name is uppercase"
  end
end

#write(name, value, value_type = :RAW, buffer = @buffer) ⇒ Object

Write an item in the structure by name



374
375
376
 
# File 'lib/cosmos/packets/structure.rb', line 374

def write(name, value, value_type = :RAW, buffer = @buffer)
  write_item(get_item(name), value, value_type, buffer)
end

#write_item(item, value, value_type = :RAW, buffer = @buffer) ⇒ Object

Write a value to the buffer based on the item definition



342
343
344
345
346
347
348
349
350
351
352
 
# File 'lib/cosmos/packets/structure.rb', line 342

def write_item(item, value, value_type = :RAW, buffer = @buffer)
  if buffer
    if item.array_size
      BinaryAccessor.write_array(value, item.bit_offset, item.bit_size, item.data_type, item.array_size, buffer, item.endianness, item.overflow)
    else
      BinaryAccessor.write(value, item.bit_offset, item.bit_size, item.data_type, buffer, item.endianness, item.overflow)
    end
  else
    raise "No buffer given to write_item"
  end
end