legacy_enum 0.0.1 → 0.1.0

data/README.md

@@ -0,0 +1,151 @@
+# LegacyEnum
+
+Allows your Rails app to interact with C-style integer-backed enumeration db columns using a more Ruby-ish syntax. 
+
+```ruby
+class Employee < ActiveRecord::Base
+  legacy_enum :payroll_type, lookup: :payroll_type_id do |e|
+    e.salaried 1
+    e.full_time 2
+    e.part_time 3
+  end
+end
+
+# You can use a symbol syntax for more readable code.
+employee = Employee.new
+employee.payroll_type = :salaried
+
+# The database still sees the column as an integer
+p employee.payroll_type_id 
+# >> 1
+
+# Labels are provided for humanized display of your enum values
+p employee.payroll_type_label
+# >> Salaried
+
+# You can still address the column as a integer field (if you have to)
+employee.payroll_type_id = 3
+p employee.payroll_type
+# >> :part_time
+```
+
+## Requires
+
+* Rails >= 3.0
+* Ruby >= 1.9.2
+
+## Why?
+
+Lots of legacy apps written in C/C++/C#/Java have integer columns in the database that represent enumerated values in the system. 
+
+For example, in a legacy system dealing with employees, an employee might be classified with a C-style enumeration like: 
+
+```c
+enum PayrollType { Salaried = 1, FullTime, PartTime }
+// stored in a db column named "PayrollTypeID" as its integer value
+```
+
+This could be accessed using legacy_enum like so:
+
+```ruby  
+legacy_enum :payroll_type do |e|
+  e.salaried 1
+  e.full_time 2
+  e.part_time 3
+end
+```
+
+## Usage
+
+```ruby
+legacy_enum [rails_friendly_name], options do |e|
+  e.enumerated_name value, [options]
+  ...
+end
+```
+
+## Options
+
+#### Lookups
+
+Conventionally, legacy_enum assumes that the backing int column is named the same as your field name, capitalized and postfixed with "ID". If that isn't the case, use the "lookup" option.
+
+```ruby
+legacy_enum :payroll_type, lookup: :unconventional_id_column_name do |e|
+  ...
+end
+```
+
+#### Values
+
+Legacy_enum requires that a backing value be provided for each enumerated name. A value can be an integer or a string.
+
+```ruby
+legacy_enum :int_values do |e|
+  e.some_value 32
+  e.another_value 64
+end
+
+legacy_enum :string_values do |e|
+  e.a_string_value_is_ok 'zip_zop_zoobity_bop'
+  e.another_string 'here_i_go_down_the_slope'
+end
+```
+
+#### Labels
+
+Labels are automatically created and conventionally have the name [legacy_enum_field]_label. For instance, this definition would have a label named 'foo_label'
+
+```ruby  
+legacy_enum :foo do |e|
+  e.some_value 1
+end
+```
+
+Each enumerated name, by default, has a label that is just the ActiveSupport#Titleized version of the enum name. This can be overridden using the 'label' option for each value.
+
+```ruby
+legacy_enum :foo do |e|
+  e.crazy_label 1, label: 'Roflcopter'
+end
+
+foo = :crazy_label
+p foo_label
+# >> 'Roflcopter'
+```
+
+#### Scopes
+
+ActiveRecord scopes can be created for your enumerated field, although by default they are not. The 'scope' option supports two values, :many and :one. 'Many' creates a scope with the enumeration name that accepts symbol values for the scope. 
+
+```ruby
+class Employee < ActiveRecord::Base
+  legacy_enum :payroll_type, lookup: :payroll_type_id, scope: :many do |e|
+    e.salaried 1
+    e.full_time 2
+    e.part_time 3
+  end
+end
+
+# The following scopes are created
+Employee.payroll_type(:salaried) 
+# 'SELECT * FROM employees WHERE payroll_type_id = 1'
+Employee.salaried
+# 'SELECT * FROM employees WHERE payroll_type_id = 1'
+Employee.full_time
+# 'SELECT * FROM employees WHERE payroll_type_id = 2'
+Employee.part_time
+# 'SELECT * FROM employees WHERE payroll_type_id = 3'
+```
+
+## Who?
+  
+legacy_enum was written by [Sean Scally](http://github.com/anydiem) for [AutoRevo](http://www.autorevo.com) with code contributed by [Matt Shannon](http://github.com/dmshann0n). 
+
+legacy_enum was inspired by jeffp's [enumerated_attribute](http://github.com/jeffp/enumerated_attribute).
+
+## License
+
+Released under the MIT license:
+
+* http://www.opensource.org/licenses/MIT

data/lib/legacy_enum/class_methods.rb

@@ -1,84 +1,79 @@
 module LegacyEnum
   module ClassMethods
     def legacy_enum(name, *options, &block)
-      values_name = "@@#{name}_values".downcase
-      options = options.extract_options!
-      id_attr_name = options[:lookup].try(:to_s) || "#{name.to_s.capitalize}ID"
+      extracted_options = options.extract_options!
+      id_attr_name = extracted_options[:lookup].try(:to_s) || "#{name.to_s.capitalize}ID"
 
       config = MethodDefinitionDSL.new
       config.instance_eval(&block)
 
       cattr_accessor :enum_config unless defined? self.enum_config
       self.enum_config ||= {}
-      self.enum_config[name] = config.enum_def
 
-      #TODO make more lightweight by conditionally adding these methods on first use via method_missing
+      self.enum_config[name] = { values: config.enum_def, lookup: id_attr_name }
+
       class_eval do
-        if options[:scope]
-          scope name.to_sym, lambda { |enum_val|
-            { :conditions => { id_attr_name.to_sym => enums[name.to_sym][enum_val] } }
-          }
-          self.enums[name].keys.each do |value|
-            if options[:scope] == :one
-              (class << self; self; end).instance_eval do
-                define_method value.to_sym, lambda { 
-                  send(name.to_sym, value.to_sym).first
-                }
-              end
-            else
-              (class << self; self; end).instance_eval do
-                define_method value.to_sym, lambda { 
-                  send(name.to_sym, value.to_sym)
-                }
-              end
-            end
-          end
+
+        define_method name do
+          enum_config[name][:values].valued(legacy_value(name))[:name]
         end
 
-        find_enum_entry = Proc.new do |_self, name, sym|
-          enum_entry = _self.enum_config[name].find do |hash|
-            attr_value = _self.send(id_attr_name.to_sym)
-            attr_value.to_s.upcase == hash[:value].to_s.upcase
-          end
+        define_method "#{name}=" do |value|
+          set_value = enum_config[name][:values].named(value)[:value]
+          set_legacy_value name, set_value
+        end
 
-          enum_entry[sym] unless enum_entry.blank?
+        define_method "#{name}_label" do
+          enum_config[name][:values].valued(legacy_value(name))[:label]
         end
 
-        define_method name do
-          find_enum_entry.call(self, name, :name)
+        def legacy_value(name)
+          send enum_config[name][:lookup].to_sym
         end
 
-        define_method "#{name}=" do |value|
-          self.send("#{id_attr_name}=".to_sym, nil) if value.blank?
-          enum_entry = self.enum_config[name].find { |hash| hash[:name] == (value.blank? ? value : value.to_sym) }
-          unless enum_entry.blank?
-            self.send("#{id_attr_name}=".to_sym, enum_entry[:value])
-          end
+        def set_legacy_value(name, value)
+          send "#{enum_config[name][:lookup]}=".to_sym, value
         end
 
-        define_method "#{name}_label" do
-          find_enum_entry.call(self, name, :label)
+        return unless extracted_options[:scope]
+        
+        scope name.to_sym, 
+          lambda { |enum_value| where(id_attr_name => enum_config[name][:values].named(enum_value)[:value] ) }
+        
+        enum_config[name][:values].each do |config|
+          singleton_class.instance_eval do
+            if extracted_options[:scope] == :one
+              define_method config[:name].to_sym, lambda { send(name, config[:name]).first }
+            else
+              define_method config[:name].to_sym, lambda { send(name, config[:name]) }
+            end
+          end
         end
+        
       end
+
     end
 
+    # Returns all enumerations for the class by enum_name and then name => value
     def enums
       inject_block(:name, :value)
     end
 
+    # Returns all enumerations for the class by enum_name and then name => label
     def labels
       inject_block(:name, :label)
     end
 
+    # Returns all enumerations for the class by enum_name and then value => name
     def enum_ids
       inject_block(:value, :name)
     end
 
   private
-    #this name sux, refactor it
+    # Restructures the enum_config around a key/value pair
     def inject_block(key, value)
       self.enum_config.inject({}) do |acc, (name,config)|
-        acc.merge( { name => config.inject({}) do |inner_acc, enum_item|
+        acc.merge( { name => config[:values].inject({}) do |inner_acc, enum_item|
           inner_acc.merge( { enum_item[key] => enum_item[value] } )
         end })
       end

data/lib/legacy_enum/configuration_search.rb

@@ -0,0 +1,21 @@
+module LegacyEnum
+  module ConfigurationSearch
+    def named(name)
+      find { |config| config[:name] == name } || null_definition
+    end
+
+    def valued(value)
+      search_value = value.to_s.upcase
+      find { |config| config[:value].to_s.upcase === search_value } || null_definition
+    end
+
+    def labelled(label)
+      find { |config| config[:label] == label } || null_definition
+    end
+
+    private
+      def null_definition
+        { name: nil, value: nil, label: nil }
+      end
+  end
+end

data/lib/legacy_enum/method_definition_dsl.rb

@@ -4,6 +4,7 @@ module LegacyEnum
 
     def method_missing(symbol, *args)
       @enum_def ||= []
+      @enum_def.singleton_class.send :include, ConfigurationSearch
       
       options = args.extract_options!
       

data/lib/legacy_enum/version.rb

@@ -1,3 +1,3 @@
 module LegacyEnum
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/lib/legacy_enum.rb

@@ -1,5 +1,6 @@
 require 'active_record'
 
+require 'legacy_enum/configuration_search'
 require 'legacy_enum/method_definition_dsl'
 require 'legacy_enum/class_methods'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legacy_enum
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-02-08 00:00:00.000000000 Z
+date: 2012-02-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
-  requirement: &70179477187020 !ruby/object:Gem::Requirement
+  requirement: &70249318379200 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>'
@@ -21,10 +21,10 @@ dependencies:
         version: 3.0.0
   type: :runtime
   prerelease: false
-  version_requirements: *70179477187020
+  version_requirements: *70249318379200
 - !ruby/object:Gem::Dependency
   name: sqlite3
-  requirement: &70179477186600 !ruby/object:Gem::Requirement
+  requirement: &70249318378160 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70179477186600
+  version_requirements: *70249318378160
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70179477186140 !ruby/object:Gem::Requirement
+  requirement: &70249318376680 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,7 +43,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70179477186140
+  version_requirements: *70249318376680
 description: Allows you to address enumerated integer columns as more sane and readable
   symbols
 email:
@@ -53,13 +53,14 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/legacy_enum/class_methods.rb
+- lib/legacy_enum/configuration_search.rb
 - lib/legacy_enum/method_definition_dsl.rb
 - lib/legacy_enum/version.rb
 - lib/legacy_enum.rb
 - lib/tasks/legacy_enum_tasks.rake
 - MIT-LICENSE
 - Rakefile
-- README.rdoc
+- README.md
 homepage: http://github.com/anydiem/legacy_enum
 licenses: []
 post_install_message: 

data/README.rdoc

@@ -1,5 +0,0 @@
-= LegacyEnum
-
-= TODO
-  - Refactor test cases
-  - More test coverage