enumerated_type 0.1.2 → 0.2.0

data/README.md

@@ -27,10 +27,10 @@ class Job
 end
 ```
 
-At first pass this seems fine. Any code that needs to act based on a job's status has to have magic symbols (i.e. `job.status == :success`), but maybe that's ok for a little while. Later, though, we might want to add a little logic around the `Job`'s status, something like:
+At first pass this seems fine. Any code that needs to act based on a job's status has to have magic symbols (i.e. `job.status == :success`), but maybe that's OK for a little while. Later, though, we might want to add a little logic around the `Job`'s status, something like:
 
 ```ruby
-# In a job notifier class or something
+# In something like a JobNotifier class
 if job.status == :failure or job.status == :success
   # Email user to let them know about their job
 end
@@ -75,9 +75,9 @@ end
 
 There are some advantages to this approach:
 
-  1. The list of all the possible statuses lives in *only one place*. I think it's way easier to look at the `JobStatus` class and see what the possible statuses are than it is to hunt through the `Job` class Looking for symbols assigned to `@status`.
+  1. The list of all the possible statuses lives in *only one place*. I think it's way easier to look at the `JobStatus` class and see what the possible statuses are than it is to hunt through the `Job` class Looking for symbols assigned to `@status` (or, even worse, to look *outside* the `Job` class looking for assignments to Job#status).
   2. It's now possible to interact with the list of all legal statuses programmatically (perhaps in an admin console that has a drop down for of all statuses so that they may be manually updated).
-  3. We can separate behavior (methods) that apply to the enumerated types from the classes that include one of these types (`Job` in our example). Although the status handling code in our version of `Job` was fairly simple, it often becomes clear that handling the status of a job is a very separate concern from the actual processing of a `Job`, and this implementing both in a single class becomes an [SRP][http://en.wikipedia.org/wiki/Single_responsibility_principle] violation.
+  3. We can separate behavior (methods) that apply to the enumerated types from the classes that include one of these types (`Job` in our example). Although the status handling code in our version of `Job` was fairly simple, it often becomes clear that handling the status of a job is a very separate concern from the actual processing of a `Job`, and thus implementing both in a single class becomes a [Single Responsibility Principle](http://en.wikipedia.org/wiki/Single_responsibility_principle) violation.
   4. By separating the `JobStatus` behavior from the `Job`, we're able to more easily respond to change in requirements around the `JobStatus` in the future. Perhaps at some point we'll want to transform `JobStatus` into a state machine where only certain transitions are allowed, or include code that audits the change of state, etc.
 
 "But all did was explain enumerated types, the kind that are present all over the place in other languages." Yep. That is correct. The only downside of the approach shown is that you have to re-create very similar, one-off implementations of an enumerated type. The `EnumeratedType` gem is just a clean and simple Ruby implementation of a well known concept.
@@ -162,6 +162,19 @@ end
 JobStatus::SUCCESS.message # => "Your job has completed"
 ```
 
+Coerce from other types:
+
+```ruby
+JobStatus.coerce(:pending)           # => #<JobStatus:pending>
+JobStatus.coerce("pending")          # => #<JobStatus:pending>
+JobStatus.coerce(JobStatus::PENDING) # => #<JobStatus:pending>
+JobStatus.coerce(nil)                # => raises a TypeError
+JobStatus.coerce(1)                  # => raises a TypeError
+JobStatus.coerce(:wrong)             # => raises an ArgumentError
+```
+
+`.coerce` is particularly useful for scrubbing parameters, allowing you to succinctly assert that arguments are valid for your `EnumeratedType`, while also broadening the range of types that can be used as input. Using `.coerce` at the boundaries of your code allows clients the freedom to pass in full fledged `EnumeratedType` objects, symbols or even strings, and allows you to use the `.coerce`d input with confidence (i.e without any type or validity checking beyond the call to `.coerce`).
+
 ## Development
 
 To run the tests (assuming you have already run `gem install bundler`):

data/lib/enumerated_type/version.rb

@@ -1,3 +1,3 @@
 module EnumeratedType
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

data/lib/enumerated_type.rb

@@ -56,6 +56,16 @@ module EnumeratedType
       map(&:name).include?(name)
     end
 
+    def coerce(coercable)
+      case
+      when coercable.class == self then coercable
+      when coercable.respond_to?(:to_sym) then self[coercable.to_sym]
+      when coercable.respond_to?(:to_str) then self[coercable.to_str.to_sym]
+      else
+        raise TypeError, "#{coercable.inspect} cannot be coerced into a #{self.name}"
+      end
+    end
+
     private
 
     def declare(name, options = {})

data/test/enumerated_type_spec.rb

@@ -14,7 +14,7 @@ describe EnumeratedType do
   end
 
   it "privatizes the constructor" do
-    lambda { Gender.new }.must_raise(NoMethodError, /private method `new' called/)
+    lambda { Gender.new }.must_raise(NoMethodError)
   end
 
   it "is enumerable" do
@@ -64,12 +64,12 @@ describe EnumeratedType do
 
   describe ".declare" do
     it "is private" do
-      lambda { Gender.declare }.must_raise(NoMethodError, /private method `declare' called/)
+      lambda { Gender.declare }.must_raise(NoMethodError)
     end
 
     it "requires the name to be unique" do
       duplicate_name = Gender.first.name
-      lambda { Gender.send(:declare, duplicate_name) }.must_raise(ArgumentError, /duplicate name/)
+      lambda { Gender.send(:declare, duplicate_name) }.must_raise(ArgumentError)
     end
 
     it "produces frozen instances" do
@@ -81,7 +81,7 @@ describe EnumeratedType do
     end
 
     it "freezes properties" do
-      lambda { Gender::MALE.planet.replace("pluto") }.must_raise(RuntimeError, /can't modify frozen/)
+      lambda { Gender::MALE.planet.replace("pluto") }.must_raise(RuntimeError)
     end
 
     it "does not expose public setters for properties" do
@@ -96,7 +96,7 @@ describe EnumeratedType do
         end
       end
 
-      name_property_definition.must_raise(ArgumentError, "Property name 'name' is not allowed")
+      name_property_definition.must_raise(ArgumentError)
     end
   end
 
@@ -121,6 +121,37 @@ describe EnumeratedType do
     end
   end
 
+  describe ".coerce" do
+    it "returns the correct type if given a recognized symbol" do
+      Gender.coerce(:female).must_equal Gender::FEMALE
+    end
+
+    it "returns the correct type if given a recognized string" do
+      Gender.coerce("female").must_equal Gender::FEMALE
+    end
+
+    it "returns the correct type if given something that responds to #to_str" do
+      stringlike = Object.new
+      def stringlike.to_str
+        "female"
+      end
+
+      Gender.coerce(stringlike).must_equal Gender::FEMALE
+    end
+
+    it "returns the object unmodified if given an instance of the enumerated type" do
+      Gender.coerce(Gender::FEMALE).must_equal Gender::FEMALE
+    end
+
+    it "raises a TypeError if given something that isn't coercable" do
+      lambda { Gender.coerce(Object.new) }.must_raise(TypeError)
+    end
+
+    it "raises a ArgumentError if given something coercable but not recognized" do
+      lambda { Gender.coerce(:neuter) }.must_raise(ArgumentError)
+    end
+  end
+
   describe "#inspect" do
     it "looks reasonable" do
       Gender::FEMALE.inspect.must_equal "#<Gender:female>"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: enumerated_type
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-12-12 00:00:00.000000000 Z
+date: 2014-01-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -90,7 +90,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1744150559039667923
+      hash: -1874679306341587618
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -99,7 +99,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1744150559039667923
+      hash: -1874679306341587618
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.26