enumerated_type 0.0.2 → 0.1.0

data/README.md

@@ -1,29 +1,169 @@
-# Enumeration
+# EnumeratedType
 
-TODO: Write a gem description
+Dead simple enumerated types for Ruby.
 
-## Installation
+## Background
 
-Add this line to your application's Gemfile:
+This gem implements the familiar notion of enumerated types in Ruby.
 
-    gem 'enumerated_type'
+"But this is Ruby," you say, "where we haven't any use for such things." Yep. In Ruby, you can get a long way without any formalized concept of enumerated types by just using regular, boring old symbols. Let's take the fairly typical example of a "status" field on the `Job` class:
 
-And then execute:
+```ruby
+class Job
+  attr_reader :status
 
-    $ bundle
+  def initialize
+    @status = :pending
+  end
 
-Or install it yourself as:
+  def process
+    begin
+      # Do work here...
+      @status = :success
+    rescue
+      @status = :failure
+    end
+  end
+end
+```
 
-    $ gem install enumerated_type
+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 to the `Job`'s status, something like:
+
+```ruby
+# In a job notifier class or something
+if job.status == :failure or job.status == :success
+  # Email user to let them know about their job
+end
+```
+
+At this point, it's starting to feel like a little bit too much knowledge about the `Job` has slipped into other classes; any changes to the in the way status is handled in `Job` will require change in other classes because they've been exposed to the details of it's implementation. What, for example, if we want to add another "finished" state that a user should be notified of (say, `:partial_success`)? To deal with this we might create a predicate method that lets you interrogate a `Job` more abstractly about it's status:
+
+```ruby
+class Job
+  # ...
+  def done?
+    [:failure, :success, :partial_success].include?(@status)
+  end
+end
+```
+
+Now, say we need another kind of job: the `AdminJob`. It needs to have the same set of statuses (with the same behavior as `Job`'s status). We could certainly move the status related code into a `StatusHaving` module and mix it in to both `Job` and `AdminJob`, but there are some drawbacks here, chief among them that we'd have to add a good bit of coupling between the `Job`, `AdminJob` and the `StatusHaving` mix-in module. For example both classes and the mix-in would need to agree on the `@status` instance variable. I would argue at this point the idea of a `JobStatus` should be promoted to it's own class, maybe with a little bit of error checking:
+
+```ruby
+class JobStatus
+  NAMES = [:pending, :success, :failure]
+
+  def initialize(name)
+    unless NAMES.include?(name)
+      raise ArugmentError.new("Invalid status #{name.inspect}")
+    end
+
+    @name = name
+  end
+end
+```
+
+and then in `Job`:
+
+```ruby
+class Job
+  def initialize
+    @status = JobStatus.new(:pending)
+  end
+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`.
+  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.
+  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.
 
 ## Usage
 
-TODO: Write usage instructions here
+Define an enumerated type:
+
+```ruby
+class JobStatus
+  include EnumeratedType
+
+  declare :pending
+  declare :success
+  declare :failure
+end
+```
+
+Get an instance of an enumerated type:
+
+```ruby
+# Via constant...
+@status = JobStatus::PENDING
+
+# Or via symbol...
+@status = JobStatus[:pending]
+@status = JobStatus[:does_not_exist] #=> raises an ArgumentError
+```
+
+All instances have predicate methods defined automatically:
+
+```ruby
+@status = JobStatus::PENDING
+@status.pending? # => true
+@status.failure? # => false
+```
+
+Get the original symbol used to define the type:
+
+```ruby
+JobStatus::PENDING.name # => :pending
+```
+
+A class that includes `EnumeratedType` is just a regular Ruby class, so feel free to (and definitely do) add your own methods:
+
+```ruby
+class JobStatus
+  #...
+  def done?
+    success? or failure?
+  end
+end
+```
+
+The only exception exception to the "just a regular ruby class" rule is that the constructor (`JobStatus.new`) is privatized.
+
+Classes that include enumerated types themselves become enumerable, so you can do things like:
+
+```ruby
+JobStatus.map(&:name).sort.each { |n| puts "JobStatus: #{n}" }
+```
+
+## Bonus Features
+
+Create enumerated types with ultra-low ceremony:
+
+```ruby
+JobStatus = EnumeratedType.new(:pending, :success, :failure)
+```
+
+Add arbitrary attributes:
+
+```ruby
+class JobStatus
+  include EnumeratedType
+
+  declare :pending, :message => "Your Job is waiting to be processed"
+  declare :success, :message => "Your Job has completed"
+  declare :failure, :message => "Oops, it looks like there was a problem"
+end
+
+JobStatus::SUCCESS.message # => "Your job has completed"
+```
+
+## Development
 
-## Contributing
+To run the tests (assuming you have already run `gem install bundler`):
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+    bundle install && rake test

data/lib/enumerated_type.rb

@@ -14,13 +14,28 @@ module EnumeratedType
     end
   end
 
+  def inspect
+    "#<#{self.class.name}:#{name}>"
+  end
+
+  def to_s
+    name.to_s
+  end
+
   private
 
-  def initialize(name, value, options = {})
-    @name  = name
-    @value = value
+  def initialize(name, properties)
+    @name = name
+    properties.each { |k, v| send(:"#{k}=", v) }
+  end
+
+  def self.new(*names)
+    names = names.first if names.first.kind_of?(Enumerable)
 
-    options.each { |k, v| send(:"#{k}=", v) }
+    Class.new do
+      include EnumeratedType
+      names.each { |n| declare(n) }
+    end
   end
 
   module ClassMethods
@@ -28,20 +43,11 @@ module EnumeratedType
       @all.each(&block)
     end
 
-    def by_value(value)
-      each { |e| return e if e.value == value }
-      raise ArgumentError, "Unrecognized #{self.name} value #{value.inspect}'"
-    end
-
-    def by_name(name)
+    def [](name)
       each { |e| return e if e.name == name }
       raise ArgumentError, "Unrecognized #{self.name} name #{name.inspect}'"
     end
 
-    def [](name)
-      by_name(name)
-    end
-
     def recognized?(name)
       map(&:name).include?(name)
     end
@@ -49,22 +55,26 @@ module EnumeratedType
     private
 
     def declare(name, options = {})
-      value = options.delete(:value)
-      value ||= (map(&:value).max || 0) + 1
-
       if map(&:name).include?(name)
         raise(ArgumentError, "duplicate name #{name.inspect}")
       end
 
-      if map(&:value).include?(value)
-        raise(ArgumentError, "duplicate :value #{value.inspect}")
-      end
-
       define_method(:"#{name}?") do
         self.name == name
       end
 
-      enumerated = new(name, value, options)
+      options.keys.each do |property|
+        unless instance_methods.include?(:"#{property}")
+          attr_reader(:"#{property}")
+        end
+
+        unless instance_methods.include?(:"#{property}=")
+          attr_writer(:"#{property}")
+          private(:"#{property}=")
+        end
+      end
+
+      enumerated = new(name, options)
 
       @all << enumerated
       const_set(name.to_s.upcase, enumerated)

data/lib/enumerated_type/version.rb

@@ -1,3 +1,3 @@
 module EnumeratedType
-  VERSION = "0.0.2"
+  VERSION = "0.1.0"
 end

data/test/enumerated_type_spec.rb

@@ -9,10 +9,8 @@ describe EnumeratedType do
   class Gender
     include EnumeratedType
 
-    attr_accessor :planet
-
-    declare(:male, :planet => "mars")
-    declare(:female, :planet => "venus")
+    declare :male, :planet => "mars"
+    declare :female, :planet => "venus"
   end
 
   it "privatizes the constructor" do
@@ -37,56 +35,60 @@ describe EnumeratedType do
     Gender.entries.map(&:female?).must_equal [false, true]
   end
 
-  describe ".declare" do
-    it "is private" do
-      lambda { Gender.declare }.must_raise(NoMethodError, /private method `declare' called/)
+  describe ".new" do
+    it "returns an anonymous class" do
+      EnumeratedType.new.instance_of?(Class).must_equal true
+      EnumeratedType.new.name.must_equal nil
     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/)
+    it "returns a class that includes EnumeratedType" do
+      gender = EnumeratedType.new
+      gender.ancestors.include?(EnumeratedType).must_equal true
     end
 
-    it "allows you to specify :value" do
-      gender = Class.new do
-        include EnumeratedType
-        declare :male, :value => 100
-        declare :female, :value => 101
-      end
+    it "declares the given names as types (provided as arguments)" do
+      gender = EnumeratedType.new(:male, :female)
+      gender.map(&:name).must_equal [:male, :female]
+    end
 
-      gender.map(&:value).must_equal [100, 101]
+    it "declares the given names as types (provides as array)" do
+      gender = EnumeratedType.new([:male, :female])
+      gender.map(&:name).must_equal [:male, :female]
     end
 
-    it "requires :value to be unique" do
-      duplicate_value = Gender.first.value
+    it "declares the given names as types (provides any enumerable)" do
+      gender = EnumeratedType.new(Set.new([:male, :female]))
+      gender.map(&:name).must_equal [:male, :female]
+    end
+  end
 
-      lambda { Gender.send(:declare, :neuter, :value => duplicate_value ) }.must_raise(ArgumentError, /duplicate :value/)
+  describe ".declare" do
+    it "is private" do
+      lambda { Gender.declare }.must_raise(NoMethodError, /private method `declare' called/)
     end
 
-    it "assigns extra attributes from .declare" do
-      Gender.map(&:planet).must_equal ["mars", "venus"]
+    it "requires the name to be unique" do
+      duplicate_name = Gender.first.name
+      lambda { Gender.send(:declare, duplicate_name) }.must_raise(ArgumentError, /duplicate name/)
     end
-  end
 
-  describe ".by_name" do
-    it "returns the type with the given name" do
-      gender = Gender.first
-      Gender.by_name(gender.name).must_equal gender
+    it "assigns properties and makes them accessible" do
+      Gender.map(&:planet).must_equal ["mars", "venus"]
     end
 
-    it "raises an error given an unrecognized name" do
-      lambda { Gender.by_name(:neuter) }.must_raise(ArgumentError)
+    it "does not expose public setters for properties" do
+      Gender::MALE.respond_to?(:planet=).must_equal false
     end
   end
 
-  describe ".by_value" do
-    it "returns the type with the given value" do
+  describe ".[]" do
+    it "returns the type with the given name" do
       gender = Gender.first
-      Gender.by_value(gender.value).must_equal gender
+      Gender[gender.name].must_equal gender
     end
 
-    it "raises an error given an unrecognized value" do
-      lambda { Gender.by_value((Gender.map(&:value).max) + 1) }.must_raise(ArgumentError)
+    it "raises an error given an unrecognized name" do
+      lambda { Gender[:neuter] }.must_raise ArgumentError
     end
   end
 
@@ -99,4 +101,16 @@ describe EnumeratedType do
       Gender.recognized?(:neuter).must_equal false
     end
   end
+
+  describe "#inspect" do
+    it "looks reasonable" do
+      Gender::FEMALE.inspect.must_equal "#<Gender:female>"
+    end
+  end
+
+  describe "#to_s" do
+    it "is the name (as a string)" do
+      Gender::MALE.to_s.must_equal "male"
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: enumerated_type
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-09-04 00:00:00.000000000 Z
+date: 2013-12-06 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: 2023803896666917699
+      hash: 37053798746470730
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -99,10 +99,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2023803896666917699
+      hash: 37053798746470730
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.23
+rubygems_version: 1.8.26
 signing_key: 
 specification_version: 3
 summary: Simple enumerated types