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.

require 'bindata'

obj = BinData::Uint8.new(:initial_value => 42)
obj.value #=> 42
obj.value = 5
obj.value #=> 5
obj.clear
obj.value #=> 42

obj = BinData::Uint8.new(:value => 42)
obj.value #=> 42
obj.value = 5
obj.value #=> 42

obj = BinData::Uint8.new(:check_value => 3)
obj.read("\005") #=> BinData::ValidityError: value is '5' but expected '3'

obj = BinData::Uint8.new(:check_value => lambda { value < 5 })
obj.read("\007") #=> BinData::ValidityError: value not as expected

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, default_parameters, #do_read, #inspect, lookup, mandatory_parameters, mutually_exclusive_parameters, #num_bytes, optional_parameters, read, #read, register, sanitize_parameters, #to_s, #write

Constructor Details

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

Returns a new instance of Single.



58
59
60
61
 
# File 'lib/bindata/single.rb', line 58

def initialize(params = {}, env = nil)
  super(params, env)
  clear
end

Class Method Details

.all_possible_field_names(sanitized_params) ⇒ Object

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



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

def self.all_possible_field_names(sanitized_params)
  []
end

Instance Method Details

#_do_read(io) ⇒ Object

Reads the value for this data from io.



75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/bindata/single.rb', line 75

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.



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

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

#_write(io) ⇒ Object

Writes the value for this data to io.



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

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.



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

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) 


70
71
72
 
# File 'lib/bindata/single.rb', line 70

def clear?
  @value.nil?
end

#done_read ⇒ Object

To be called after calling #do_read.



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

def done_read
  @in_read = false
end

#field_names ⇒ Object

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



119
120
121
 
# File 'lib/bindata/single.rb', line 119

def field_names
  []
end

#single_value? ⇒ Boolean

Single objects are single_values

Returns:

  • (Boolean) 


114
115
116
 
# File 'lib/bindata/single.rb', line 114

def single_value?
  true
end

#snapshot ⇒ Object

Returns a snapshot of this data object.



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

def snapshot
  value
end

#value ⇒ Object

Returns the current value of this data.



124
125
126
 
# File 'lib/bindata/single.rb', line 124

def value
  _value
end

#value=(v) ⇒ Object

Sets the value of this data.



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

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