Class: BinData::Base

Inherits:
Object
  • Object
show all
Extended by:
AcceptedParametersPlugin
Includes:
CheckOrAdjustOffsetPlugin, Framework, RegisterNamePlugin
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 AcceptedParametersPlugin

accepted_parameters, default_parameters, mandatory_parameters, mutually_exclusive_parameters, optional_parameters

Methods included from RegisterNamePlugin

included, #initialize_shared_instance

Methods included from CheckOrAdjustOffsetPlugin

included, #initialize_shared_instance

Methods included from Framework

#assign, #clear?, #debug_name_of, included, #offset_of, #snapshot

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.



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

def arg_extractor
  BaseArgExtractor
end

.bindata_name ⇒ Object

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



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

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.



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

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

.register_subclasses ⇒ Object

Registers all subclasses of this class for use



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

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.



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

def unregister_self
  RegisteredClasses.unregister(name)
end

Instance Method Details

#==(other) ⇒ Object

:nodoc:



254
255
256
257
 
# File 'lib/bindata/base.rb', line 254

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

#=~(other) ⇒ Object

Override and delegate =~ as it is defined in Object.



223
224
225
 
# File 'lib/bindata/base.rb', line 223

def =~(other)
  snapshot =~ other
end

#clear ⇒ Object

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



158
159
160
 
# File 'lib/bindata/base.rb', line 158

def clear
  initialize_instance
end

#debug_name ⇒ Object

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



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

def debug_name
  if @parent
    @parent.debug_name_of(self)
  else
    "obj"
  end
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
134
135
136
137
138
 
# File 'lib/bindata/base.rb', line 131

def eval_parameter(key, overrides = nil)
  value = get_parameter(key)
  if value.is_a?(Symbol) or value.respond_to?(:arity)
    lazy_evaluator.lazy_eval(value, overrides)
  else
    value
  end
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.



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

def get_parameter(key)
  @params[key]
end

#has_parameter?(key) ⇒ Boolean

Returns whether key exists in the parameters hash.

Returns:

  • (Boolean) 


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

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

#initialize_instance(*args) ⇒ Object 



43
44
45
46
47
 
# File 'lib/bindata/deprecated.rb', line 43

def initialize_instance(*args)
  unless args.empty?
    fail "#{caller[0]} remove the call to super in #initialize_instance"
  end
end

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



30
31
32
33
34
35
36
37
38
39
40
 
# File 'lib/bindata/deprecated.rb', line 30

def initialize_with_warning(*args)
  owner = method(:initialize).owner
  if owner != BinData::Base
    msg = "Don't override #initialize on #{owner}."
    if %w(BinData::Base BinData::BasePrimitive).include? self.class.superclass.name
      msg += "\nrename #initialize to #initialize_instance."
    end
    fail msg
  end
  initialize_without_warning(*args)
end

#inspect ⇒ Object

Return a human readable representation of this data object.



208
209
210
 
# File 'lib/bindata/base.rb', line 208

def inspect
  snapshot.inspect
end

#lazy_evaluator ⇒ Object

Returns a lazy evaluator for this object.



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

def lazy_evaluator #:nodoc:
  @lazy ||= LazyEvaluator.new(self)
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.



195
196
197
 
# File 'lib/bindata/base.rb', line 195

def num_bytes
  do_num_bytes.ceil
end

#offset ⇒ Object

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



237
238
239
240
241
242
243
 
# File 'lib/bindata/base.rb', line 237

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

#pretty_print(pp) ⇒ Object

Work with Ruby’s pretty-printer library.



218
219
220
 
# File 'lib/bindata/base.rb', line 218

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

#read(io) ⇒ Object

Reads data into this data object.



163
164
165
166
167
168
169
170
171
172
 
# File 'lib/bindata/base.rb', line 163

def read(io)
  io = BinData::IO::Read.new(io) unless BinData::IO::Read === 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.



246
247
248
249
250
251
252
 
# File 'lib/bindata/base.rb', line 246

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

#safe_respond_to?(symbol, include_private = false) ⇒ Boolean

A version of respond_to? used by the lazy evaluator. It doesn’t reinvoke the evaluator so as to avoid infinite evaluation loops.

Returns:

  • (Boolean) 


261
262
263
 
# File 'lib/bindata/base.rb', line 261

def safe_respond_to?(symbol, include_private = false) #:nodoc:
  respond_to?(symbol, include_private)
end

#to_binary_s ⇒ Object

Returns the string representation of this data object.



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

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.



213
214
215
 
# File 'lib/bindata/base.rb', line 213

def to_s
  snapshot.to_s
end

#write(io) ⇒ Object

Writes the value for this data object to io.



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

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

  do_write(io)
  io.flush
  self
end