classy_enum 2.3.0 → 3.0.0

data/.gitignore

@@ -15,3 +15,4 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+.DS_Store

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # ClassyEnum Changelog
 
+## 3.0.0
+
+* Removing ClassyEnum::Base.enum_classes in favor of using enum
+  inheritance to setup classes
+* Removing ClassyEnum::Base.valid_options
+* Removing ClassyEnum::Base.find
+* Removing ClassyEnum::Base#name
+* Removing :suffix option from classy_enum_attr
+* Enforce use of namespacing for subclasses (Parent::Child < Parent)
+* Use require instead of autoload
+* Lots of code refactoring
+
 ## 2.3.0
 
 * Deprecating ClassyEnum::Base#name (use to_s.titleize instead). `name` is

data/README.md

@@ -6,12 +6,12 @@ ClassyEnum is a Ruby on Rails gem that adds class-based enumerator functionality
 
 ## Rails & Ruby Versions Supported
 
-*Rails:*
+*Rails:* 3.0.x - 3.2.x
 
-  * 3.0.x - 3.2.x: Fully tested in a production application.
-  * 2.3.x: If you need support for Rails 2.3.x, please install [version 0.9.1](https://rubygems.org/gems/classy_enum/versions/0.9.1)
+*Ruby:* 1.8.7, 1.9.2 and 1.9.3
 
-*Ruby:* Ruby 1.8.7, 1.9.2, and 1.9.3 are tested and supported
+If you need support for Rails 2.3.x, please install [version 0.9.1](https://rubygems.org/gems/classy_enum/versions/0.9.1).
+Note: This branch is no longer maintained and will not get bug fixes or new features.
 
 ## Installation
 
@@ -19,15 +19,9 @@ The gem is hosted at [rubygems.org](https://rubygems.org/gems/classy_enum)
 
 You will also need to add `app/enums` as an autoloadable path. This configuration will depend on which version of rails you are using.
 
-## Upgrading to 2.0
+## Upgrading?
 
-Prior to 2.0, enum classes were implicity defined and were only required
-when overriding methods or properties. As of 2.0, all enum classes must
-explicity subclass a child of ClassyEnum::Base. If you used the
-generator, there are no changes to the existing structure.
-
-Built-in Formtastic support has been removed. See the note at the
-bottom of this readme for more information how how to enable it.
+See the [wiki](https://github.com/beerlington/classy_enum/wiki/Upgrading) for notes about upgrading from previous versions.
 
 ## Example Usage
 
@@ -45,20 +39,19 @@ A new enum template file will be created at app/enums/priority.rb that will look
 
 ```ruby
 class Priority < ClassyEnum::Base
-  enum_classes :low, :medium, :high
 end
 
-class PriorityLow < Priority
+class Priority::Low < Priority
 end
 
-class PriorityMedium < Priority
+class Priority::Medium < Priority
 end
 
-class PriorityHigh < Priority
+class Priority::High < Priority
 end
 ```
 
-The `enum_classes` class macro will define the enum member order as well as additional ClassyEnum behavior, which is described further down in this document.
+The class order will define the enum member order as well as additional ClassyEnum behavior, which is described further down in this document.
 
 ### 2. Customize the Enum
 
@@ -70,20 +63,18 @@ I would like to add a method called `send_email?` that all member subclasses res
 
 ```ruby
 class Priority < ClassyEnum::Base
-  enum_classes :low, :medium, :high
-
   def send_email?
     false
   end
 end
 
-class PriorityLow < Priority
+class Priority::Low < Priority
 end
 
-class PriorityMedium < Priority
+class Priority::Medium < Priority
 end
 
-class PriorityHigh < Priority
+class Priority::High < Priority
   def send_email?
     true
   end
@@ -119,11 +110,10 @@ With this setup, I can now do the following:
 ```ruby
 @alarm = Alarm.create(:priority => :medium)
 
-@alarm.priority  # => PriorityMedium
+@alarm.priority  # => Priority::Medium
 @alarm.priority.medium? # => true
 @alarm.priority.high? # => false
 @alarm.priority.to_s # => 'medium'
-@alarm.priority.name # => 'Medium'
 
 # Should this alarm send an email?
 @alarm.send_email? # => false
@@ -137,7 +127,7 @@ The enum field works like any other model attribute. It can be mass-assigned usi
 
 In some cases you may want an enum class to reference the owning object
 (an instance of the active record model). Think of it as a `belongs_to`
-relationship, where the enum can reference its owning object.
+relationship, where the enum belongs to the model.
 
 By default, the back reference can be called using `owner`.
 If you want to refer to the owner by a different name, you must explicitly declare
@@ -147,14 +137,11 @@ Example using the default `owner` method:
 
 ```ruby
 class Priority < ClassyEnum::Base
-  enum_classes :low, :medium, :high
 end
 
-...
 # low and medium subclasses omitted
-...
 
-class PriorityHigh < Priority
+class Priority::High < Priority
   def send_email?
     owner.enabled?
   end
@@ -165,15 +152,12 @@ Example where the owner reference is explicitly declared:
 
 ```ruby
 class Priority < ClassyEnum::Base
-  enum_classes :low, :medium, :high
   owner :alarm
 end
 
-...
 # low and medium subclasses omitted
-...
 
-class PriorityHigh < Priority
+class Priority::High < Priority
   def send_email?
     alarm.enabled?
   end
@@ -213,28 +197,15 @@ end
 
 ## Special Cases
 
-What if your enum class name is not the same as your model's attribute name? No problem! Just use a second arugment in `classy_enum_attr` to declare the attribute name. In this case, the model's attribute is called *alarm_priority*.
+What if your enum class name is not the same as your model's attribute name? No problem! Just use a second argument in `classy_enum_attr` to declare the attribute name. In this case, the model's attribute is called *alarm_priority*.
 
 ```ruby
 class Alarm < ActiveRecord::Base
-  classy_enum_attr :alarm_priority, :enum => :priority
+  classy_enum_attr :alarm_priority, :enum => 'Priority'
 end
 
 @alarm = Alarm.create(:alarm_priority => :medium)
-@alarm.alarm_priority  # => PriorityMedium
-```
-
-If you would like the default getter method to return a string, you can
-use the optional *:suffix* option for the enum getter:
-
-```ruby
-class Alarm < ActiveRecord::Base
-  classy_enum_attr :priority, :suffix => 'type'
-end
-
-alarm = Alarm.create(:priority => :high)
-alarm.priority # => 'high'
-alarm.priority_type # instance of PriorityHigh enum
+@alarm.alarm_priority  # => Priority::Medium
 ```
 
 ## Model Validation
@@ -265,20 +236,13 @@ end
 
 While ClassyEnum was designed to be used directly with ActiveRecord, it can also be used outside of it. Here are some examples based on the enum class defined earlier in this document.
 
-Instantiate an enum member subclass *PriorityLow*
+Instantiate an enum member subclass *Priority::Low*
 
 ```ruby
 # These statements are all equivalent
 low = Priority.build(:low)
 low = Priority.build('low')
-low = Priority.find(:low)
-low = PriorityLow.new
-```
-
-Get a list of the valid enum options
-
-```ruby
-Priority.valid_options # => low, medium, high
+low = Priority::Low.new
 ```
 
 ## Formtastic Support

data/classy_enum.gemspec

@@ -16,7 +16,7 @@ Gem::Specification.new do |gem|
 
   gem.add_dependency('rails', '>= 3.0')
 
-  gem.add_development_dependency('rspec-rails', '~> 2.10.0')
+  gem.add_development_dependency('rspec-rails', '~> 2.11.0')
   gem.add_development_dependency('sqlite3', '~> 1.3.6')
   gem.add_development_dependency('json', '~> 1.6.5')
 

data/gemfiles/Gemfile.rails-3.0.x

@@ -1,8 +1,6 @@
 source :rubygems
 
 gem 'rails', '~> 3.0.0'
-gem 'rspec-rails', '~> 2.8.1'
-gem 'formtastic', '~> 1.2.4'
+gem 'rspec-rails', '~> 2.11.0'
 gem 'sqlite3-ruby', :require => 'sqlite3'
-gem 'json', '~> 1.6.5'
-gem "jeweler", "~> 1.6.2"
+gem 'json', '~> 1.6.5'

data/gemfiles/Gemfile.rails-3.1.x

@@ -1,8 +1,6 @@
 source :rubygems
 
 gem 'rails', '~> 3.1.0'
-gem 'rspec-rails', '~> 2.8.1'
-gem 'formtastic', '~> 1.2.4'
+gem 'rspec-rails', '~> 2.11.0'
 gem 'sqlite3'
-gem 'json', '~> 1.6.5'
-gem "jeweler", "~> 1.6.2"
+gem 'json', '~> 1.6.5'

data/gemfiles/Gemfile.rails-3.2.x

@@ -1,8 +1,6 @@
 source :rubygems
 
 gem 'rails', '~> 3.2.0'
-gem 'rspec-rails', '~> 2.8.1'
-gem 'formtastic', '~> 1.2.4'
+gem 'rspec-rails', '~> 2.11.0'
 gem 'sqlite3'
-gem 'json', '~> 1.6.5'
-gem "jeweler", "~> 1.6.2"
+gem 'json', '~> 1.6.5'

data/lib/classy_enum/active_record.rb

@@ -0,0 +1,58 @@
+module ClassyEnum
+  module ActiveRecord
+
+    # Class macro used to associate an enum with an attribute on an ActiveRecord model.
+    # This method is automatically added to all ActiveRecord models when the classy_enum gem
+    # is installed. Accepts an argument for the enum class to be associated with
+    # the model. ActiveRecord validation is automatically added to ensure
+    # that a value is one of its pre-defined enum members.
+    #
+    # ==== Example
+    #  # Associate an enum Priority with Alarm model's priority attribute
+    #  class Alarm < ActiveRecord::Base
+    #    classy_enum_attr :priority
+    #  end
+    #
+    #  # Associate an enum Priority with Alarm model's alarm_priority attribute
+    #  classy_enum_attr :alarm_priority, :enum => 'Priority'
+    #
+    #  # Allow enum value to be nil
+    #  classy_enum_attr :priority, :allow_nil => true
+    #
+    #  # Allow enum value to be blank
+    #  classy_enum_attr :priority, :allow_blank => true
+    def classy_enum_attr(attribute, options={})
+      enum              = (options[:enum] || attribute).to_s.camelize.constantize
+      allow_blank       = options[:allow_blank] || false
+      allow_nil         = options[:allow_nil] || false
+      serialize_as_json = options[:serialize_as_json] || false
+
+      error_message    = "must be #{enum.all.to_sentence(:two_words_connector => ' or ', :last_word_connector => ', or ')}"
+
+      # Add ActiveRecord validation to ensure it won't be saved unless it's an option
+      validates_inclusion_of attribute,
+        :in          => enum.all,
+        :message     => error_message,
+        :allow_blank => allow_blank,
+        :allow_nil   => allow_nil
+
+      # Define getter method that returns a ClassyEnum instance
+      define_method attribute do
+        enum.build(read_attribute(attribute),
+                   :owner             => self,
+                   :serialize_as_json => serialize_as_json,
+                   :allow_blank       => (allow_blank || allow_nil)
+                  )
+      end
+
+      # Define setter method that accepts either string or symbol for member
+      define_method "#{attribute}=" do |value|
+        value = value.to_s unless value.nil?
+        super(value)
+      end
+    end
+
+  end
+end
+
+ActiveRecord::Base.send :extend, ClassyEnum::ActiveRecord

data/lib/classy_enum/base.rb

@@ -1,8 +1,88 @@
 module ClassyEnum
+  class SubclassNameError < Exception; end
+
   class Base
-    extend ClassyEnum::ClassMethods
-    include ClassyEnum::InstanceMethods
     include Comparable
-    include ActiveModel::AttributeMethods
+    include Conversion
+    include Predicate
+    include Collection
+
+    class_attribute :base_class
+    attr_accessor :owner, :serialize_as_json, :allow_blank
+
+    class << self
+      def inherited(klass)
+        if self == ClassyEnum::Base
+          klass.base_class = klass
+        else
+
+          # Ensure subclasses follow expected naming conventions
+          unless klass.name.start_with? "#{base_class.name}::"
+            raise SubclassNameError, "subclass must be namespaced with #{base_class.name}::"
+          end
+
+          # Add visit_EnumMember methods to support validates_uniqueness_of with enum field
+          # This is due to a bug in Rails where it uses the method result as opposed to the
+          # database value for validation scopes. A fix will be released in Rails 4, but
+          # this will remain until Rails 3.x is no longer prevalent.
+          Arel::Visitors::ToSql.class_eval do
+            define_method "visit_#{klass.name.split('::').join('_')}", lambda {|value| quote(value.to_s) }
+          end
+
+          # Convert from MyEnumClass::NumberTwo to :number_two
+          enum = klass.name.split('::').last.underscore.to_sym
+
+          Predicate.define_predicate_method(klass, enum)
+
+          klass.instance_variable_set('@option', enum)
+        end
+
+        super
+      end
+
+      # Used internally to build a new ClassyEnum child instance
+      # It is preferred that you use ChildClass.new instead
+      #
+      # ==== Example
+      #  # Create an Enum with some elements
+      #  class Priority < ClassyEnum::Base
+      #  end
+      #
+      #  class Priority::Low < Priority
+      #  end
+      #
+      #  Priority.build(:low) # => Priority::Low.new
+      #  Priority.build(:invalid_option) # => :invalid_option
+      def build(value, options={})
+        return value if value.blank? && options[:allow_blank]
+
+        # Return the value if it is not a valid member
+        return value unless all.map(&:to_s).include? value.to_s
+
+        object = "#{base_class}::#{value.to_s.camelize}".constantize.new
+        object.owner = options[:owner]
+        object.serialize_as_json = options[:serialize_as_json]
+        object.allow_blank = options[:allow_blank]
+        object
+      end
+
+      # DSL setter method for overriding reference to enum owner (ActiveRecord model)
+      #
+      # ==== Example
+      #  # Create an Enum with some elements
+      #  class Priority < ClassyEnum::Base
+      #    owner :alarm
+      #  end
+      #
+      #  class Priority::High < Priority
+      #    def send_alarm?
+      #      alarm.enabled?
+      #    end
+      #  end
+      def owner(owner)
+        define_method owner, lambda { @owner }
+      end
+    end
+
   end
 end

data/lib/classy_enum/collection.rb

@@ -0,0 +1,76 @@
+module ClassyEnum
+  module Collection
+    # Sort an array of elements based on the order they are defined
+    #
+    # ==== Example
+    #  # Create an Enum with some elements
+    #  class Priority < ClassyEnum::Base
+    #  end
+    #
+    #  class Priority::Low < Priority; end
+    #  class Priority::Medium < Priority; end
+    #  class Priority::High < Priority; end
+    #
+    #  @low = Priority.build(:low)
+    #  @medium = Priority.build(:medium)
+    #  @high = Priority.build(:high)
+    #  priorities = [@low, @high, @medium]
+    #  priorities.sort # => [@low, @medium, @high]
+    #  priorities.max # => @high
+    #  priorities.min # => @low
+    def <=> other
+      index <=> other.index
+    end
+
+    def self.included(klass)
+      klass.extend ClassMethods
+    end
+
+    module ClassMethods
+      def inherited(klass)
+        if self == ClassyEnum::Base
+          klass.class_attribute :enum_options
+          klass.enum_options = []
+        else
+          enum_options << klass
+          klass.instance_variable_set('@index', enum_options.size)
+        end
+
+        super
+      end
+
+      # Returns an array of all instantiated enums
+      #
+      # ==== Example
+      #  # Create an Enum with some elements
+      #  class Priority < ClassyEnum::Base
+      #  end
+      #
+      #  class Priority::Low < Priority; end
+      #  class Priority::Medium < Priority; end
+      #  class Priority::High < Priority; end
+      #
+      #  Priority.all # => [Priority::Low.new, Priority::Medium.new, Priority::High.new]
+      def all
+        enum_options.map(&:new)
+      end
+
+      # Returns a 2D array for Rails select helper options.
+      # Also used internally for Formtastic support
+      #
+      # ==== Example
+      #  # Create an Enum with some elements
+      #  class Priority < ClassyEnum::Base
+      #  end
+      #
+      #  class Priority::Low < Priority; end
+      #  class Priority::ReallyHigh < Priority; end
+      #
+      #  Priority.select_options # => [["Low", "low"], ["Really High", "really_high"]]
+      def select_options
+        all.map {|e| [e.to_s.titleize, e.to_s] }
+      end
+    end
+
+  end
+end

data/lib/classy_enum/conversion.rb

@@ -0,0 +1,69 @@
+module ClassyEnum
+  module Conversion
+
+    # Returns an integer representing the order that this element was defined in.
+    # Also used internally for sorting.
+    #
+    # ==== Example
+    #  # Create an Enum with some elements
+    #  class Priority < ClassyEnum::Base
+    #  end
+    #
+    #  class Priority::Low < Priority; end
+    #  class Priority::Medium < Priority; end
+    #  class Priority::High < Priority; end
+    #
+    #  @priority = Priority::Medium.new
+    #  @priority.to_i # => 2
+    def to_i
+      self.class.instance_variable_get('@index')
+    end
+
+    alias :index :to_i
+
+    # Returns the name or string corresponding to element
+    #
+    # ==== Example
+    #  # Create an Enum with some elements
+    #  class Priority < ClassyEnum::Base
+    #  end
+    #
+    #  class Priority::Low < Priority; end
+    #  class Priority::Medium < Priority; end
+    #  class Priority::High < Priority; end
+    #
+    #  @priority = Priority::Low.new
+    #  @priority.to_s # => 'low'
+    def to_s
+      self.class.instance_variable_get('@option').to_s
+    end
+
+    # Returns a Symbol corresponding to a string representation of element,
+    # creating the symbol if it did not previously exist
+    #
+    # ==== Example
+    #  # Create an Enum with some elements
+    #  class Priority < ClassyEnum::Base
+    #  end
+    #
+    #  class Priority::Low < Priority; end
+    #  class Priority::Medium < Priority; end
+    #  class Priority::High < Priority; end
+    #
+    #  @priority = Priority::Low.new
+    #  @priority.to_sym # => :low
+    def to_sym
+      to_s.to_sym
+    end
+
+    # Overrides as_json to remove owner reference recursion issues
+    def as_json(options=nil)
+      return to_s unless serialize_as_json
+      json = super(options)
+      json.delete('owner')
+      json.delete('serialize_as_json')
+      json
+    end
+
+  end
+end

data/lib/classy_enum/predicate.rb

@@ -0,0 +1,35 @@
+module ClassyEnum
+  module Predicate
+
+    # Define attribute methods like two?
+    def self.define_predicate_method(klass, enum)
+      klass.base_class.class_eval do
+        define_method "#{enum}?", lambda { attribute?(enum.to_s) }
+      end
+    end
+
+    protected
+
+    # Determine if the enum attribute is a particular member.
+    #
+    # ==== Example
+    #  # Create an Enum with some elements
+    #  class Breed < ClassyEnum::Base
+    #  end
+    #
+    # class Breed::GoldenRetriever < Breed; end
+    # class Breed::Snoop < Breed; end
+    #
+    #  # Create an ActiveRecord class using the Breed enum
+    #  class Dog < ActiveRecord::Base
+    #    classy_enum_attr :breed
+    #  end
+    #
+    #  @dog = Dog.new(:breed => :snoop)
+    #  @dog.breed.snoop? # => true
+    #  @dog.breed.golden_retriever? # => false
+    def attribute?(attribute)
+      to_s == attribute
+    end
+  end
+end

data/lib/classy_enum/version.rb

@@ -1,3 +1,3 @@
 module ClassyEnum
-  VERSION = "2.3.0"
+  VERSION = "3.0.0"
 end

data/lib/classy_enum.rb

@@ -1,8 +1,5 @@
-module ClassyEnum
-  autoload :Base, 'classy_enum/base'
-  autoload :InstanceMethods, 'classy_enum/instance_methods'
-  autoload :ClassMethods, 'classy_enum/class_methods'
-  autoload :Attributes, 'classy_enum/attributes'
-end
-
-ActiveRecord::Base.send :extend, ClassyEnum::Attributes
+require 'classy_enum/collection'
+require 'classy_enum/conversion'
+require 'classy_enum/predicate'
+require 'classy_enum/base'
+require 'classy_enum/active_record'

data/lib/generators/classy_enum/templates/enum.rb

@@ -1,5 +1,4 @@
 class <%= class_name %> < ClassyEnum::Base
-  enum_classes <%= values.map {|a| ":#{a}"}.join(", ") %>
 end
 <% values.each do |arg| %>
 class <%= "#{class_name}::#{arg.camelize}" %> < <%= class_name %>