Class: BinData::Single

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

Overview

A BinData::Single object is a container for a value that has a particular binary representation. A value corresponds to a primitive type such as as integer, float or string. Only one value can be contained by this object. This value can be read from or written to an IO stream.

Parameters

Parameters may be provided at initialisation to control the behaviour of an object. These params include those for BinData::Base as well as:

:initial_value

This is the initial value to use before one is either #read or explicitly set with #value=.

:value

The object will always have this value. Explicitly calling #value= is prohibited when using this param. In the interval between calls to #do_read and #done_read, #value will return the value of the data read from the IO, not the result of the :value param.

:check_value

Raise an error unless the value read in meets this criteria. The variable value is made available to any lambda assigned to this parameter. A boolean return indicates success or failure. Any other return is compared to the value just read in.

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Base

#accepted_parameters, #do_read, #inspect, #klass_lookup, lookup, mandatory_parameters, #num_bytes, optional_parameters, parameters, read, #read, register, #single_value?, #write

Constructor Details

#initialize(params = {}, env = nil) ⇒ Single

Returns a new instance of Single.



37
38
39
40
41
 
# File 'lib/bindata/single.rb', line 37

def initialize(params = {}, env = nil)
  super(params, env)
  ensure_mutual_exclusion(:initial_value, :value)
  clear
end

Class Method Details

.inherited(subclass) ⇒ Object

Register the names of all subclasses of this class.



33
34
35
 
# File 'lib/bindata/single.rb', line 33

def self.inherited(subclass) #:nodoc:
  register(subclass.name, subclass)
end

Instance Method Details

#_do_read(io) ⇒ Object

Reads the value for this data from io.



55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/bindata/single.rb', line 55

def _do_read(io)
  @in_read = true
  @value   = read_val(io)

  # does the value meet expectations?
  if has_param?(:check_value)
    current_value = self.value
    expected = eval_param(:check_value, :value => current_value)
    if not expected
      raise ValidityError, "value not as expected"
    elsif current_value != expected and expected != true
      raise ValidityError, "value is '#{current_value}' but " +
                           "expected '#{expected}'"
    end
  end
end

#_num_bytes(ignored) ⇒ Object

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



84
85
86
 
# File 'lib/bindata/single.rb', line 84

def _num_bytes(ignored)
  val_to_str(_value).length
end

#_write(io) ⇒ Object

Writes the value for this data to io.



78
79
80
81
 
# File 'lib/bindata/single.rb', line 78

def _write(io)
  raise "can't write whilst reading" if @in_read
  io.write(val_to_str(_value))
end

#clear ⇒ Object

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



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

def clear
  @value = nil
  @in_read = false
end

#clear? ⇒ Boolean

Returns if the value of this data has been read or explicitly set.

Returns:

  • (Boolean) 


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

def clear?
  @value.nil?
end

#done_read ⇒ Object

To be called after calling #do_read.



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

def done_read
  @in_read = false
end

#field_names ⇒ Object

Single objects don’t contain fields so this returns an empty list.



94
95
96
 
# File 'lib/bindata/single.rb', line 94

def field_names
  []
end

#snapshot ⇒ Object

Returns a snapshot of this data object.



89
90
91
 
# File 'lib/bindata/single.rb', line 89

def snapshot
  value
end

#value ⇒ Object

Returns the current value of this data.



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

def value
  _value
end

#value=(v) ⇒ Object

Sets the value of this data.



104
105
106
107
108
109
110
 
# File 'lib/bindata/single.rb', line 104

def value=(v)
  # only allow modification if the value isn't predefined
  unless has_param?(:value)
    raise ArgumentError, "can't set a nil value" if v.nil?
    @value = v
  end
end