typesafe_enum 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6e6e6d0a15330f5ec2dd13061e2da603ec354705
-  data.tar.gz: cfaca6a2bc5a2dd50dd2442abc23a6fe5775e8dd
+  metadata.gz: 59ddff44544a977b2f7d6c4cf56727d0a1aabf60
+  data.tar.gz: 9987d8367b1eb2cc2d79baa52b8ed58e934e5dd3
 SHA512:
-  metadata.gz: 0808cf4b53fc63cd69d330cec45fe2124f73380070e6db5d7c6c03e389f8dbf32d1b9c36ea54147cbe6f2abfcc458b35416371f1242c17d191208e91342033ad
-  data.tar.gz: 604dfd70e95d123a72045757aba249b474c3cb8869282d4eac3d38dd37663a56e5f7724439de1dafc20532b8d2eb79bb813fff60fad22064ac5229dd050df7c7
+  metadata.gz: 64736c736ebd281b5eb368195bef1bbcd62ea61f737d3474f8e29b4bfd468a376199fb62f0a639a16a68ff98af9a24293867720e790f6e6cd76282161165de64
+  data.tar.gz: 8dc8b5dcaa016a53bda462f425f77652745c11e36944172895f36924bd00e49ead3eff56463f9ad5150772f524a4e1a3d2ed740365fafdfd1aa21cf357b58f56

data/.gitignore

@@ -15,6 +15,9 @@
 *.a
 mkmf.log
 
+# Build output
+*.gem
+
 # Database
 
 db/*.sqlite3

data/CHANGES.md

@@ -1,3 +1,7 @@
+## 0.1.1
+
+- Added `::find_by_value_str`
+
 ## 0.1.0
 
 - Initial release

data/README.md

@@ -144,6 +144,19 @@ Tarot.find_by_ord(3)
 # => #<Tarot:0x007faab19fd810 @key=:SWORDS, @value="Swords", @ord=3>
 ```
 
+### `::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:
+
+```ruby
+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 can have methods, and other non-enum constants:
@@ -259,33 +272,99 @@ Tarot::CUPS == 'Cups'
 # => false
 ```
 
-## How is this different from [java.lang.Enum](http://docs.oracle.com/javase/8/docs/api/java/lang/Enum.html)?
-
-*[TODO: details]*
+## How is this different from `java.lang.Enum`?
 
 ### Clunkier syntax
 
+In Java 5+, you can define an enum in one line and instance-specific methods with a pair of braces.
+
+```java
+enum CMYKColor {
+  CYAN, MAGENTA, YELLOW, BLACK
+}
+
+enum Suit {
+  CLUBS    { char pip() { return '♣'; } },
+  DIAMONDS { char pip() { return '♦'; } },
+  HEARTS   { char pip() { return '♥'; } },
+  SPADES   { char pip() { return '♠'; } };
+
+  abstract char pip();
+}
+```
+
+With `TypesafeEnum`, instance-specific methods require extra parentheses and `instance_eval`,
+as shown above, and about the best you can do even for simple enums is something like:
+
+```ruby
+class CMYKColor < TypesafeEnum::Base
+  [:CYAN, :MAGENTA, :YELLOW, :BLACK].each { |c| new c }
+end
+```
+
 ### No special `switch`/`case` support
 
+The Java compiler will warn you if a `switch` statement doesn't include all instances of a Java enum.
+Ruby doesn't care whether you cover all instances of a `TypesafeEnum`, and in fact it doesn't care if
+your `when` statements include a mix of enum instances of different classes, or of enum instances and
+other things. (In some respects this latter is a feature, of course.)
+
 ### No serialization support
 
-  - but `#==`, `#hash` etc. are `Marshal`-safe
+The Java `Enum` class has special code to ensure that enum instances are deserialized to the existing
+singleton constants. This can be done with Ruby [`Marshal`](http://ruby-doc.org/core-2.2.3/Marshal.html)
+(by defining `marshal_load`) but it didn't seem worth the trouble, so a deserialized `TypesafeEnum` will
+not be identical to the original:
 
-### No support classes like [`EnumSet`](http://docs.oracle.com/javase/8/docs/api/java/util/EnumSet.html) and
-  [`EnumMap`](http://docs.oracle.com/javase/8/docs/api/java/util/EnumMap.html)
+```ruby
+clubs2 = Marshal.load(Marshal.dump(Suit::CLUBS))
+Suit::CLUBS.equal?(clubs2)
+# => false
+```
+
+However, `#==`, `#hash`, etc. are `Marshal`-safe:
+
+```ruby
+Suit::CLUBS == clubs2
+# => true
+clubs2 == Suit::CLUBS
+# => true
+Suit::CLUBS.hash == clubs2.hash
+# => true
+```
+
+If this isn't enough, and the lack of object identity across marshalling is a problem, it could be added
+in a later version. (Pull requests welcome!)
+
+### No support classes
+
+Java has `Enum`-specific classes like
+[`EnumSet`](http://docs.oracle.com/javase/8/docs/api/java/util/EnumSet.html) and
+[`EnumMap`](http://docs.oracle.com/javase/8/docs/api/java/util/EnumMap.html) that provide special
+high-performance, optimized versions of its collection interfaces. `TypesafeEnum` doesn't.
 
 ### Enum classes are not closed
 
 It's Ruby, so even though `:new` is private to each enum class, you
-can always work around that:
+can work around that in various ways:
 
 ```ruby
 Suit.send(:new, :JOKERS)
 # => #<Suit:0x007fc9e44e4778 @key=:JOKERS, @value="jokers", @ord=4>
+
+class Tarot
+  new :MAJOR_ARCANA, 'Major Arcana'
+end
+# => #<Tarot:0x007f8513b39b20 @key=:MAJOR_ARCANA, @value="Major Arcana", @ord=4>
+
 Suit.map(&:key)
 # => [:CLUBS, :DIAMONDS, :HEARTS, :SPADES, :JOKERS]
-Suit.size
-# => 5
+
+Tarot.map(&:key)
+# => [:CUPS, :COINS, :WANDS, :SWORDS, :MAJOR_ARCANA]
 ```
 
-### *[Other limitations...]*
+## Contributing
+
+Pull requests are welcome, but please make sure the tests pass, the code has 100% coverage, and the
+code style passes Rubocop. (The default rake task should check all of these for you.)

data/lib/typesafe_enum/base.rb

@@ -42,6 +42,14 @@ module TypesafeEnum
         by_value[value]
       end
 
+      # Looks up an enum instance based on the string representation of its value
+      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
+      end
+
       # Looks up an enum instance based on its ordinal
       def find_by_ord(ord)
         return nil if ord < 0 || ord > size

data/lib/typesafe_enum/module_info.rb

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

data/spec/unit/typesafe_enum/base_spec.rb

@@ -15,6 +15,19 @@ class Tarot < TypesafeEnum::Base
   new :SWORDS, 'Swords'
 end
 
+class RGBColor < TypesafeEnum::Base
+  new :RED, :red
+  new :GREEN, :green
+  new :BLUE, :blue
+end
+
+class Scale < TypesafeEnum::Base
+  new :DECA, 10
+  new :HECTO, 100
+  new :KILO, 1_000
+  new :MEGA, 1_000_000
+end
+
 module TypesafeEnum
   describe Base do
 
@@ -285,27 +298,40 @@ module TypesafeEnum
       end
 
       it 'supports enums with symbol values' do
-        class RGBColors < Base
-          new :RED, :red
-          new :GREEN, :green
-          new :BLUE, :blue
+        RGBColor.each do |c|
+          expect(RGBColor.find_by_value(c.value)).to be(c)
         end
+      end
 
-        RGBColors.each do |c|
-          expect(RGBColors.find_by_value(c.value)).to be(c)
+      it 'supports enums with integer values' do
+        Scale.each do |s|
+          expect(Scale.find_by_value(s.value)).to be(s)
         end
       end
+    end
 
-      it 'supports enums with integer values' do
-        class Scale < Base
-          new :DECA, 10
-          new :HECTO, 100
-          new :KILO, 1_000
-          new :MEGA, 1_000_000
+    describe '::find_by_value_str' do
+      it 'maps string values to enum instances' do
+        values = %w(clubs diamonds hearts spades)
+        expected = Suit.to_a
+        values.each_with_index do |n, index|
+          expect(Suit.find_by_value_str(n)).to be(expected[index])
         end
+      end
+
+      it 'returns nil for invalid values' do
+        expect(Suit.find_by_value_str('wands')).to be_nil
+      end
 
+      it 'supports enums with symbol values' do
+        RGBColor.each do |c|
+          expect(RGBColor.find_by_value_str(c.value.to_s)).to be(c)
+        end
+      end
+
+      it 'supports enums with integer values' do
         Scale.each do |s|
-          expect(Scale.find_by_value(s.value)).to be(s)
+          expect(Scale.find_by_value_str(s.value.to_s)).to be(s)
         end
       end
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: typesafe_enum
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - David Moles
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-11-18 00:00:00.000000000 Z
+date: 2015-11-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler