enum_table 0.0.1

data/.gitignore

@@ -0,0 +1,2 @@
+/Gemfile.lock
+/*.gem

data/CHANGELOG

@@ -0,0 +1,3 @@
+== 0.0.1 2012-11-05
+
+ * Hi.

data/Gemfile

@@ -0,0 +1,2 @@
+source :rubygems
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) George Ogata
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,136 @@
+## Enum Table
+
+Table-based enumerations for ActiveRecord.
+
+## What?
+
+When you have a column that should only take one of a finite set of string
+values (e.g., gender, statuses through some workflow), it's usually best not to
+store these as strings. Many databases, such as MySQL and PostgreSQL have native
+enum types which effectively let you treat these as strings while storing them
+internally using as few bytes as possible. Indeed there are already
+[plugins][enum_column3] that let you use these native enum types.
+
+But sometimes this is inadequate.
+
+Most obviously, not all databases have a native enum type, notably SQLite.
+
+Further, in the case of MySQL, the enum type leaves a lot to be desired in a
+production setting. If you need to do anything to the list of allowed values
+other than adding values to the end of the list, MySQL will rebuild the entire
+table, which can be very slow. Unless you're using something like
+[pt-online-schema-change][pt-osc], it will also lock the table during this
+period, which could be unacceptable for large tables.
+
+A common alternative is to simply keep the value-to-id mapping in the
+application, hardcoded in the model. The downside of this is that your database
+is no longer self-documenting: the integers mean nothing without the value
+mapping buried in your application code, making it hard to work with the
+database directly. Another problem is the database cannot enforce any
+[referential integrity][foreigner].
+
+This plugin implements a different strategy which solves the above problems -
+each enum is defined by a table with `id` and `value` columns, which defines the
+values and the integers they map to. Altering the values can be done with simple
+DDL statements, which do not require rebuilding any tables.
+
+[enum_column3]: https://github.com/taktsoft/enum_column3
+[pt-osc]: http://www.percona.com/doc/percona-toolkit/2.1/pt-online-schema-change.html
+[foreigner]: https://github.com/matthuhiggins/foreigner
+
+## Usage
+
+Create your enum tables in migrations. Example:
+
+    create_enum_table :user_genders do |t|
+      t.add :male
+      t.add :female
+    end
+
+Then add the enum ID to your model table:
+
+    add_column :users, :gender_id, null: false
+
+Then in your model:
+
+    class User < ActiveRecord::Base
+      enum :gender
+    end
+
+Note the convention: for a model `User` with enum `gender`, the column is
+`users.gender_id`, and the enum_table is `user_genders`. You can override these
+with the `:id_name` and `:table` options:
+
+    enum :gender, id_name: :sex_id, table: :sexes
+
+### Custom columns
+
+While the names `id` and `value` are fixed, you can change other attributes of
+the column. For example, the ID has `limit: 1` by default, but you can change
+this if you have a large list of enum values:
+
+    create_enum_table :user_countries do |t|
+      t.id limit: 2
+      t.add 'Afghanistan'
+      t.add 'Albania'
+      # ...
+    end
+
+Similarly you can customize the `value` column, say if you want to place a
+varchar limit:
+
+    create_enum_table :user_countries do |t|
+      t.value limit: 100
+      # ...
+    end
+
+### Updating enums
+
+To change the list of enums:
+
+    change_enum_table :user_genders do |t|
+      t.add :other
+      t.remove :male
+    end
+
+To drop an enum table:
+
+    drop_enum_table :user_genders
+
+Under the hood, `create_enum_table` and `drop_enum_table` maintain the list of
+enum tables in the `enum_tables` table. This allows the table data to be tracked
+by `db/schema.rb` so it gets copied to your test database.
+
+### Hardcoded mappings
+
+If you really want, you can forego the table completely and just hardcode the
+ids and values in your model:
+
+    enum :genders, table: {male: 1, female: 2}
+
+Or since our IDs are 1-based and sequential:
+
+    enum :genders, table: [:male, :female]
+
+Of course, by not using tables, you lose some of the advantages mentioned
+earlier, namely a self-documenting database and referential integrity.
+
+### Values
+
+By default, `user.gender` will be either the symbol `:male` or `:female`. If
+you're transitioning from using old-fashioned `varchar`s, however, you may find
+it less disruptive to use strings instead. Do that with the `:type` option:
+
+    enum :genders, type: :string
+
+## Contributing
+
+ * [Bug reports](https://github.com/howaboutwe/enum_table/issues)
+ * [Source](https://github.com/howaboutwe/enum_table)
+ * Patches: Fork on Github, send pull request.
+   * Include tests where practical.
+   * Leave the version alone, or bump it in a separate commit.
+
+## Copyright
+
+Copyright (c) HowAboutWe. See LICENSE for details.

data/Rakefile

@@ -0,0 +1 @@
+require 'ritual'

data/enum_table.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+$:.unshift File.expand_path('lib', File.dirname(__FILE__))
+require 'enum_table/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = 'enum_table'
+  gem.version       = EnumTable::VERSION
+  gem.authors       = ['George Ogata']
+  gem.email         = ['george.ogata@gmail.com']
+  gem.summary       = "Enumeration tables for ActiveRecord"
+  gem.homepage      = 'http://github.com/howaboutwe/enum_table'
+
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+
+  gem.add_runtime_dependency 'activerecord', '~> 3.2.0'
+  gem.add_development_dependency 'ritual', '~> 0.4.1'
+end

data/lib/enum_table.rb

@@ -0,0 +1,11 @@
+module EnumTable
+  autoload :VERSION, 'enum_table/version'
+  autoload :Record, 'enum_table/record'
+  autoload :Reflection, 'enum_table/reflection'
+  autoload :SchemaDumper, 'enum_table/schema_dumper'
+  autoload :SchemaStatements, 'enum_table/schema_statements'
+end
+
+require 'enum_table/railtie' if defined?(Rails)
+ActiveRecord::Base.send :include, EnumTable::Record
+ActiveRecord::ConnectionAdapters::AbstractAdapter.send :include, EnumTable::SchemaStatements

data/lib/enum_table/railtie.rb

@@ -0,0 +1,13 @@
+module EnumTable
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      namespace :enum_table do
+        task :load_schema_dumper do
+          require 'enum_table/schema_dumper'
+        end
+      end
+
+      Rake::Task['db:schema:dump'].prerequisites << 'enum_table:load_schema_dumper'
+    end
+  end
+end

data/lib/enum_table/record.rb

@@ -0,0 +1,214 @@
+module EnumTable
+  module Record
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :enums
+      self.enums = {}
+    end
+
+    module ClassMethods
+      def enum(name, options={})
+        name = name.to_sym
+        reflection = enums[name] ? enums[name].dup : Reflection.new(name)
+        [:type, :id_name].each do |key|
+          value = options[key] and
+            reflection.send "#{key}=", value
+        end
+        enum_map(name, options).each do |value, id|
+          reflection.add_value id, value
+        end
+        self.enums = enums.merge(name => reflection, name.to_s => reflection)
+
+        class_eval <<-EOS
+          def #{name}
+            read_enum(:#{name})
+          end
+
+          def #{name}=(value)
+            write_enum(:#{name}, value)
+          end
+
+          def #{name}?
+            query_enum(:#{name})
+          end
+
+          def #{name}_changed?
+            enum_changed?(:#{name})
+          end
+
+          def #{name}_was
+            enum_was(:#{name})
+          end
+
+          def #{name}_change
+            enum_change(:#{name})
+          end
+        EOS
+
+        reflection
+      end
+
+      def enum_map(name, options)
+        case (table = options[:table])
+        when Hash
+          table
+        when Array
+          map = {}
+          table.each_with_index { |element, i| map[element] = i + 1 }
+          map
+        when String, Symbol, nil
+          map = {}
+          table_name = table || "#{self.table_name.singularize}_#{name.to_s.pluralize}"
+          connection.execute("SELECT id, value FROM #{table_name}").each do |row|
+            map[row[1]] = row[0]
+          end
+          map
+        else
+          raise ArgumentError, "invalid table specifier: #{table.inspect}"
+        end
+      end
+
+      def reflect_on_enum(name)
+        enums[name]
+      end
+
+      def enum_id(name, value)
+        reflection = enums[name] or
+          raise ArgumentError, "no such enum: #{name}"
+        reflection.id(value)
+      end
+
+      # Enables enums for STI types.
+      def builtin_inheritance_column  # :nodoc:
+        # Can this be made less brittle?
+        if self == ActiveRecord::Base
+          'type'
+        else
+          (@builtin_inheritance_column ||= nil) || superclass.builtin_inheritance_column
+        end
+      end
+
+      def inheritance_enum  # :nodoc:
+        @inheritance_enum ||= enums[builtin_inheritance_column.to_sym]
+      end
+
+      def inheritance_column  # :nodoc:
+        (reflection = inheritance_enum) ? reflection.id_name.to_s : super
+      end
+
+      def sti_name  # :nodoc:
+        (reflection = inheritance_enum) ? reflection.id(super) : super
+      end
+
+      def find_sti_class(type_name)  # :nodoc:
+        (reflection = inheritance_enum) ? super(reflection.value(type_name).to_s) : super
+      end
+
+      # Enables .find_by_name(value) for enums.
+      def expand_hash_conditions_for_aggregates(attrs)  # :nodoc:
+        conditions = super
+        enums.each do |name, reflection|
+          if conditions.key?(name)
+            value = conditions.delete(name)
+          elsif conditions.key?((string_name = name.to_s))
+            value = conditions.delete(string_name)
+          else
+            next
+          end
+          if value.is_a?(Array)
+            id = value.map { |el| reflection.id(el) }
+          else
+            id = reflection.id(value)
+          end
+          conditions[reflection.id_name] = id
+        end
+        conditions
+      end
+
+      # Enables .where(name: value) for enums.
+      def expand_attribute_names_for_aggregates(attribute_names)  # :nodoc:
+        attribute_names = super
+        enums.each do |name, reflection|
+          index = attribute_names.index(name) and
+            attribute_names[index] = reflection.id_name
+        end
+        attribute_names
+      end
+
+      # Enables state_machine to set initial values for states. Ick.
+      def initialize_attributes(attributes)  # :nodoc:
+        attributes = super
+        enums.each do |name, reflection|
+          if (value = attributes.delete(reflection.name.to_s))
+            attributes[reflection.id_name.to_s] ||= reflection.id(value)
+          end
+        end
+        attributes
+      end
+    end
+
+    def enum(name)
+      self.class.enums[name]
+    end
+
+    def enum!(name)
+      self.class.enums[name] or
+        raise ArgumentError, "no such enum: #{name}"
+    end
+
+    def enum_id(name, value)
+      self.class.enum_id(name, value)
+    end
+
+    def read_enum(name)
+      reflection = enum!(name)
+      id = read_attribute(reflection.id_name)
+      reflection.value(id)
+    end
+
+    def query_enum(name)
+      reflection = enum!(name)
+      id = read_attribute(reflection.id_name)
+      !!reflection.value(id)
+    end
+
+    def write_enum(name, value)
+      reflection = enum!(name)
+      id = reflection.id(value)
+      write_attribute(reflection.id_name, id)
+      value
+    end
+
+    def enum_changed?(name)
+      reflection = enum!(name)
+      attribute_changed?(reflection.id_name.to_s)
+    end
+
+    def enum_was(name)
+      reflection = enum!(name)
+      id = attribute_was(reflection.id_name.to_s)
+      reflection.value(id)
+    end
+
+    def enum_change(name)
+      reflection = enum!(name)
+      change = attribute_change(reflection.id_name.to_s) or
+        return nil
+      old_id, new_id = *change
+      [reflection.value(old_id), reflection.value(new_id)]
+    end
+
+    def read_attribute(name)
+      reflection = enum(name) or
+        return super
+      read_enum(name)
+    end
+
+    def write_attribute(name, value)
+      reflection = enum(name) or
+        return super
+      write_enum(name, value)
+    end
+  end
+end

data/lib/enum_table/reflection.rb

@@ -0,0 +1,52 @@
+module EnumTable
+  class Reflection
+    def initialize(name, options={})
+      @name = name
+      @id_name = options[:id_name] || :"#{name}_id"
+      @type = options[:type] || :symbol
+      @type == :string || @type == :symbol or
+        raise ArgumentError, "invalid type: #{type.inspect}"
+
+      @strings_to_ids = {}
+      @values_to_ids = {}
+      @ids_to_values = {}
+    end
+
+    def initialize_copy(other)
+      @name = other.name
+      @id_name = other.id_name
+      @type = other.type
+
+      @strings_to_ids = other.instance_variable_get(:@strings_to_ids).dup
+      @values_to_ids = other.instance_variable_get(:@values_to_ids).dup
+      @ids_to_values = other.instance_variable_get(:@ids_to_values).dup
+    end
+
+    attr_reader :name
+    attr_accessor :id_name, :type
+
+    def add_value(id, value)
+      @strings_to_ids[value.to_s] = id
+
+      cast_value = @type == :string ? value.to_s : value.to_sym
+      @values_to_ids[cast_value] = id
+      @ids_to_values[id] = cast_value
+    end
+
+    def id(value)
+      if value.is_a?(String) || type == :string
+        @strings_to_ids[value.to_s.strip]
+      else
+        @values_to_ids[value]
+      end
+    end
+
+    def value(id)
+      @ids_to_values[id]
+    end
+
+    def values
+      @values_to_ids.keys
+    end
+  end
+end