Class: BinData::Base

Inherits:
Object
  • Object
show all
Includes:
AcceptedParametersMixin, CheckOrAdjustOffsetMixin
Defined in:
lib/bindata/base.rb,
lib/bindata/struct.rb,
lib/bindata/deprecated.rb

Overview

This is the abstract base class for all data objects.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from CheckOrAdjustOffsetMixin

#do_read_with_adjust_offset, #do_read_with_check_offset, included

Methods included from AcceptedParametersMixin

included

Instance Attribute Details

#parent ⇒ Object

Returns the value of attribute parent.



109
110
111
 
# File 'lib/bindata/base.rb', line 109

def parent
  @parent
end

Class Method Details

.arg_extractor ⇒ Object

The arg extractor for this class.



55
56
57
 
# File 'lib/bindata/base.rb', line 55

def arg_extractor
  BaseArgExtractor
end

.bindata_name ⇒ Object

The name of this class as used by Records, Arrays etc.



60
61
62
 
# File 'lib/bindata/base.rb', line 60

def bindata_name
  RegisteredClasses.underscore_name(self.name)
end

.read(io) ⇒ Object

Instantiates this class and reads from io, returning the newly created data object.



48
49
50
51
52
 
# File 'lib/bindata/base.rb', line 48

def read(io)
  obj = self.new
  obj.read(io)
  obj
end

.register(name, class_to_register) ⇒ Object 



42
43
44
 
# File 'lib/bindata/deprecated.rb', line 42

def register(name, class_to_register)
  warn "#{caller[0]} `register' is no longer needed as of BinData 1.3.2.  You can delete this line"
end

.register_self ⇒ Object 



38
39
40
 
# File 'lib/bindata/deprecated.rb', line 38

def register_self
  warn "#{caller[0]} `register_self' is no longer needed as of BinData 1.3.2.  You can delete this line"
end

.register_subclasses ⇒ Object

Registers all subclasses of this class for use



70
71
72
73
74
75
76
77
 
# File 'lib/bindata/base.rb', line 70

def register_subclasses #:nodoc:
  class << self
    define_method(:inherited) do |subclass|
      RegisteredClasses.register(subclass.name, subclass)
      register_subclasses
    end
  end
end

.unregister_self ⇒ Object

Call this method if this class is abstract and not to be used.



65
66
67
 
# File 'lib/bindata/base.rb', line 65

def unregister_self
  RegisteredClasses.unregister(name)
end

Instance Method Details

#==(other) ⇒ Object

:nodoc:



234
235
236
237
 
# File 'lib/bindata/base.rb', line 234

def ==(other) #:nodoc:
  # double dispatch
  other == snapshot
end

#_assign(val) ⇒ Object 



62
63
64
65
 
# File 'lib/bindata/deprecated.rb', line 62

def _assign(val)
  warn "#{caller[0]} `_assign(val)' is deprecated as of BinData 1.3.0.  Replace with `assign(val)'"
  assign(val)
end

#_do_num_bytes ⇒ Object 



57
58
59
60
 
# File 'lib/bindata/deprecated.rb', line 57

def _do_num_bytes
  warn "#{caller[0]} `_do_num_bytes' is deprecated as of BinData 1.3.0.  Replace with `do_num_bytes'"
  do_num_bytes
end

#_do_read(io) ⇒ Object 



47
48
49
50
 
# File 'lib/bindata/deprecated.rb', line 47

def _do_read(io)
  warn "#{caller[0]} `_do_read(io)' is deprecated as of BinData 1.3.0.  Replace with `do_read(io)'"
  do_read(io)
end

#_do_write(io) ⇒ Object 



52
53
54
55
 
# File 'lib/bindata/deprecated.rb', line 52

def _do_write(io)
  warn "#{caller[0]} `_do_write(io)' is deprecated as of BinData 1.3.0.  Replace with `do_write(io)'"
  do_write(io)
end

#_snapshot ⇒ Object 



67
68
69
70
 
# File 'lib/bindata/deprecated.rb', line 67

def _snapshot
  warn "#{caller[0]} `_snapshot' is deprecated as of BinData 1.3.0.  Replace with `snapshot'"
  snapshot
end

#assign(val) ⇒ Object

Assigns the value of val to this data object. Note that val must always be deep copied to ensure no aliasing problems can occur.

Raises:

  • (NotImplementedError) 


290
291
292
 
# File 'lib/bindata/base.rb', line 290

def assign(val)
  raise NotImplementedError
end

#clear ⇒ Object

Resets the internal state to that of a newly created object.

Raises:

  • (NotImplementedError) 


279
280
281
 
# File 'lib/bindata/base.rb', line 279

def clear
  raise NotImplementedError
end

#clear? ⇒ Boolean

Returns true if the object has not been changed since creation.

Returns:

  • (Boolean)

Raises:

  • (NotImplementedError) 


284
285
286
 
# File 'lib/bindata/base.rb', line 284

def clear?
  raise NotImplementedError
end

#debug_name ⇒ Object

Returns a user friendly name of this object for debugging purposes.



208
209
210
211
212
213
214
 
# File 'lib/bindata/base.rb', line 208

def debug_name
  if @parent
    @parent.debug_name_of(self)
  else
    "obj"
  end
end

#debug_name_of(child) ⇒ Object

Returns the debug name of child. This only needs to be implemented by objects that contain child objects.



301
302
303
 
# File 'lib/bindata/base.rb', line 301

def debug_name_of(child) #:nodoc:
  debug_name
end

#eval_parameter(key, overrides = nil) ⇒ Object

Returns the result of evaluating the parameter identified by key.

overrides is an optional parameters like hash that allow the parameters given at object construction to be overridden.

Returns nil if key does not refer to any parameter.



131
132
133
 
# File 'lib/bindata/base.rb', line 131

def eval_parameter(key, overrides = nil)
  LazyEvaluator.eval(self, get_parameter(key), overrides)
end

#get_parameter(key) ⇒ Object

Returns the parameter referenced by key. Use this method if you are sure the parameter is not to be evaluated. You most likely want #eval_parameter.



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

def get_parameter(key)
  @params[key]
end

#has_parameter?(key) ⇒ Boolean

Returns whether key exists in the parameters hash.

Returns:

  • (Boolean) 


143
144
145
 
# File 'lib/bindata/base.rb', line 143

def has_parameter?(key)
  @params.has_parameter?(key)
end

#initialize_instance(*args) ⇒ Object

Initializes the state of the object. All instance variables that are used by the object must be initialized here.



266
267
 
# File 'lib/bindata/base.rb', line 266

def initialize_instance
end

#initialize_with_deprecation(*args) ⇒ Object Also known as: initialize 



22
23
24
25
26
27
28
 
# File 'lib/bindata/deprecated.rb', line 22

def initialize_with_deprecation(*args)
  owner = method(:initialize).owner
  if owner != BinData::Base
    fail "implementing #initialize on #{owner} is not allowed.\nEither downgrade to BinData 1.2.2, or rename #initialize to #initialize_instance."
  end
  initialize_without_deprecation(*args)
end

#inspect ⇒ Object

Return a human readable representation of this data object.



193
194
195
 
# File 'lib/bindata/base.rb', line 193

def inspect
  snapshot.inspect
end

#new(value = nil, parent = nil) ⇒ Object

Creates a new data object based on this instance.

All parameters will be be duplicated. Use this method when creating multiple objects with the same parameters.



116
117
118
119
120
121
122
123
 
# File 'lib/bindata/base.rb', line 116

def new(value = nil, parent = nil)
  obj = clone
  obj.parent = parent if parent
  obj.initialize_instance
  obj.assign(value) if value

  obj
end

#num_bytes ⇒ Object

Returns the number of bytes it will take to write this data object.



180
181
182
 
# File 'lib/bindata/base.rb', line 180

def num_bytes
  do_num_bytes.ceil
end

#offset ⇒ Object

Returns the offset of this object wrt to its most distant ancestor.



217
218
219
220
221
222
223
 
# File 'lib/bindata/base.rb', line 217

def offset
  if @parent
    @parent.offset + @parent.offset_of(self)
  else
    0
  end
end

#offset_of(child) ⇒ Object

Returns the offset of child. This only needs to be implemented by objects that contain child objects.



307
308
309
 
# File 'lib/bindata/base.rb', line 307

def offset_of(child) #:nodoc:
  0
end

#pretty_print(pp) ⇒ Object

Work with Ruby’s pretty-printer library.



203
204
205
 
# File 'lib/bindata/base.rb', line 203

def pretty_print(pp) #:nodoc:
  pp.pp(snapshot)
end

#read(io) ⇒ Object

Reads data into this data object.



148
149
150
151
152
153
154
155
156
157
 
# File 'lib/bindata/base.rb', line 148

def read(io)
  io = BinData::IO.new(io) unless BinData::IO === io

  @in_read = true
  clear
  do_read(io)
  @in_read = false

  self
end

#rel_offset ⇒ Object

Returns the offset of this object wrt to its parent.



226
227
228
229
230
231
232
 
# File 'lib/bindata/base.rb', line 226

def rel_offset
  if @parent
    @parent.offset_of(self)
  else
    0
  end
end

#snapshot ⇒ Object

Returns a snapshot of this data object.

Raises:

  • (NotImplementedError) 


295
296
297
 
# File 'lib/bindata/base.rb', line 295

def snapshot
  raise NotImplementedError
end

#to_binary_s ⇒ Object

Returns the string representation of this data object.



185
186
187
188
189
190
 
# File 'lib/bindata/base.rb', line 185

def to_binary_s
  io = BinData::IO.create_string_io
  write(io)
  io.rewind
  io.read
end

#to_s ⇒ Object

Return a string representing this data object.



198
199
200
 
# File 'lib/bindata/base.rb', line 198

def to_s
  snapshot.to_s
end

#write(io) ⇒ Object

Writes the value for this data object to io.



171
172
173
174
175
176
177
 
# File 'lib/bindata/base.rb', line 171

def write(io)
  io = BinData::IO.new(io) unless BinData::IO === io

  do_write(io)
  io.flush
  self
end