meta_enum 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2613b743e3671c160c9e9402e181e49e300b4cbf0d89e8c42ed93299f8095a2f
-  data.tar.gz: 4fb9192c6bcfb1096a6b605a574f975e00247662670b7cf51e2744a5867ff9ee
+  metadata.gz: ae4f6d4921c00b29216e850aa59e679b34c3eba7d5cf9d5ae9365a69c81b75aa
+  data.tar.gz: fc7018df488e1de04230d58a9d5b8181ea9686157dd0dee48fa48e97c180b20f
 SHA512:
-  metadata.gz: 712fc2fddf6c361a890da5c24ce063556b0289d8bf437ccbc68b7051f501e7839a4926dafddc83bfbca055e8e206797c20117865586990f9e5b7c5eea75e0e26
-  data.tar.gz: a43af11ac01bd954776e9ddb41d557c06707cb1941e8374c7bafcffbb4b1845968699528dd56b7e5a0733e32c085b581f7a5b9c540c0d20f66684b5cff40acca
+  metadata.gz: fdfd752d85a7df06677a109c44fb75589e2e494312a90860dc5b878cce6ab02de618154775c715251bf3e8bb3a5274d3e62d02cbdb71b7ed08f41247481998b1
+  data.tar.gz: a1ec0eb6670569f0bb5efa36b04c6406269b519d2313201c8c5d1fcc2be0eea641b714733f712392d05dd6e692d680f17e3aff37d243e91c3d8737321ad00cb4

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 2.0.0 (January 27, 2018)
+
+Support non-integer values.
+
+This entailed some breaking changes:
+
+* MetaEnum::Value renamed to MetaEnum::Element
+* MetaEnum::MissingValue renamed to MetaEnum::MissingElement
+* MetaEnum::Value#number renamed to value
+* MetaEnum::Type#values renamed to elements
+* MetaEnum::Type#values_by_name renamed to elements_by_name
+* MetaEnum::Type#values_by_number renamed to elements_by_value

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    meta_enum (1.0.0)
+    meta_enum (2.0.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,7 +1,7 @@
 # MetaEnum
 
 MetaEnum is a library for handling enum types in Ruby. It makes it easy to
-convert between external numbers and internal names.
+convert between external values and internal names.
 
 ## Installation
 
@@ -32,16 +32,16 @@ ColorType = MetaEnum::Type.new(red: 0, green: 1, blue: 2)
 Use the `[]` operator to lookup a value by name:
 
 ```ruby
-ColorType[:green] # => #<MetaEnum::Value: 1 => green}>
+ColorType[:green] # => #<MetaEnum::Element: 1 => green}>
 ```
 
 Or lookup by number:
 
 ```ruby
-ColorType[1] # => #<MetaEnum::Value: 1 => green}>
+ColorType[1] # => #<MetaEnum::Element: 1 => green}>
 ```
 
-Values can also be easily compared with numbers or names:
+Elements can also be easily compared with values or names:
 
 ```ruby
 ColorType[:green] == 1 # => true
@@ -54,17 +54,17 @@ Missing names would almost always be a programming error, so that will raise an
 ColorType[:purple] # => raises: KeyError: key not found: :purple
 ```
 
-But missing numbers could mean that there are values defined externally we do not know about. So it is preferable not to raise an exception.
+But missing values could mean that there are values defined externally we do not know about. So it is preferable not to raise an exception.
 
 ```ruby
-ColorType[42] # => #<MetaEnum::MissingValue: 42}>
+ColorType[42] # => #<MetaEnum::MissingElement: 42}>
 ```
 
-Number and name can be retrieved from a `MetaEnum::Value`
+Value and name can be retrieved from a `MetaEnum::Element`
 
 ```ruby
-v = ColorType[:red] # => #<MetaEnum::Value: 0 => red}>
-v.number # => 0
+v = ColorType[:red] # => #<MetaEnum::Element: 0 => red}>
+v.value # => 0
 v.name # => :red
 ```
 
@@ -75,6 +75,15 @@ AgeType = MetaEnum::Type.new(child: [0, "Less than 18"], adult: [1, "At least 18
 AgeType[:child].data # => "Less than 18"
 ```
 
+Non-integer values can be enabled by passing a value_normalizer to `MetaEnum::Type.new`. For example, to use string values:
+
+```ruby
+CardType = MetaEnum::Type.new({visa: "VS", mastercard: "MC", discover: "DS"}, value_normalizer: method(:String))
+CardType[:visa] # => #<MetaEnum::Element: visa: "VS", data: nil>
+CardType["VS"] # => #<MetaEnum::Element: visa: "VS", data: nil>
+pry(main)> CardType["VS"].value # => "VS"
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/meta_enum/{value.rb → element.rb}

@@ -1,9 +1,9 @@
 module MetaEnum
-  class Value
-    attr_reader :number, :name, :data, :type
+  class Element
+    attr_reader :value, :name, :data, :type
 
-    def initialize(number, name, data, type)
-      @number = Integer(number)
+    def initialize(value, name, data, type)
+      @value = value
       @name = name.to_sym
       @data = data
       @type = type
@@ -18,11 +18,10 @@ module MetaEnum
       false
     end
 
-    def to_i; number; end
     def to_s; name.to_s; end
 
     def inspect
-      "#<#{self.class}: #{name}: #{number}, data: #{data.inspect}>"
+      "#<#{self.class}: #{name}: #{value.inspect}, data: #{data.inspect}>"
     end
   end
 end

data/lib/meta_enum/{missing_value.rb → missing_element.rb}

@@ -1,9 +1,9 @@
 module MetaEnum
-  class MissingValue
-    attr_reader :number, :type
+  class MissingElement
+    attr_reader :value, :type
 
-    def initialize(number, type)
-      @number = Integer(number)
+    def initialize(value, type)
+      @value = value
       @type = type
       freeze
     end
@@ -13,18 +13,17 @@ module MetaEnum
 
     def ==(other)
       other = type[other]
-      number == other.number && type == other.type
+      value == other.value && type == other.type
 
     # type[] will raise for certain bad keys. Those are obviously not equal so return false.
     rescue ArgumentError, KeyError
       false
     end
 
-    def to_i; number; end
     def to_s; name.to_s; end
 
     def inspect
-      "#<#{self.class}: #{number}}>"
+      "#<#{self.class}: #{value.inspect}}>"
     end
   end
 end

data/lib/meta_enum/type.rb

@@ -1,75 +1,104 @@
 require 'set'
 
 module MetaEnum
+
+  # ValueNormalizationError is raised on when a value normalization fails. It wraps the underlying exception.
+  class ValueNormalizationError < StandardError
+    attr_reader :original_exception, :original_value
+
+    def initialize(original_exception, original_value)
+      @original_exception = original_exception
+      @original_value = original_value
+    end
+
+    def to_s
+      "original_exception: #{original_exception}, original_value: #{original_value}"
+    end
+  end
+
   class Type
-    attr_reader :values, :values_by_number, :values_by_name
+    attr_reader :elements, :elements_by_value, :elements_by_name
 
-    # Initialize takes a single hash of name to number.
+    # Initialize takes a single hash of name to value.
     #
     # e.g. MetaEnum::Type.new(red: 0, green: 1, blue: 2)
     #
     # Additional data can also be associated with each value by passing an array
-    # of [number, extra data]. This can be used for additional description or
+    # of [value, extra data]. This can be used for additional description or
     # any other reason.
     #
     # e.g. MetaEnum::Type.new(small: [0, "Less than 10], large: [1, "At least 10"]
-    def initialize(values)
-      @values_by_number = {}
-      @values_by_name = {}
-      @values = Set.new
+    #
+    # value_normalizer is a callable object that normalizes values. The default
+    # converts all values to integers. To allow string values use method(:String).
+    def initialize(
+      elements,
+      value_normalizer: method(:Integer)
+    )
+      @value_normalizer = value_normalizer
+      @elements_by_value = {}
+      @elements_by_name = {}
+      @elements = Set.new
 
-      values.each do |name, number_and_data|
-        number_and_data = Array(number_and_data)
-        v = Value.new number_and_data[0], name, number_and_data[1], self
-        raise ArgumentError, "duplicate number: #{v.number}" if @values_by_number.key? v.number
-        raise ArgumentError, "duplicate name: #{v.name}" if @values_by_name.key? v.name
-        @values_by_number[v.number] = v
-        @values_by_name[v.name] = v
-        @values.add(v)
+      elements.each do |name, value_and_data|
+        value_and_data = Array(value_and_data)
+        v = Element.new normalize_value(value_and_data[0]), name, value_and_data[1], self
+        raise ArgumentError, "duplicate value: #{v.value}" if @elements_by_value.key? v.value
+        raise ArgumentError, "duplicate name: #{v.name}" if @elements_by_name.key? v.name
+        @elements_by_value[v.value] = v
+        @elements_by_name[v.name] = v
+        @elements.add(v)
       end
 
-      @values_by_number.freeze
-      @values_by_name.freeze
-      @values.freeze
+      @elements_by_value.freeze
+      @elements_by_name.freeze
+      @elements.freeze
       freeze
     end
 
-    # [] is a "do what I mean" operator. It returns the Value from this type depending on the key.
+    # [] is a "do what I mean" operator. It returns the Element from this type depending on the key.
     #
-    # When key is a symbol, it is considered the name of the Value to return.
+    # When key is a symbol, it is considered the name of the Element to return.
     # Since symbols are used from number, it is considered an error if the key is
     # not found and it raises an exception.
     #
     # When key can be converted to an integer by Integer(), then it is
-    # considered the number of the Value to return. Retrieving by number is
+    # considered the number of the Element to return. Retrieving by number is
     # presumed to converting from external data where a missing value should not
-    # be considered fatal. In this case it returns a MissingValue is with number
+    # be considered fatal. In this case it returns a MissingElement is with number
     # as the key. This allows a Type to only specify the values is needs while
     # passing through the others unmodified.
     #
-    # Finally, when key is a MetaEnum::Value, it is simply returned (unless it
+    # Finally, when key is a MetaEnum::Element, it is simply returned (unless it
     # belongs to a different Type in which case an ArgumentError is raised).
     #
     # See #values_by_number and #values_by_name for non-fuzzy value selection.
     def [](key)
       case key
-      when Value, MissingValue
+      when Element, MissingElement
         raise ArgumentError, "wrong type" unless key.type == self
         key
       when Symbol
-        values_by_name.fetch(key)
+        elements_by_name.fetch(key)
       else
-        key = Integer(key)
-        values_by_number.fetch(key) { MissingValue.new key, self }
+        key = normalize_value(key)
+        elements_by_value.fetch(key) { MissingElement.new key, self }
       end
     end
 
     def inspect
-      sprintf('#<%s: {%s}>', self.class, values.to_a.map { |v| "#{v.name}: #{v.number}"}.join(", "))
+      sprintf('#<%s: {%s}>', self.class, elements.to_a.map { |v| "#{v.name}: #{v.number}"}.join(", "))
     end
 
     def size
-      values.size
+      elements.size
+    end
+
+  private
+    def normalize_value(value)
+      @value_normalizer.call(value)
+    rescue StandardError => e
+      raise ValueNormalizationError.new(e, value)
     end
   end
 end

data/lib/meta_enum/version.rb

@@ -1,3 +1,3 @@
 module MetaEnum
-  VERSION = "1.0.0"
+  VERSION = "2.0.0"
 end

data/lib/meta_enum.rb

@@ -1,4 +1,4 @@
 require "meta_enum/version"
 require 'meta_enum/type.rb'
-require 'meta_enum/value.rb'
-require 'meta_enum/missing_value.rb'
+require 'meta_enum/element.rb'
+require 'meta_enum/missing_element.rb'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: meta_enum
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Jack Christensen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-01-26 00:00:00.000000000 Z
+date: 2018-01-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -75,6 +75,7 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".travis.yml"
+- CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
@@ -83,9 +84,9 @@ files:
 - bin/console
 - bin/setup
 - lib/meta_enum.rb
-- lib/meta_enum/missing_value.rb
+- lib/meta_enum/element.rb
+- lib/meta_enum/missing_element.rb
 - lib/meta_enum/type.rb
-- lib/meta_enum/value.rb
 - lib/meta_enum/version.rb
 - meta_enum.gemspec
 homepage: https://github.com/ccsalespro/meta_enum