typesafe_enum 0.1.6 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7d4eb09d4f1aa7e839ff17914b2b41273e5f82ef
-  data.tar.gz: 863e13f1b183a106aa9ad565485f2cb07ef6bac6
+  metadata.gz: a03ce1356a736037c69f793aaffb12ffe001b4e8
+  data.tar.gz: 3d748bba73a6df9a5f2bf929c379ef2a2ca904b4
 SHA512:
-  metadata.gz: 952de3b215c8a70054d644b82003069a12f85880d91645456b6a681f94f0d952820cf73db32e1563359d53846117c8cc12ce6864a6573d3094390a2bd98ca2ce
-  data.tar.gz: 0e9f424f975ad48bcbab6aaf6719082319e3a593f5372ada6eb9694b330b9679ecf9556c72c0c602e135911956857c150efcb340bfba4f34dc00ec6ec087fe2e
+  metadata.gz: f8437ae0afc6f20a003ca259fedf412378ffdea8c9090b17cc9271326cb78a0c43dd8dda22a3df31c32d468b94ea8e7edbb3b586ca8c582c967ac7c447da1a03
+  data.tar.gz: c55260cab261cc0273cfc61ca0eaaf686f57ecda9d18d8ea6c13e237e12ae97bd4909fc1ce54bd1545d2f4fb50c7e9c5d38cd04572e4d39172db3a71790dfc80

data/CHANGES.md

@@ -1,6 +1,19 @@
+## 0.1.7 (28 April 2016)
+
+- The default `to_s` for `TypesafeEnum::Base` now includes the enum's class, key, value,
+  and ordinal, e.g.
+
+      Suit::DIAMONDS.to_s
+      # => "Suit::DIAMONDS [1] -> diamonds"
+
+  (Fixes [#5](https://github.com/dmolesUC3/typesafe_enum/issues/5).)
+- `::find_by_value_str` now uses a hash lookup like the other `::find_by` methods.
+- Improved method documentation.
+
 ## 0.1.6 (15 Mar 2016)
 
-- [#3](https://github.com/dmolesUC3/typesafe_enum/pull/3) - No need for `instance_eval` when creating new enum instance methods - [@dblock](https://github.com/dblock).
+- [#3](https://github.com/dmolesUC3/typesafe_enum/pull/3) - No need for `instance_eval`
+  when creating new enum instance methods - [@dblock](https://github.com/dblock).
 
 ## 0.1.5 (27 Jan 2016)
 

data/README.md

@@ -1,4 +1,4 @@
-# typesafe_enum
+# 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)
@@ -9,6 +9,28 @@ A Ruby implementation of Joshua Bloch's
 [typesafe enum pattern](http://www.oracle.com/technetwork/java/page1-139488.html#replaceenums),
 with syntax loosely inspired by [Ruby::Enum](https://github.com/dblock/ruby-enum).
 
+## Table of contents
+
+- [Basic usage](#basic-usage)
+- [Ordering](#ordering)
+- [String representations](#string-representations)
+- [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)
+- [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 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)
+- [Contributing](#contributing)
+
 ## Basic usage
 
 Create a new enum class and a set of instances:
@@ -165,6 +187,18 @@ Suit::SPADES > Tarot::CUPS
 # ArgumentError: comparison of Suit with Tarot failed
 ```
 
+## String representations
+
+The default `to_s` implementation provides the enum's class, key, value,
+and ordinal, e.g.
+
+```ruby
+Suit::DIAMONDS.to_s
+# => "Suit::DIAMONDS [1] -> diamonds"
+```
+
+It can of course be overridden.
+
 ## Convenience methods on enum classes
 
 ### `::to_a`
@@ -229,9 +263,6 @@ Scale.find_by_value_str('1000000')
 # => #<Scale:0x007f8513a93810 @key=:MEGA, @value=1000000, @ord=3>
 ```
 
-(Note that unlike the other `::find_by…` methods, which use hash lookups, `::find_by_value_str`
-is linear in the number of enum values, so it's best suited for smaller enumerations.)
-
 ## Enum classes with methods
 
 Enum classes are just classes. They can have methods, and other non-enum constants.
@@ -334,7 +365,7 @@ Bar::BAR == 1
 ```
 
 Java introduced the concept of "typesafe enums", first as a
-[design pattern]((http://www.oracle.com/technetwork/java/page1-139488.html#replaceenums))
+[design pattern](http://www.oracle.com/technetwork/java/page1-139488.html#replaceenums)
 and later as a
 [first-class language construct](https://docs.oracle.com/javase/1.5.0/docs/guide/language/enums.html).
 In Java, an `Enum` class defines a closed, valued set of _instances of that class,_ rather than

data/lib/typesafe_enum/base.rb

@@ -8,50 +8,65 @@ module TypesafeEnum
     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 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.each do |value, instance|
-          return instance if value_str == value.to_s
-        end
-        nil
+        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 < 0 || ord > size
         as_array[ord]
@@ -67,6 +82,10 @@ module TypesafeEnum
         @by_value ||= {}
       end
 
+      def by_value_str
+        @by_value_str ||= {}
+      end
+
       def as_array
         @as_array ||= []
       end
@@ -91,23 +110,34 @@ module TypesafeEnum
         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
     end
 
     # The symbol key for the enum instance
+    # @return [Symbol] the key
     attr_reader :key
+
     # The value encapsulated by the enum instance
+    # @return [Object] the value
     attr_reader :value
+
     # 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
@@ -117,6 +147,10 @@ module TypesafeEnum
       end
     end
 
+    def to_s
+      "#{self.class}::#{key} [#{ord}] -> #{value}"
+    end
+
     private
 
     def initialize(key, value = nil, &block)

data/lib/typesafe_enum/module_info.rb

@@ -3,7 +3,7 @@ module TypesafeEnum
   NAME = 'typesafe_enum'
 
   # The version of this gem
-  VERSION = '0.1.6'
+  VERSION = '0.1.7'
 
   # The copyright notice for this gem
   COPYRIGHT = 'Copyright (c) 2016 The Regents of the University of California'

data/spec/unit/typesafe_enum/base_spec.rb

@@ -294,6 +294,21 @@ module TypesafeEnum
       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, ev.value].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]

data/typesafe_enum.gemspec

@@ -15,7 +15,7 @@ Gem::Specification.new do |spec|
   spec.license       = 'MIT'
 
   origin = `git config --get remote.origin.url`.chomp
-  origin_uri = origin.start_with?('http') ? URI(origin) : URI(origin.sub('git@github.com:', 'https://github.com/'))
+  origin_uri = origin.start_with?('http') ? URI(origin) : URI(origin.gsub(%r{git@([^:]+)(.com|.org)[^\/]+}, 'http://\1\2'))
   spec.homepage = URI::HTTP.build(host: origin_uri.host, path: origin_uri.path.chomp('.git')).to_s
 
   spec.files         = `git ls-files -z`.split("\x0")

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: typesafe_enum
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.7
 platform: ruby
 authors:
 - David Moles
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-03-15 00:00:00.000000000 Z
+date: 2016-04-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler