Class: BinData::Base

Inherits:
Object
  • Object
show all
Defined in:
lib/bindata/base.rb

Overview

This is the abstract base class for all data objects.

Parameters

Parameters may be provided at initialisation to control the behaviour of an object. These params are:

:check_offset

Raise an error if the current IO offset doesn’t meet this criteria. A boolean return indicates success or failure. Any other return is compared to the current offset. The variable offset is made available to any lambda assigned to this parameter. This parameter is only checked before reading.

:adjust_offset

Ensures that the current IO offset is at this position before reading. This is like :check_offset, except that it will adjust the IO offset instead of raising an error.

Direct Known Subclasses

Array, BasePrimitive, Choice, Struct, Wrapper

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(params = {}, parent = nil) ⇒ Base

Creates a new data object.

params is a hash containing symbol keys. Some params may reference callable objects (methods or procs). parent is the parent data object (e.g. struct, array, choice) this object resides under.



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

def initialize(params = {}, parent = nil)
  @params = Sanitizer.sanitize(params, self.class)
  @parent = parent
end

Instance Attribute Details

#parent ⇒ Object (readonly)

Returns the value of attribute parent.



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

def parent
  @parent
end

Class Method Details

.accepted_parameters ⇒ Object 



61
62
63
64
65
66
67
68
69
70
 
# File 'lib/bindata/base.rb', line 61

def accepted_parameters
  unless defined? @accepted_parameters
    ancestor = ancestors[1..-1].find { |cls|
                                  cls.respond_to?(:accepted_parameters)
                                 }
    ancestor_params = ancestor.nil? ? nil : ancestor.accepted_parameters
    @accepted_parameters = AcceptedParameters.new(ancestor_params)
  end
  @accepted_parameters
end

.default_parameters(*args) ⇒ Object Also known as: default_parameter 



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

def default_parameters(*args)
  accepted_parameters.default(*args)
end

.mandatory_parameters(*args) ⇒ Object Also known as: mandatory_parameter 



41
42
43
 
# File 'lib/bindata/base.rb', line 41

def mandatory_parameters(*args)
  accepted_parameters.mandatory(*args)
end

.mutually_exclusive_parameters(*args) ⇒ Object 



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

def mutually_exclusive_parameters(*args)
  accepted_parameters.mutually_exclusive(*args)
end

.optional_parameters(*args) ⇒ Object Also known as: optional_parameter 



45
46
47
 
# File 'lib/bindata/base.rb', line 45

def optional_parameters(*args)
  accepted_parameters.optional(*args)
end

.read(io) ⇒ Object

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



35
36
37
38
39
 
# File 'lib/bindata/base.rb', line 35

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

.sanitize_parameters!(params, sanitizer) ⇒ Object

:nodoc:



72
73
 
# File 'lib/bindata/base.rb', line 72

def sanitize_parameters!(params, sanitizer) #:nodoc:
end

Instance Method Details

#==(other) ⇒ Object

:nodoc:



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

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

#assign(val) ⇒ Object

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



172
173
174
 
# File 'lib/bindata/base.rb', line 172

def assign(val)
  _assign(val)
end

#clear ⇒ Object

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

Raises:

  • (NotImplementedError) 


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

def clear
  raise NotImplementedError
end

#clear? ⇒ Boolean

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

Returns:

  • (Boolean)

Raises:

  • (NotImplementedError) 


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

def clear?
  raise NotImplementedError
end

#debug_name ⇒ Object

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



205
206
207
208
209
210
211
 
# File 'lib/bindata/base.rb', line 205

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.



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

def debug_name_of(child) #:nodoc:
  debug_name
end

#eval_parameter(key, overrides = {}) ⇒ 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.



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

def eval_parameter(key, overrides = {})
  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.



117
118
119
 
# File 'lib/bindata/base.rb', line 117

def get_parameter(key)
  @params[key]
end

#has_parameter?(key) ⇒ Boolean

Returns whether key exists in the parameters hash.

Returns:

  • (Boolean) 


122
123
124
 
# File 'lib/bindata/base.rb', line 122

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

#inspect ⇒ Object

Return a human readable representation of this data object.



190
191
192
 
# File 'lib/bindata/base.rb', line 190

def inspect
  snapshot.inspect
end

#num_bytes ⇒ Object

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



161
162
163
 
# File 'lib/bindata/base.rb', line 161

def num_bytes
  do_num_bytes.ceil
end

#offset ⇒ Object

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



214
215
216
217
218
219
220
 
# File 'lib/bindata/base.rb', line 214

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.



297
298
299
 
# File 'lib/bindata/base.rb', line 297

def offset_of(child) #:nodoc:
  0
end

#pretty_print(pp) ⇒ Object

Work with Ruby’s pretty-printer library.



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

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

#read(io) ⇒ Object

Reads data into this data object.



127
128
129
130
131
132
133
 
# File 'lib/bindata/base.rb', line 127

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

  do_read(io)
  done_read
  self
end

#rel_offset ⇒ Object

Returns the offset of this object wrt to its parent.



223
224
225
226
227
228
229
 
# File 'lib/bindata/base.rb', line 223

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

#snapshot ⇒ Object

Returns a snapshot of this data object.



177
178
179
 
# File 'lib/bindata/base.rb', line 177

def snapshot
  _snapshot
end

#to_binary_s ⇒ Object

Returns the string representation of this data object.



182
183
184
185
186
187
 
# File 'lib/bindata/base.rb', line 182

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.



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

def to_s
  snapshot.to_s
end

#write(io) ⇒ Object

Writes the value for this data to io.



147
148
149
150
151
152
153
 
# File 'lib/bindata/base.rb', line 147

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

  do_write(io)
  io.flush
  self
end