Documentation for Enum::Value

safe-enum-value-pr.md

Enum::Value

What it does

Enum::Value lets you create immutable value object instances from your Enum::Base subclasses. These Value instances delegate to the Enum::Base subclass for all read and write operations. Additionally, these instances are comparable with each other AND with strings, symbols, and integers (the integers representing enum indexes).

Simple setup

class Side < Enum::Base
  values :left, :right, :whole
end

value_object = Side.new(:right)
# => #<Side::Value:0x007f82abd7b920 @stored_value=:right>

Examples

value_object.value
# => "right"

value_object.to_s
# => "right"

value_object.to_sym
# => :right

value_object.index
# => 1

value_object.to_i
# => 1

value_object.valid?
# => true

Comparisons

value_object >= 1
# => true

value_object >= :right
# => true

value_object <=> :whole
# => -1

value_object <= Side.new(:whole)
# => true

value_object.between? :left, :whole
# => true

Safety

Enum::Value respects all safety features of the safe-enum gem. As a default, invalid tokens raise Enum::TokenNotFoundError.

Side.new(:outofbounds)

# Exception Raised => Enum::TokenNotFoundError: token 'outofbounds'' not found in the enum Side

The safety of Enum::Value loading can be relaxed.

Side.default_value nil

side = Side.new(:outofbounds)
# => #<Side::Value:0x007f82abd20868 @error=#<Enum::TokenNotFoundError: token 'outofbounds'' not found in the enum Side>, @stored_value=nil>

side.valid?
# => false

side.stored_value
# => nil

side.to_s
# Exception Raised => Enum::TokenNotFoundError: token ''' not found in the enum Side

And even more relaxed.

Side.default_value :ANY

side = Side.new(:outofbounds)
# => #<Side::Value:0x007f82abd20868 @error=#<Enum::TokenNotFoundError: token 'outofbounds'' not found in the enum Side>, @stored_value=:outofbounds>

side.valid?
# => false

side.stored_value
# => :outofbounds

As a default, reading invalid Value instances will raise Enum::TokenNotFoundError.

side.value
# Exception Raised => Enum::TokenNotFoundError: token 'outofbounds'' not found in the enum Side

Reading safety can be relaxed as well.

Side.suppress_read_errors true

side.error
# => #<Enum::TokenNotFoundError: token 'outofbounds'' not found in the enum Side>

side.valid?
# => false

side.value
# => :outofbounds

Settings

Enum::Value has two configurable settings.

.default_value

Set .default_value to control load behavior of value objects created with the Base subclass. More specifically, .default_value determines what happens when a new Value instance attempts to load an invalid token.

class Side < Enum::Base
  values :left, :right, :whole
  default_value :whole
end

The options for the .default_value setting are

• :ERROR Raise an error if loading invalid token
• :ANY Allow loading of any value, valid or otherwise (will store invalid value + generated error)
• :any_other_value Use .default_value if Enum::TokenNotFoundError is raised while loading token. The value given to .default_value need not be in the enum set.

The default for .default_value is :ERROR. Loading an invalid token will raise Enum::TokenNotFoundError.

.suppress_read_errors

Enum::Base.suppress_read_errors will suppress Enum::TokenNotFoundError when reading a Value instance, regardless of the validity of the @stored_value.

class Side < Enum::Base
  values :left, :right, :whole
  suppress_read_errors true
end

Example settings

The out-of-the-box behavior with no manipulation of the settings utilizes the full safety of safe-enum. Exceptions will be raised during loading or reading of invalid tokens.

class Side < Enum::Base
  values :left, :right, :whole
  # default_value :ERROR
  # suppress_read_errors false
end

If your project does not require strict adherence to your enum set, you can loosen up the settings.

class Side < Enum::Base
  values :left, :right, :whole
  default_value :ANY
  suppress_read_errors true
end