type_is_enum 0.2.0

data/Rakefile

@@ -0,0 +1,49 @@
+# ------------------------------------------------------------
+# RSpec
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+namespace :spec do
+
+  desc 'Run all unit tests'
+  RSpec::Core::RakeTask.new(:unit) do |task|
+    task.rspec_opts = %w(--color --format documentation --order default)
+    task.pattern = 'unit/**/*_spec.rb'
+  end
+
+  task all: [:unit]
+end
+
+desc 'Run all tests'
+task spec: 'spec:all'
+
+# ------------------------------------------------------------
+# Coverage
+
+desc 'Run all unit tests with coverage'
+task :coverage do
+  ENV['COVERAGE'] = 'true'
+  Rake::Task['spec:unit'].execute
+end
+
+# ------------------------------------------------------------
+# RuboCop
+
+require 'rubocop/rake_task'
+RuboCop::RakeTask.new
+
+# ------------------------------------------------------------
+# TODOs
+
+desc 'List TODOs (from spec/todo.rb)'
+RSpec::Core::RakeTask.new(:todo) do |task|
+  task.rspec_opts = %w(--color --format documentation --order default)
+  task.pattern = 'todo.rb'
+end
+
+# ------------------------------------------------------------
+# Defaults
+
+desc 'Run unit tests, check test coverage, run acceptance tests, check code style'
+task default: [:coverage, :rubocop]

data/lib/type_is_enum.rb

@@ -0,0 +1,3 @@
+module TypeIsEnum
+  Dir.glob(File.expand_path('../type_is_enum/*.rb', __FILE__)).sort.each(&method(:require))
+end

data/lib/type_is_enum/enum.rb

@@ -0,0 +1,137 @@
+# A Ruby implementation of Joshua Bloch's
+# [typesafe enum pattern](http://www.oracle.com/technetwork/java/page1-139488.html#replaceenums)
+module TypeIsEnum
+  # Base class for typesafe enum classes.
+  class Enum
+    include Comparable
+
+    class << self
+
+      # Returns an array of the enum instances in declaration order
+      # @return [Array<self>] All instances of this enum, in declaration order
+      def to_a
+        as_array.dup
+      end
+
+      # Returns the number of enum instances
+      # @return [Integer] the number of instances
+      def size
+        as_array ? as_array.length : 0
+      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
+      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
+      def find_by_key(key)
+        by_key[key]
+      end
+
+      # Looks up an enum instance based on its ordinal
+      # @param ord [Integer] the ordinal to look up
+      # @return [self, nil] the corresponding enum instance, or nil
+      def find_by_ord(ord)
+        return nil if ord < 0 || ord > size
+        as_array[ord]
+      end
+
+      private
+
+      def add(key, *args, &block)
+        fail TypeError, "#{key} is not a symbol" unless key.is_a?(Symbol)
+        obj = new(*args)
+        obj.instance_variable_set :@key, key
+        obj.instance_variable_set :@ord, size
+        class_exec(obj) do |instance|
+          register(instance)
+          instance.instance_eval(&block) if block_given?
+        end
+      end
+
+      def by_key
+        @by_key ||= {}
+      end
+
+      def as_array
+        @as_array ||= []
+      end
+
+      def valid_key(instance)
+        key = instance.key
+        if find_by_key(key)
+          warn("ignoring redeclaration of #{name}::#{key} (source: #{caller[4]})")
+          nil
+        else
+          key
+        end
+      end
+
+      def register(instance)
+        key = valid_key(instance)
+        return unless key
+
+        const_set(key.to_s, instance)
+        by_key[key] = instance
+        as_array << instance
+      end
+    end
+
+    # The symbol key for the enum instance
+    # @return [Symbol] the key
+    attr_reader :key
+
+    # The ordinal of the enum instance, in declaration order
+    # @return [Integer] the ordinal
+    attr_reader :ord
+
+    # Compares two instances of the same enum class based on their declaration order
+    # @param other [self] the enum instance to compare
+    # @return [Integer, nil] -1 if this value precedes `other`; 0 if the two are
+    #   the same enum instance; 1 if this value follows `other`; `nil` if `other`
+    #   is not an instance of this enum class
+    def <=>(other)
+      ord <=> other.ord if self.class == other.class
+    end
+
+    # Generates a Fixnum hash value for this enum instance
+    # @return [Fixnum] the hash value
+    def hash
+      @hash ||= begin
+        result = 17
+        result = 31 * result + self.class.hash
+        result = 31 * result + ord
+        result.is_a?(Fixnum) ? result : result.hash
+      end
+    end
+
+    def name
+      key.to_s
+    end
+
+    def to_s
+      "#{self.class}::#{key} [#{ord}]"
+    end
+  end
+end

data/lib/type_is_enum/module_info.rb

@@ -0,0 +1,10 @@
+module TypeIsEnum
+  # The name of this gem
+  NAME = 'type_is_enum'
+
+  # The version of this gem
+  VERSION = '0.2.0'
+
+  # The copyright notice for this gem
+  COPYRIGHT = 'Copyright (c) 2016 The Regents of the University of California, Andrew Shcheglov'
+end

data/lib/type_is_enum/value_enum.rb

@@ -0,0 +1,9 @@
+module TypeIsEnum
+  class ValueEnum < Enum
+    def initialize(value)
+      @value = value
+    end
+
+    attr_reader :value
+  end
+end

data/spec/.rubocop.yml

@@ -0,0 +1,10 @@
+inherit_from: ../.rubocop.yml
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  Enabled: false

data/spec/spec_helper.rb

@@ -0,0 +1,31 @@
+# ------------------------------------------------------------
+# SimpleCov setup
+
+if ENV['COVERAGE']
+  require 'simplecov'
+  require 'simplecov-console'
+
+  SimpleCov.minimum_coverage 100
+  SimpleCov.start do
+    add_filter '/spec/'
+    SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter[
+      SimpleCov::Formatter::HTMLFormatter,
+      SimpleCov::Formatter::Console,
+    ]
+  end
+end
+
+# ------------------------------------------------------------
+# Rspec configuration
+
+require 'rspec'
+
+RSpec.configure do |config|
+  config.raise_errors_for_deprecations!
+  config.mock_with :rspec
+end
+
+# ------------------------------------------------------------
+# TypesafeEnum
+
+require 'type_is_enum'

data/spec/unit/type_is_enum/enum_spec.rb

@@ -0,0 +1,367 @@
+# coding: utf-8
+require 'spec_helper'
+
+class Suit < TypeIsEnum::Enum
+  add :CLUBS
+  add :DIAMONDS
+  add :HEARTS
+  add :SPADES
+end
+
+class Tarot < TypeIsEnum::ValueEnum
+  add :CUPS, 'Cups'
+  add :COINS, 'Coins'
+  add :WANDS, 'Wands'
+  add :SWORDS, 'Swords'
+end
+
+class RGBColor < TypeIsEnum::ValueEnum
+  add :RED, :red
+  add :GREEN, :green
+  add :BLUE, :blue
+end
+
+class Scale < TypeIsEnum::ValueEnum
+  add :DECA, 10
+  add :HECTO, 100
+  add :KILO, 1_000
+  add :MEGA, 1_000_000
+end
+
+class Car < TypeIsEnum::Enum
+  def initialize(price, coolness)
+    @price = price
+    @coolness = coolness
+  end
+
+  attr_reader :price, :coolness
+
+  add :Audi, 25_000, 4
+  add :Mercedes, 30_000, 6
+  add :Toyota, 10_000, 2
+end
+
+module TypeIsEnum
+  describe Enum do
+
+    it 'allows custom constructors with multiple arguments' do
+      expect(Car.to_a).to contain_exactly(
+        have_attributes(price: 25_000, coolness: 4),
+        have_attributes(price: 30_000, coolness: 6),
+        have_attributes(price: 10_000, coolness: 2)
+      )
+    end
+
+    it 'has a name that is a key as string' do
+      expect(Car.to_a.map(&:name)).to eq(['Audi', 'Mercedes', 'Toyota'])
+    end
+
+    describe '::add' do
+      it ' adds a constant enum value' do
+        enum = Suit::CLUBS
+        expect(enum).to be_a(Suit)
+      end
+
+      it 'insists symbols be symbols' do
+        expect do
+          class ::StringKeys < ValueEnum
+            add 'spades', 'spades'
+          end
+        end.to raise_error(TypeError)
+        expect(::StringKeys.to_a).to be_empty
+      end
+
+      it 'insists symbols be uppercase' do
+        expect do
+          class ::LowerCaseKeys < ValueEnum
+            add :spades, 'spades'
+          end
+        end.to raise_error(NameError)
+        expect(::LowerCaseKeys.to_a).to be_empty
+      end
+
+      it 'disallows nil keys' do
+        expect do
+          class ::NilKeys < ValueEnum
+            add nil, 'nil'
+          end
+        end.to raise_error(TypeError)
+        expect(::NilKeys.to_a).to be_empty
+      end
+
+      it 'allows, but ignores redeclaration of identical instances' do
+        class ::IdenticalInstances < ValueEnum
+          add :SPADES, 'spades'
+        end
+        expect(::IdenticalInstances).to receive(:warn).with(a_string_matching(/ignoring redeclaration of IdenticalInstances::SPADES/))
+        class ::IdenticalInstances < ValueEnum
+          add :SPADES, 'spades'
+        end
+        expect(::IdenticalInstances.to_a).to eq([::IdenticalInstances::SPADES])
+      end
+
+      it 'is private' do
+        expect { Tarot.add(:PENTACLES) }.to raise_error(NoMethodError)
+      end
+    end
+
+    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
+      it 'returns a copy' do
+        array = Suit.to_a
+        array.clear
+        expect(array.empty?).to eq(true)
+        expect(Suit.to_a).to eq([Suit::CLUBS, Suit::DIAMONDS, Suit::HEARTS, Suit::SPADES])
+      end
+    end
+
+    describe '::size' do
+      it 'returns the number of enum instnaces' do
+        expect(Suit.size).to eq(4)
+      end
+    end
+
+    describe '::each' do
+      it 'iterates the enum values' do
+        expected = [Suit::CLUBS, Suit::DIAMONDS, Suit::HEARTS, Suit::SPADES]
+        index = 0
+        Suit.each do |s|
+          expect(s).to be(expected[index])
+          index += 1
+        end
+      end
+    end
+
+    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|
+          expect(s).to be(expected[index])
+        end
+      end
+    end
+
+    describe '::map' do
+      it 'maps enum values' do
+        all_keys = Suit.map(&:key)
+        expect(all_keys).to eq([:CLUBS, :DIAMONDS, :HEARTS, :SPADES])
+      end
+    end
+
+    describe '#<=>' do
+      it 'orders enum instances' do
+        Suit.each_with_index do |s1, i1|
+          Suit.each_with_index do |s2, i2|
+            expect(s1 <=> s2).to eq(i1 <=> i2)
+          end
+        end
+      end
+    end
+
+    describe '#==' do
+      it 'returns true for identical instances, false otherwise' do
+        Suit.each do |s1|
+          Suit.each do |s2|
+            identical = s1.equal?(s2)
+            expect(s1 == s2).to eq(identical)
+          end
+        end
+      end
+
+      it 'reports instances as unequal to nil and other objects' do
+        a_nil_value = nil
+        Suit.each do |s|
+          expect(s.nil?).to eq(false)
+          expect(s == a_nil_value).to eq(false)
+          Tarot.each do |t|
+            expect(s == t).to eq(false)
+            expect(t == s).to eq(false)
+          end
+        end
+      end
+
+      it 'survives marshalling' do
+        Suit.each do |s1|
+          dump = Marshal.dump(s1)
+          s2 = Marshal.load(dump)
+          expect(s1 == s2).to eq(true)
+          expect(s2 == s1).to eq(true)
+        end
+      end
+    end
+
+    describe '#!=' do
+      it 'returns false for identical instances, true otherwise' do
+        Suit.each do |s1|
+          Suit.each do |s2|
+            different = !s1.equal?(s2)
+            expect(s1 != s2).to eq(different)
+          end
+        end
+      end
+
+      it 'reports instances as unequal to nil and other objects' do
+        a_nil_value = nil
+        Suit.each do |s|
+          expect(s != a_nil_value).to eq(true)
+          Tarot.each do |t|
+            expect(s != t).to eq(true)
+            expect(t != s).to eq(true)
+          end
+        end
+      end
+    end
+
+    describe '#hash' do
+      it 'gives consistent values' do
+        Suit.each do |s1|
+          Suit.each do |s2|
+            expect(s1.hash == s2.hash).to eq(s1 == s2)
+          end
+        end
+      end
+
+      it 'returns different values for different types' do
+        class Suit2 < ValueEnum
+          add :CLUBS, 'Clubs'
+          add :DIAMONDS, 'Diamonds'
+          add :HEARTS, 'Hearts'
+          add :SPADES, 'Spades'
+        end
+
+        Suit.each do |s1|
+          s2 = Suit2.find_by_key(s1.key)
+          expect(s1.hash == s2.hash).to eq(false)
+        end
+      end
+
+      it 'survives marshalling' do
+        Suit.each do |s1|
+          dump = Marshal.dump(s1)
+          s2 = Marshal.load(dump)
+          expect(s2.hash).to eq(s1.hash)
+        end
+      end
+
+      it 'always returns a Fixnum' do
+        Suit.each do |s1|
+          expect(s1.hash).to be_a(Fixnum)
+        end
+      end
+    end
+
+    describe '#eql?' do
+      it 'is consistent with #hash' do
+        Suit.each do |s1|
+          Suit.each do |s2|
+            expect(s1.eql?(s2)).to eq(s1.hash == s2.hash)
+          end
+        end
+      end
+    end
+
+    describe '#key' do
+      it 'returns the symbol key of the enum instance' do
+        expected = [:CLUBS, :DIAMONDS, :HEARTS, :SPADES]
+        Suit.each_with_index do |s, index|
+          expect(s.key).to eq(expected[index])
+        end
+      end
+    end
+
+    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)
+        end
+      end
+    end
+
+    describe '#to_s' do
+      it 'provides an informative string' do
+        aggregate_failures 'informative string' do
+          [Suit, Tarot, RGBColor, Scale].each do |ec|
+            ec.each do |ev|
+              result = ev.to_s
+              [ec.to_s, ev.key, ev.ord].each do |info|
+                expect(result).to include("#{info}")
+              end
+            end
+          end
+        end
+      end
+    end
+
+    describe '::find_by_key' do
+      it 'maps symbol keys to enum instances' do
+        keys = [:CLUBS, :DIAMONDS, :HEARTS, :SPADES]
+        expected = Suit.to_a
+        keys.each_with_index do |k, index|
+          expect(Suit.find_by_key(k)).to be(expected[index])
+        end
+      end
+
+      it 'returns nil for invalid keys' do
+        expect(Suit.find_by_key(:WANDS)).to be_nil
+      end
+    end
+
+    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)
+        end
+      end
+
+      it 'returns nil for negative indices' do
+        expect(Suit.find_by_ord(-1)).to be_nil
+      end
+
+      it 'returns nil for out-of-range indices' do
+        expect(Suit.find_by_ord(Suit.size)).to be_nil
+      end
+
+      it 'returns nil for invalid indices' do
+        expect(Suit.find_by_ord(100)).to be_nil
+      end
+    end
+
+    it 'supports case statements' do
+      def pip(suit)
+        case suit
+        when Suit::CLUBS
+          '♣'
+        when Suit::DIAMONDS
+          '♦'
+        when Suit::HEARTS
+          '♥'
+        when Suit::SPADES
+          '♠'
+        else
+          fail "unknown suit: #{self}"
+        end
+      end
+
+      expect(Suit.map { |s| pip(s) }).to eq(%w(♣ ♦ ♥ ♠))
+    end
+
+    it 'supports "inner class" methods' do
+      class Operation < ValueEnum
+        add(:PLUS, '+') do
+          def eval(x, y)
+            x + y
+          end
+        end
+        add(:MINUS, '-') do
+          def eval(x, y)
+            x - y
+          end
+        end
+      end
+
+      expect(Operation.map { |op| op.eval(39, 23) }).to eq([39 + 23, 39 - 23])
+    end
+  end
+end