Class: BinData::Base

Inherits:
Object
  • Object
show all
Defined in:
lib/bindata/base.rb,
lib/bindata/deprecated.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.



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

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.



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

def parent
  @parent
end

Class Method Details

.accepted_parameters ⇒ Object 



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

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 



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

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

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



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

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

.mutually_exclusive_parameters(*args) ⇒ Object 



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

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

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



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

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.



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

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

.sanitize_parameters!(params, sanitizer) ⇒ Object 



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

def sanitize_parameters!(params, sanitizer)
end

Instance Method Details

#==(other) ⇒ Object 



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

def ==(other)
  # 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.



174
175
176
 
# File 'lib/bindata/base.rb', line 174

def assign(val)
  _assign(val)
end

#clear ⇒ Object

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

Raises:

  • (NotImplementedError) 


268
269
270
 
# File 'lib/bindata/base.rb', line 268

def clear
  raise NotImplementedError
end

#clear? ⇒ Boolean

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

Returns:

  • (Boolean)

Raises:

  • (NotImplementedError) 


273
274
275
 
# File 'lib/bindata/base.rb', line 273

def clear?
  raise NotImplementedError
end

#debug_name ⇒ Object

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



202
203
204
205
206
207
208
 
# File 'lib/bindata/base.rb', line 202

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.

Raises:

  • (NotImplementedError) 


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

def debug_name_of(child)
  raise NotImplementedError
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.



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

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.



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

def get_parameter(key)
  @params[key]
end

#has_parameter?(key) ⇒ Boolean

Returns whether key exists in the parameters hash.

Returns:

  • (Boolean) 


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

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

#inspect ⇒ Object

Return a human readable representation of this data object.



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

def inspect
  snapshot.inspect
end

#num_bytes(deprecated = nil) ⇒ Object

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



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

def num_bytes(deprecated = nil)
  num = do_num_bytes(deprecated)
  num.ceil
end

#offset ⇒ Object

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



211
212
213
214
215
216
217
 
# File 'lib/bindata/base.rb', line 211

def offset
  if parent
    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.

Raises:

  • (NotImplementedError) 


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

def offset_of(child)
  raise NotImplementedError
end

#read(io) ⇒ Object

Reads data into this data object.



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

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

  do_read(io)
  done_read
  self
end

#single_value? ⇒ Boolean

Returns:

  • (Boolean) 


3
4
5
6
 
# File 'lib/bindata/deprecated.rb', line 3

def single_value?
  warn "#single_value? is deprecated.  It should no longer be needed"
  false
end

#snapshot ⇒ Object

Returns a snapshot of this data object.



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

def snapshot
  _snapshot
end

#to_binary_s ⇒ Object

Returns the string representation of this data object.



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

def to_binary_s
  io = StringIO.new
  write(io)
  io.rewind
  io.read
end

#to_s ⇒ Object

Return a string representing this data object.



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

def to_s
  snapshot.to_s
end

#write(io) ⇒ Object

Writes the value for this data to io.



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

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

  do_write(io)
  io.flush
  self
end