typesafe_enum 0.1.8 → 0.3.0

data/.ruby-version

@@ -1 +1 @@
-2.4.1
+2.6.6

data/.travis.yml

@@ -1,2 +1,9 @@
 language: ruby
 
+os:
+  - linux
+  - osx
+
+rvm:
+  - 2.6
+  - 2.7

data/CHANGES.md

@@ -1,3 +1,26 @@
+## 0.3.0
+
+- Support explicit nil values
+- Update author email in gemspec
+- Update RuboCop to version 0.91 and pin version
+- Set minimum required_ruby_version to 2.6.0
+- Bump .ruby-version to 2.6.6
+
+## 0.2.2 (23 April 2020)
+
+- Implement [`Enumerable`](https://ruby-doc.org/core-2.6.5/Enumerable.html)
+
+## 0.2.1 (12 March 2020)
+
+- Update to Rake 12.3.3
+
+## 0.2.0 (12 March 2020)
+
+- Update to Ruby 2.6.5
+- Update to Rake 10.4
+- Update to RSpec 3.9
+- Update to RuboCop 0.80
+
 ## 0.1.8 (22 December 2017)
 
 - Update to Ruby 2.4.1

data/README.md

@@ -1,9 +1,9 @@
 # TypesafeEnum
 
-[![Build Status](https://travis-ci.org/dmolesUC3/typesafe_enum.svg?branch=master)](https://travis-ci.org/dmolesUC3/typesafe_enum)
-[![Code Climate](https://codeclimate.com/github/dmolesUC3/typesafe_enum.svg)](https://codeclimate.com/github/dmolesUC3/typesafe_enum)
-[![Inline docs](http://inch-ci.org/github/dmolesUC3/typesafe_enum.svg)](http://inch-ci.org/github/dmolesUC3/typesafe_enum)
-[![Gem Version](https://img.shields.io/gem/v/typesafe_enum.svg)](https://github.com/dmolesUC3/typesafe_enum/releases)
+[![Build Status](https://travis-ci.org/dmolesUC/typesafe_enum.svg?branch=master)](https://travis-ci.org/dmolesUC/typesafe_enum)
+[![Code Climate](https://codeclimate.com/github/dmolesUC/typesafe_enum.svg)](https://codeclimate.com/github/dmolesUC/typesafe_enum)
+[![Inline docs](http://inch-ci.org/github/dmolesUC/typesafe_enum.svg)](http://inch-ci.org/github/dmolesUC/typesafe_enum)
+[![Gem Version](https://img.shields.io/gem/v/typesafe_enum.svg)](https://github.com/dmolesUC/typesafe_enum/releases)
 
 A Ruby implementation of Joshua Bloch's
 [typesafe enum pattern](http://www.oracle.com/technetwork/java/page1-139488.html#replaceenums),
@@ -14,23 +14,25 @@ with syntax loosely inspired by [Ruby::Enum](https://github.com/dblock/ruby-enum
 - [Basic usage](#basic-usage)
 - [Ordering](#ordering)
 - [String representations](#string-representations)
+- [Enumerable](#enumerable)
 - [Convenience methods on enum classes](#convenience-methods-on-enum-classes)
-    - [::to\_a](#to_a)
-    - [::size](#size)
-    - [::each, ::each\_with\_index, and ::map](#each-each_with_index-and-map)
-    - [::find\_by\_key, ::find\_by\_value, ::find\_by\_ord](#find_by_key-find_by_value-find_by_ord)
-    - [::find\_by\_value\_str](#find_by_value_str)
+   - [#to_a](#to_a)
+   - [#size](#size)
+   - [#each, <code>#each_with_index</code>, <code>#map</code> and <code>#flat_map</code>](#each-each_with_index-map-and-flat_map)
+   - [#find_by_key, <code>#find_by_value</code>, <code>#find_by_ord</code>](#find_by_key-find_by_value-find_by_ord)
+   - [#find_by_value_str](#find_by_value_str)
 - [Enum classes with methods](#enum-classes-with-methods)
 - [Enum instances with methods](#enum-instances-with-methods)
-- [How is this different from Ruby::Enum?](#how-is-this-different-from-rubyenum)
+- [How is this different from <a href="https://github.com/dblock/ruby-enum">Ruby::Enum</a>?](#how-is-this-different-from-rubyenum)
 - [How is this different from java.lang.Enum?](#how-is-this-different-from-javalangenum)
-    - [Clunkier syntax](#clunkier-syntax)
-    - [No special switch/case support](#no-special-switchcase-support)
-    - [No serialization support](#no-serialization-support)
-    - [No support classes](#no-support-classes)
-    - [Enum classes are not closed](#enum-classes-are-not-closed)
+   - [Clunkier syntax](#clunkier-syntax)
+   - [No special switch/<code>case</code> support](#no-special-switchcase-support)
+   - [No serialization support](#no-serialization-support)
+   - [No support classes](#no-support-classes)
+   - [Enum classes are not closed](#enum-classes-are-not-closed)
 - [Contributing](#contributing)
 
+
 ## Basic usage
 
 Create a new enum class and a set of instances:
@@ -91,6 +93,20 @@ Scale::KILO.value
 # => 1000
 ```
 
+Even `nil` is a valid value (if set explicitly):
+
+```ruby
+class Scheme < TypesafeEnum::Base
+  new :HTTP, 'http'
+  new :HTTPS, 'https'
+  new :EXAMPLE, 'example'
+  new :UNKNOWN, nil
+end
+
+Scheme::UNKNOWN.value
+# => nil
+```
+
 Declaring two instances with the same key will produce an error:
 
 ```ruby
@@ -199,9 +215,19 @@ Suit::DIAMONDS.to_s
 
 It can of course be overridden.
 
+## `Enumerable`
+
+As of version 0.2.2, `TypesafeEnum` classes implement
+[`Enumerable`](https://ruby-doc.org/core-2.6.5/Enumerable.html),
+so they support methods such as
+[`#find`](https://ruby-doc.org/core-2.6.5/Enumerable.html#method-i-find),
+[`#select`](https://ruby-doc.org/core-2.6.5/Enumerable.html#method-i-select), 
+and  [`#reduce`](https://ruby-doc.org/core-2.6.5/Enumerable.html#method-i-reduce),
+in addition to the convenience methods called out specifically below.
+
 ## Convenience methods on enum classes
 
-### `::to_a`
+### `#to_a`
 
 Returns an array of the enum instances in declaration order:
 
@@ -210,7 +236,7 @@ Tarot.to_a
 # => [#<Tarot:0x007fd4db30eca8 @key=:CUPS, @value="Cups", @ord=0>, #<Tarot:0x007fd4db30ebe0 @key=:COINS, @value="Coins", @ord=1>, #<Tarot:0x007fd4db30eaf0 @key=:WANDS, @value="Wands", @ord=2>, #<Tarot:0x007fd4db30e9b0 @key=:SWORDS, @value="Swords", @ord=3>]
 ```
 
-### `::size`
+### `#size`
 
 Returns the number of enum instances:
 
@@ -219,7 +245,7 @@ Suit.size
 # => 4
 ```
 
-### `::each`, `::each_with_index`, and `::map`
+### `#each`, `#each_with_index`, `#map` and `#flat_map`
 
 Iterate over the set of enum instances:
 
@@ -238,9 +264,12 @@ Suit.each_with_index { |s, i| puts "#{i}: #{s.key}" }
 
 Suit.map(&:value)
 # => ["clubs", "diamonds", "hearts", "spades"]
+
+Suit.flat_map { |s| [s.key, s.value] }
+# => [:CLUBS, "clubs", :DIAMONDS, "diamonds", :HEARTS, "hearts", :SPADES, "spades"]
 ```
 
-### `::find_by_key`, `::find_by_value`, `::find_by_ord`
+### `#find_by_key`, `#find_by_value`, `#find_by_ord`
 
 Look up an enum instance based on its key, value, or ordinal:
 
@@ -253,7 +282,7 @@ Tarot.find_by_ord(3)
 # => #<Tarot:0x007faab19fd810 @key=:SWORDS, @value="Swords", @ord=3>
 ```
 
-### `::find_by_value_str`
+### `#find_by_value_str`
 
 Look up an enum instance based on the string form of its value (as returned by `to_s`) --
 useful for, e.g., XML or JSON mapping of enums with non-string values:

data/lib/typesafe_enum.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TypesafeEnum
-  Dir.glob(File.expand_path('../typesafe_enum/*.rb', __FILE__)).sort.each(&method(:require))
+  Dir.glob(File.expand_path('typesafe_enum/*.rb', __dir__)).sort.each(&method(:require))
 end

data/lib/typesafe_enum/base.rb

@@ -8,6 +8,7 @@ module TypesafeEnum
     include Comparable
 
     class << self
+      include Enumerable
 
       # Returns an array of the enum instances in declaration order
       # @return [Array<self>] All instances of this enum, in declaration order
@@ -18,32 +19,16 @@ module TypesafeEnum
       # Returns the number of enum instances
       # @return [Integer] the number of instances
       def size
-        as_array ? as_array.length : 0
+        as_array.size
       end
 
       # Iterates over the set of enum instances
       # @yield [self] Each instance of this enum, in declaration order
-      # @return [Array<self>] All instances of this enum, in declaration order
+      # @return [Enumerator<self>] All instances of this enum, in declaration order
       def each(&block)
         to_a.each(&block)
       end
 
-      # Iterates over the set of enum instances
-      # @yield [self, Integer] Each instance of this enum, in declaration order,
-      #   with its ordinal index
-      # @return [Array<self>] All instances of this enum, in declaration order
-      def each_with_index(&block)
-        to_a.each_with_index(&block)
-      end
-
-      # Iterates over the set of enum instances
-      # @yield [self] Each instance of this enum, in declaration order
-      # @return [Array] An array containing the result of applying `&block`
-      #   to each instance of this enum, in instance declaration order
-      def map(&block)
-        to_a.map(&block)
-      end
-
       # Looks up an enum instance based on its key
       # @param key [Symbol] the key to look up
       # @return [self, nil] the corresponding enum instance, or nil
@@ -71,6 +56,7 @@ module TypesafeEnum
       # @return [self, nil] the corresponding enum instance, or nil
       def find_by_ord(ord)
         return nil if ord > size || ord.negative?
+
         as_array[ord]
       end
 
@@ -93,21 +79,37 @@ module TypesafeEnum
       end
 
       def valid_key_and_value(instance)
+        return unless (key = valid_key(instance))
+
+        [key, valid_value(instance)]
+      end
+
+      def valid_key(instance)
         key = instance.key
+        return key unless (found = find_by_key(key))
+
         value = instance.value
-        if (found = find_by_key(key))
-          raise NameError, "#{name}::#{key} already exists" unless value == found.value
-          warn("ignoring redeclaration of #{name}::#{key} with value #{value} (source: #{caller(5..5).first})")
-          nil
-        else
-          raise NameError, "A #{name} instance with value '#{value}' already exists" if find_by_value(value)
-          [key, value]
-        end
+        raise NameError, "#{name}::#{key} already exists with value #{found.value.inspect}" unless value == found.value
+
+        warn("ignoring redeclaration of #{name}::#{key} with value #{value.inspect} (source: #{caller(6..6).first})")
+      end
+
+      def valid_value(instance)
+        value = instance.value
+        return value unless (found = find_by_value(value))
+
+        key = instance.key
+        raise NameError, "A #{name} instance with value #{value.inspect} already exists: #{found.key}" unless key == found.key
+
+        # valid_key() should already have warned us, and valid_key_and_value() should have exited early, but just in case
+        # :nocov:
+        warn("ignoring redeclaration of #{name}::#{key} with value #{value.inspect} (source: #{caller(6..6).first})")
+        # :nocov:
       end
 
       def register(instance)
         key, value = valid_key_and_value(instance)
-        return unless key && value
+        return unless key
 
         const_set(key.to_s, instance)
         by_key[key] = instance
@@ -150,15 +152,19 @@ module TypesafeEnum
     end
 
     def to_s
-      "#{self.class}::#{key} [#{ord}] -> #{value}"
+      "#{self.class}::#{key} [#{ord}] -> #{value.inspect}"
     end
 
     private
 
-    def initialize(key, value = nil, &block)
+    IMPLICIT = Class.new.new
+    private_constant :IMPLICIT
+
+    def initialize(key, value = IMPLICIT, &block)
       raise TypeError, "#{key} is not a symbol" unless key.is_a?(Symbol)
+
       @key = key
-      @value = value || key.to_s.downcase
+      @value = value == IMPLICIT ? key.to_s.downcase : value
       @ord = self.class.size
       self.class.class_exec(self) do |instance|
         register(instance)

data/lib/typesafe_enum/module_info.rb

@@ -5,8 +5,8 @@ module TypesafeEnum
   NAME = 'typesafe_enum'
 
   # The version of this gem
-  VERSION = '0.1.8'
+  VERSION = '0.3.0'
 
   # The copyright notice for this gem
-  COPYRIGHT = 'Copyright (c) 2017 The Regents of the University of California'
+  COPYRIGHT = 'Copyright (c) 2020 The Regents of the University of California'
 end

data/spec/.rubocop.yml

@@ -1,16 +1,19 @@
 inherit_from: ../.rubocop.yml
 
-Metrics/BlockLength:
+Lint/ConstantDefinitionInBlock:
   Enabled: false
 
-Metrics/MethodLength:
+Style/ClassAndModuleChildren:
   Enabled: false
 
-Metrics/ModuleLength:
+Metrics/AbcSize:
   Enabled: false
 
-Style/ClassAndModuleChildren:
+Metrics/BlockLength:
   Enabled: false
 
-Security/MarshalLoad:
+Metrics/ModuleLength:
+  Enabled: false
+
+Metrics/MethodLength:
   Enabled: false

data/spec/unit/typesafe_enum/base_spec.rb

@@ -1,4 +1,3 @@
-
 # frozen_string_literal: true
 
 require 'spec_helper'
@@ -30,15 +29,31 @@ class Scale < TypesafeEnum::Base
   new :MEGA, 1_000_000
 end
 
+class Scheme < TypesafeEnum::Base
+  new :HTTP, 'http'
+  new :HTTPS, 'https'
+  new :EXAMPLE, 'example'
+  new :UNKNOWN, nil
+end
+
 module TypesafeEnum
   describe Base do
 
-    describe '::new' do
-      it ' news a constant enum value' do
+    describe :new do
+      it 'news a constant enum value' do
         enum = Suit::CLUBS
         expect(enum).to be_a(Suit)
       end
 
+      it 'allows nil values' do
+        expect do
+          class ::NilValues < Base
+            new :NONE, nil
+          end
+        end.not_to raise_error
+        expect(::NilValues.to_a).not_to be_empty
+      end
+
       it 'insists symbols be symbols' do
         expect do
           class ::StringKeys < Base
@@ -81,6 +96,18 @@ module TypesafeEnum
         expect(::DuplicateValues.find_by_key(:ALSO_SPADES)).to be_nil
       end
 
+      it 'disallows duplicate nil values' do
+        expect do
+          class ::DuplicateNilValues < Base
+            new :NONE, nil
+            new :NULL, nil
+          end.to raise_error(NameError)
+          expect(::DuplicateNilValues.to_a).to eq([::DuplicateNilValues::NONE])
+          expect(::DuplicateNilValues::NONE.value).to be_nil
+          expect(::DuplicateNilValues.find_by_key(:NULL)).to be_nil
+        end
+      end
+
       it 'disallows nil keys' do
         expect do
           class ::NilKeys < Base
@@ -94,7 +121,8 @@ module TypesafeEnum
         class ::IdenticalInstances < Base
           new :SPADES, 'spades'
         end
-        expect(::IdenticalInstances).to receive(:warn).with(a_string_matching(/ignoring redeclaration of IdenticalInstances::SPADES with value spades/))
+        expected_msg = /ignoring redeclaration of IdenticalInstances::SPADES with value "spades" \(source: .*base_spec.rb:[0-9]+:in `new'\)/
+        expect(::IdenticalInstances).to receive(:warn).once.with(expected_msg)
         class ::IdenticalInstances < Base
           new :SPADES, 'spades'
         end
@@ -113,7 +141,7 @@ module TypesafeEnum
       end
     end
 
-    describe '::to_a' do
+    describe :to_a do
       it 'returns the values as an array' do
         expect(Suit.to_a).to eq([Suit::CLUBS, Suit::DIAMONDS, Suit::HEARTS, Suit::SPADES])
       end
@@ -125,13 +153,27 @@ module TypesafeEnum
       end
     end
 
-    describe '::size' do
+    describe :size do
       it 'returns the number of enum instnaces' do
         expect(Suit.size).to eq(4)
       end
     end
 
-    describe '::each' do
+    describe :count do
+      it 'returns the number of enum instnaces' do
+        expect(Suit.count).to eq(4)
+      end
+
+      it 'counts items' do
+        expect(Suit.count(Suit::SPADES)).to eq(1)
+      end
+
+      it 'counts items that match a predicate' do
+        expect(Suit.count { |s| s.value.length == 6 }).to eq(2)
+      end
+    end
+
+    describe :each do
       it 'iterates the enum values' do
         expected = [Suit::CLUBS, Suit::DIAMONDS, Suit::HEARTS, Suit::SPADES]
         index = 0
@@ -142,7 +184,7 @@ module TypesafeEnum
       end
     end
 
-    describe '::each_with_index' do
+    describe :each_with_index do
       it 'iterates the enum values with indices' do
         expected = [Suit::CLUBS, Suit::DIAMONDS, Suit::HEARTS, Suit::SPADES]
         Suit.each_with_index do |s, index|
@@ -151,14 +193,21 @@ module TypesafeEnum
       end
     end
 
-    describe '::map' do
+    describe :map do
       it 'maps enum values' do
         all_keys = Suit.map(&:key)
         expect(all_keys).to eq(%i[CLUBS DIAMONDS HEARTS SPADES])
       end
     end
 
-    describe '#<=>' do
+    describe :flat_map do
+      it 'flatmaps enum values' do
+        result = Tarot.flat_map { |t| [t.key, t.value] }
+        expect(result).to eq([:CUPS, 'Cups', :COINS, 'Coins', :WANDS, 'Wands', :SWORDS, 'Swords'])
+      end
+    end
+
+    describe :<=> do
       it 'orders enum instances' do
         Suit.each_with_index do |s1, i1|
           Suit.each_with_index do |s2, i2|
@@ -168,7 +217,7 @@ module TypesafeEnum
       end
     end
 
-    describe '#==' do
+    describe :== do
       it 'returns true for identical instances, false otherwise' do
         Suit.each do |s1|
           Suit.each do |s2|
@@ -190,6 +239,7 @@ module TypesafeEnum
         end
       end
 
+      # rubocop:disable Security/MarshalLoad
       it 'survives marshalling' do
         Suit.each do |s1|
           dump = Marshal.dump(s1)
@@ -198,9 +248,10 @@ module TypesafeEnum
           expect(s2 == s1).to eq(true)
         end
       end
+      # rubocop:enable Security/MarshalLoad
     end
 
-    describe '#!=' do
+    describe :!= do
       it 'returns false for identical instances, true otherwise' do
         Suit.each do |s1|
           Suit.each do |s2|
@@ -222,7 +273,7 @@ module TypesafeEnum
       end
     end
 
-    describe '#hash' do
+    describe :hash do
       it 'gives consistent values' do
         Suit.each do |s1|
           Suit.each do |s2|
@@ -245,6 +296,7 @@ module TypesafeEnum
         end
       end
 
+      # rubocop:disable Security/MarshalLoad
       it 'survives marshalling' do
         Suit.each do |s1|
           dump = Marshal.dump(s1)
@@ -252,6 +304,7 @@ module TypesafeEnum
           expect(s2.hash).to eq(s1.hash)
         end
       end
+      # rubocop:enable Security/MarshalLoad
 
       it 'always returns a Fixnum' do
         Suit.each do |s1|
@@ -260,7 +313,7 @@ module TypesafeEnum
       end
     end
 
-    describe '#eql?' do
+    describe :eql? do
       it 'is consistent with #hash' do
         Suit.each do |s1|
           Suit.each do |s2|
@@ -270,16 +323,30 @@ module TypesafeEnum
       end
     end
 
-    describe '#value' do
+    describe :value do
       it 'returns the string value of the enum instance' do
         expected = %w[clubs diamonds hearts spades]
         Suit.each_with_index do |s, index|
           expect(s.value).to eq(expected[index])
         end
       end
+
+      it 'returns an explicit value' do
+        expected = [10, 100, 1000, 1_000_000]
+        Scale.each_with_index do |s, index|
+          expect(s.value).to eq(expected[index])
+        end
+      end
+
+      it 'supports nil values' do
+        expected = ['http', 'https', 'example', nil]
+        Scheme.each_with_index do |s, index|
+          expect(s.value).to eq(expected[index])
+        end
+      end
     end
 
-    describe '#key' do
+    describe :key do
       it 'returns the symbol key of the enum instance' do
         expected = %i[CLUBS DIAMONDS HEARTS SPADES]
         Suit.each_with_index do |s, index|
@@ -288,7 +355,7 @@ module TypesafeEnum
       end
     end
 
-    describe '#ord' do
+    describe :ord do
       it 'returns the ord value of the enum instance' do
         Suit.each_with_index do |s, index|
           expect(s.ord).to eq(index)
@@ -296,13 +363,13 @@ module TypesafeEnum
       end
     end
 
-    describe '#to_s' do
+    describe :to_s do
       it 'provides an informative string' do
         aggregate_failures 'informative string' do
-          [Suit, Tarot, RGBColor, Scale].each do |ec|
+          [Suit, Tarot, RGBColor, Scale, Scheme].each do |ec|
             ec.each do |ev|
               result = ev.to_s
-              [ec.to_s, ev.key, ev.ord, ev.value].each do |info|
+              [ec.to_s, ev.key, ev.ord, ev.value.inspect].each do |info|
                 expect(result).to include(info.to_s)
               end
             end
@@ -311,7 +378,7 @@ module TypesafeEnum
       end
     end
 
-    describe '::find_by_key' do
+    describe :find_by_key do
       it 'maps symbol keys to enum instances' do
         keys = %i[CLUBS DIAMONDS HEARTS SPADES]
         expected = Suit.to_a
@@ -325,7 +392,7 @@ module TypesafeEnum
       end
     end
 
-    describe '::find_by_value' do
+    describe :find_by_value do
       it 'maps values to enum instances' do
         values = %w[clubs diamonds hearts spades]
         expected = Suit.to_a
@@ -349,9 +416,15 @@ module TypesafeEnum
           expect(Scale.find_by_value(s.value)).to be(s)
         end
       end
+
+      it 'supports enums with explicit nil values' do
+        Scheme.each do |s|
+          expect(Scheme.find_by_value(s.value)).to be(s)
+        end
+      end
     end
 
-    describe '::find_by_value_str' do
+    describe :find_by_value_str do
       it 'maps string values to enum instances' do
         values = %w[clubs diamonds hearts spades]
         expected = Suit.to_a
@@ -375,9 +448,15 @@ module TypesafeEnum
           expect(Scale.find_by_value_str(s.value.to_s)).to be(s)
         end
       end
+
+      it 'supports enums with explicit nil values' do
+        Scheme.each do |s|
+          expect(Scheme.find_by_value(s.value)).to be(s)
+        end
+      end
     end
 
-    describe '::find_by_ord' do
+    describe :find_by_ord do
       it 'maps ordinal indices to enum instances' do
         Suit.each do |s|
           expect(Suit.find_by_ord(s.ord)).to be(s)
@@ -432,5 +511,9 @@ module TypesafeEnum
 
       expect(Operation.map { |op| op.eval(39, 23) }).to eq([39 + 23, 39 - 23])
     end
+
+    it 'is an Enumerable' do
+      expect(Suit).to be_an(Enumerable)
+    end
   end
 end