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. 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

#do_read, #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.



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

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.



31
32
33
 
# File 'lib/bindata/single.rb', line 31

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.



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

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

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

#_num_bytes(ignored) ⇒ Object

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



81
82
83
 
# File 'lib/bindata/single.rb', line 81

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

#_write(io) ⇒ Object

Writes the value for this data to io.



75
76
77
78
 
# File 'lib/bindata/single.rb', line 75

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.



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

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) 


48
49
50
 
# File 'lib/bindata/single.rb', line 48

def clear?
  @value.nil?
end

#done_read ⇒ Object

To be called after calling #do_read.



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

def done_read
  @in_read = false
end

#field_names ⇒ Object

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



91
92
93
 
# File 'lib/bindata/single.rb', line 91

def field_names
  []
end

#snapshot ⇒ Object

Returns a snapshot of this data object.



86
87
88
 
# File 'lib/bindata/single.rb', line 86

def snapshot
  value
end

#value ⇒ Object

Returns the current value of this data.



96
97
98
 
# File 'lib/bindata/single.rb', line 96

def value
  _value
end

#value=(v) ⇒ Object

Sets the value of this data.



101
102
103
104
105
106
107
 
# File 'lib/bindata/single.rb', line 101

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