typesafe_enum 0.2.2 → 0.3.1

data/.rubocop.yml

@@ -1,8 +1,3 @@
-# Disable compact style check for example.rb
-Style/ClassAndModuleChildren:
-  Exclude:
-    - 'example.rb'
-
 # Allow one line around block body (Layout/EmptyLines will still disallow two or more)
 Layout/EmptyLinesAroundBlockBody:
   Enabled: false
@@ -27,11 +22,6 @@ Layout/MultilineMethodCallIndentation:
 Layout/MultilineOperationIndentation:
   Enabled: false
 
-# Just because something looks like an accessor doesn't mean it is one
-Naming/PredicateName:
-  Exclude:
-    - 'app/controllers/application_controller.rb'
-
 # Confusing and weird
 Naming/VariableNumber:
   Enabled: False
@@ -60,18 +50,6 @@ Style/CommentedKeyword:
 Style/Documentation:
   Enabled: false
 
-# Added in RuboCop 0.80
-Style/HashEachMethods:
-  Enabled: true
-
-# Added in RuboCop 0.80
-Style/HashTransformKeys:
-  Enabled: true
-
-# Added in RuboCop 0.80
-Style/HashTransformValues:
-  Enabled: true
-
 # Adding more line noise to format strings will not improve them
 Style/FormatStringToken:
   Enabled: false
@@ -95,3 +73,187 @@ Style/Lambda:
 # Unclear why it's a good idea to give parameters semantically meaningless names
 Style/SingleLineBlockParams:
   Enabled: false
+
+############################################################
+# Added in RuboCop 0.80
+
+Style/HashEachMethods:
+  Enabled: true
+
+Style/HashTransformKeys:
+  Enabled: true
+
+Style/HashTransformValues:
+  Enabled: true
+
+############################################################
+# Added in RuboCop 0.81
+
+Lint/StructNewOverride:
+  Enabled: true
+
+Lint/RaiseException:
+  Enabled: true
+
+############################################################
+# Added in RuboCop 0.82
+
+Layout/SpaceAroundMethodCallOperator:
+  Enabled: true
+
+Style/ExponentialNotation:
+  Enabled: false
+
+############################################################
+# Added in RuboCop 0.83
+
+Layout/EmptyLinesAroundAttributeAccessor:
+  Enabled: true
+
+Style/SlicingWithRange:
+  Enabled: true
+
+############################################################
+# Added in RuboCop 0.84
+
+Lint/DeprecatedOpenSSLConstant:
+  Enabled: true
+
+############################################################
+# Added in RuboCop 0.85
+
+Lint/MixedRegexpCaptureTypes:
+  Enabled: true
+
+Style/RedundantRegexpEscape:
+  Enabled: true
+
+Style/RedundantRegexpCharacterClass:
+  Enabled: true
+
+############################################################
+# Added in Rubocop 0.86
+
+Style/RedundantFetchBlock:
+  Enabled: true
+
+############################################################
+# Added in Rubocop 0.87
+
+# Sometimes we separate things for a reason
+Style/AccessorGrouping:
+  Enabled: false
+
+Style/BisectedAttrAccessor:
+  Enabled: true
+
+Style/RedundantAssignment:
+  Enabled: true
+
+############################################################
+# Added in Rubocop 0.88
+
+Lint/DuplicateElsifCondition:
+  Enabled: true
+
+Style/ArrayCoercion:
+  Enabled: true
+
+Style/CaseLikeIf:
+  Enabled: true
+
+Style/HashAsLastArrayItem:
+  Enabled: true
+
+Style/HashLikeCase:
+  Enabled: true
+
+Style/RedundantFileExtensionInRequire:
+  Enabled: true
+
+############################################################
+# Added in Rubocop 0.89
+
+Lint/BinaryOperatorWithIdenticalOperands:
+  Enabled: true
+
+Lint/DuplicateRescueException:
+  Enabled: true
+
+Lint/EmptyConditionalBody:
+  Enabled: true
+
+Lint/FloatComparison:
+  Enabled: true
+
+Lint/MissingSuper:
+  Enabled: true
+
+Lint/OutOfRangeRegexpRef:
+  Enabled: true
+
+Lint/SelfAssignment:
+  Enabled: true
+
+Lint/TopLevelReturnWithArgument:
+  Enabled: true
+
+Lint/UnreachableLoop:
+  Enabled: true
+
+Style/ExplicitBlockArgument:
+  Enabled: true
+
+Style/GlobalStdStream:
+  Enabled: true
+
+Style/OptionalBooleanParameter:
+  Enabled: true
+
+Style/SingleArgumentDig:
+  Enabled: true
+
+Style/SoleNestedConditional:
+  Enabled: true
+
+Style/StringConcatenation:
+  Enabled: true
+
+############################################################
+# Added in Rubocop 0.90
+
+Lint/DuplicateRequire:
+  Enabled: true
+
+Lint/EmptyFile:
+  Enabled: true
+
+Lint/TrailingCommaInAttributeDeclaration:
+  Enabled: true
+
+Lint/UselessMethodDefinition:
+  Enabled: true
+
+Style/CombinableLoops:
+  Enabled: true
+
+Style/KeywordParametersOrder:
+  Enabled: true
+
+Style/RedundantSelfAssignment:
+  Enabled: true
+
+############################################################
+# Added in Rubocop 0.91
+
+Layout/BeginEndAlignment:
+  Enabled: true
+
+Lint/ConstantDefinitionInBlock:
+  Enabled: true
+
+Lint/IdentityComparison:
+  Enabled: true
+
+Lint/UselessTimes:
+  Enabled: true

data/.ruby-version

@@ -1 +1 @@
-2.6.5
+2.7

data/.travis.yml

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

data/CHANGES.md

@@ -1,3 +1,20 @@
+## 0.3.1 (next)
+
+- Add `values`, `keys`, `each_value`, `each_key`, `find_by_value!`, `find_by_value_str!`
+  (PR [#8](https://github.com/dmolesUC/typesafe_enum/pull/8))
+- Set minimum required_ruby_version to 2.7 to reflect 2.6 
+  [end of life](https://www.ruby-lang.org/en/news/2022/04/12/ruby-2-6-10-released/)
+- Bump .ruby-version to 2.7
+- Bump Rake version to 13 for 2.x/3.x compatibility
+
+## 0.3.0 (26 October 2020)
+
+- 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)

data/README.md

@@ -1,6 +1,6 @@
 # TypesafeEnum
 
-[![Build Status](https://travis-ci.org/dmolesUC/typesafe_enum.svg?branch=master)](https://travis-ci.org/dmolesUC/typesafe_enum)
+[![Build Status](https://github.com/dmolesUC/typesafe_enum/actions/workflows/build.yml/badge.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)
@@ -93,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

data/Rakefile

@@ -1,51 +1,17 @@
 # frozen_string_literal: true
 
-# ------------------------------------------------------------
-# 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
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('Gemfile', __dir__)
+require 'bundler/setup' # Set up gems listed in the Gemfile.
 
 # ------------------------------------------------------------
-# TODOs
+# Application code
 
-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'
+File.expand_path('lib', __dir__).tap do |lib|
+  $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 end
 
 # ------------------------------------------------------------
-# Defaults
+# Custom tasks
 
-desc 'Run unit tests, check test coverage, run acceptance tests, check code style'
-task default: %i[coverage rubocop]
+desc 'Run tests, check test coverage, check code style, build gem'
+task default: %i[coverage rubocop gem]

data/lib/typesafe_enum/base.rb

@@ -1,108 +1,18 @@
 # frozen_string_literal: true
 
+require 'typesafe_enum/exceptions'
+require 'typesafe_enum/class_methods'
+
 # A Ruby implementation of Joshua Bloch's
 # [typesafe enum pattern](http://www.oracle.com/technetwork/java/page1-139488.html#replaceenums)
 module TypesafeEnum
+
   # Base class for typesafe enum classes.
   class Base
     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
-      def to_a
-        as_array.dup
-      end
-
-      # Returns the number of enum instances
-      # @return [Integer] the number of instances
-      def size
-        as_array.size
-      end
-
-      # Iterates over the set of enum instances
-      # @yield [self] Each instance 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
-
-      # 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 value
-      # @param value [Object] the value to look up
-      # @return [self, nil] the corresponding enum instance, or nil
-      def find_by_value(value)
-        by_value[value]
-      end
-
-      # Looks up an enum instance based on the string representation of its value
-      # @param value_str [String] the string form of the value
-      # @return [self, nil] the corresponding enum instance, or nil
-      def find_by_value_str(value_str)
-        value_str = value_str.to_s
-        by_value_str[value_str]
-      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 > size || ord.negative?
-
-        as_array[ord]
-      end
-
-      private
-
-      def by_key
-        @by_key ||= {}
-      end
-
-      def by_value
-        @by_value ||= {}
-      end
-
-      def by_value_str
-        @by_value_str ||= {}
-      end
-
-      def as_array
-        @as_array ||= []
-      end
-
-      def valid_key_and_value(instance)
-        key = instance.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
-      end
-
-      def register(instance)
-        key, value = valid_key_and_value(instance)
-        return unless key && value
-
-        const_set(key.to_s, instance)
-        by_key[key] = instance
-        by_value[value] = instance
-        by_value_str[value.to_s] = instance
-        as_array << instance
-      end
+      include ClassMethods
     end
 
     # The symbol key for the enum instance
@@ -123,6 +33,9 @@ module TypesafeEnum
     #   the same enum instance; 1 if this value follows `other`; `nil` if `other`
     #   is not an instance of this enum class
     def <=>(other)
+      # in the case where the enum being compared is actually the parent
+      # class, only `==` will work correctly & we cannot use #is_a? or
+      # #instance_of?
       ord <=> other.ord if self.class == other.class
     end
 
@@ -137,17 +50,24 @@ module TypesafeEnum
       end
     end
 
+    # Default implementation includes the enum class, `key`,
+    # `ord` and `value`.
+    # @return [String] a string representation of the enum instance
     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
+
+    # TODO: is documentation on this still accurate? does it still need to be private?
+    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/class_methods.rb

@@ -0,0 +1,167 @@
+module TypesafeEnum
+  # Class methods for {{TypesafeEnum::Base}}.
+  module ClassMethods
+    include Enumerable
+
+    # 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.size
+    end
+
+    # Iterates over the set of enum instances
+    # @yield [self] Each instance 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
+
+    # The set of all keys of all enum instances
+    # @return [Enumerator<Symbol>] All keys of all enums, in declaration order
+    def keys
+      to_a.map(&:key)
+    end
+
+    # The set of all values of all enum instances
+    # @return [Enumerator<Object>] All values of all enums, in declaration order
+    def values
+      to_a.map(&:value)
+    end
+
+    # Iterates over the set of keys of all instances (#keys)
+    # @yield [Enumerator<Symbol>] Each key of each instance of this enum, in declaration order
+    # @return [Enumerator<Symbol>]
+    def each_key(&block)
+      keys.each(&block)
+    end
+
+    # Iterates over the set of values of all instances (#values)
+    # @yield [Enumerator<Object>] Each value of each instance of this enum, in declaration order
+    # @return [Enumerator<Object>]
+    def each_value(&block)
+      values.each(&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 value
+    # @param value [Object] the value to look up
+    # @return [self, nil] the corresponding enum instance, or nil
+    def find_by_value(value)
+      by_value[value]
+    end
+
+    # Looks up an enum instance based on its value
+    # @param value [Object] the value to look up
+    # @return [self, EnumValidationError] the corresponding enum instance, or throws #EnumValidationError
+    def find_by_value!(value)
+      valid = find_by_value(value)
+      return valid unless valid.nil?
+
+      raise Exceptions::EnumValidationError, "#{class_name}: #{value} is absurd"
+    end
+
+    # Looks up an enum instance based on the string representation of its value
+    # @param value_str [String] the string form of the value
+    # @return [self, nil] the corresponding enum instance, or nil
+    def find_by_value_str(value_str)
+      value_str = value_str.to_s
+      by_value_str[value_str]
+    end
+
+    # Looks up an enum instance based on the string representation of its value
+    # @param value_str [String] the string form of the value
+    # @return [self, EnumValidationError] the corresponding enum instance, or throws #EnumValidationError
+    def find_by_value_str!(value_str)
+      valid = find_by_value_str(value_str)
+      return valid unless valid.nil?
+
+      raise Exceptions::EnumValidationError, "#{class_name}: #{value_str} is absurd"
+    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 > size || ord.negative?
+
+      as_array[ord]
+    end
+
+    private
+
+    def by_key
+      @by_key ||= {}
+    end
+
+    def by_value
+      @by_value ||= {}
+    end
+
+    def by_value_str
+      @by_value_str ||= {}
+    end
+
+    def as_array
+      @as_array ||= []
+    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
+      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
+
+      const_set(key.to_s, instance)
+      by_key[key] = instance
+      by_value[value] = instance
+      by_value_str[value.to_s] = instance
+      as_array << instance
+    end
+
+    # Returns the demodulized class name of the inheriting class
+    # @return [String] The demodulized class name
+    def class_name
+      name.split('::').last
+    end
+
+  end
+end

data/lib/typesafe_enum/exceptions.rb

@@ -0,0 +1,7 @@
+module TypesafeEnum
+  # Grouping module for exceptions
+  module Exceptions
+    # Base class of enum validation exceptions
+    class EnumValidationError < StandardError; end
+  end
+end

data/lib/typesafe_enum/module_info.rb

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
 module TypesafeEnum
-  # The name of this gem
-  NAME = 'typesafe_enum'
+  module ModuleInfo
+    # The name of this gem
+    NAME = 'typesafe_enum'
 
-  # The version of this gem
-  VERSION = '0.2.2'
+    # The version of this gem
+    VERSION = '0.3.1'
 
-  # The copyright notice for this gem
-  COPYRIGHT = 'Copyright (c) 2020 The Regents of the University of California'
+    # The copyright notice for this gem
+    COPYRIGHT = 'Copyright (c) 2022 The Regents of the University of California'
+  end
 end