galetahub-enum_field 0.1.4

data/README.rdoc

@@ -0,0 +1,127 @@
+= enum_field
+
+* http://github.com/paraseba/enum_field
+
+== DESCRIPTION:
+
+Enables Active Record attributes to point to enum like objects, by saving in your database
+only an integer ID.
+
+
+== FEATURES:
+
+* Allows creation of Classes with enum like behaviour.
+* Allows any number of members and methods in the enum classes.
+* Allows an integer id to be used in your database columns to link to the enum members (user.role_id)
+* Enables higher abstraction interaction with +AR+ attributes:
+  * <code>user.role = Role.admin</code>
+  * <code>if user.role.can_edit?</code>
+* Saves in your +AR+ tables, only an integer id pointing to the enumeration member.
+
+== SYNOPSIS:
+
+When in an Active Record class, you have an attribute like role, state or country you have
+several options.
+
+* You can create a roles, states or countries table, and dump there all possible values.
+* You can use a string to identify, for instance, the role.
+* You can use an id to identify the role.
+
+If you are not confortable with any of this options, maybe +enum_field+ is an answer for you.
+
+== BASIC USAGE:
+
+  class Role
+    define_enum do |builder|
+      builder.member :admin
+      builder.member :manager
+      builder.member :employee
+    end
+  end
+
+  class User < ActiveRecord::Base
+    # in the database table there is a role_id integer column
+    enumerated_attribute :role
+  end
+
+
+  link_to_if(current_user.role == Role.admin, edit_foo_path(@foo))
+
+  user.role = Role.manager
+  user.role_id == Role.manager.id  #will be true
+
+  User.first.role.id == User.first.role_id  #will be true
+
+Your enum classes can have all the methods you need:
+
+  class PhoneType
+    def initialize(name)
+      @name = name
+    end
+    attr_reader :name
+
+    define_enum do |b|
+      b.member :home,       :object => PhoneType.new('home')
+      b.member :commercial, :object => PhoneType.new('commercial')
+      b.member :mobile,     :object => PhoneType.new('mobile')
+    end
+  end
+
+  user.phone.type.name
+
+You have some +AR+ like methods in enum classes
+
+  PhoneType.all == [PhoneType.home, PhoneType.commercial, PhoneType.mobile]  # ordered all
+  PhoneType.first == PhoneType.home
+  PhoneType.last == PhoneType.mobile
+
+  PhoneType.find_by_id(PhoneType.home.id) == PhoneType.home
+  PhoneType.find_by_id(123456) == nil
+  PhoneType.find(2) == PhoneType.commercial
+  PhoneType.find(123456)  # will raise
+
+The library also mimics has_many :through behavior, for cases such as:
+
+  class Role
+    define_enum do |builder|
+      builder.member :admin
+      builder.member :manager
+      builder.member :employee
+    end
+  end
+
+  class User
+    has_many_enumerated_attributes :roles, :through  => UserRole
+  end
+
+  class UserRole < ActiveRecord::Base
+    belongs_to :user
+    enumerated_attribute :role
+  end
+
+  user = User.create
+  user.role = [Role.manager, Role.admin]
+  user.roles.include?(Role.admin)         #will be true
+  user.roles.include?(Role.manager)       #will be true
+  user.roles.include?(Role.employee)      #will be false
+  user.role_ids.include?(Role.manager.id) #will be true
+  user.role_ids = [Role.employee.id]
+  user.roles.include?(Role.employee)      #will be true
+  user.roles.include?(Role.admin)         #will be false
+
+
+
+== REQUIREMENTS:
+
+* activerecord
+
+
+== INSTALL:
+
+  rails plugin install git://github.com/galetahub/enum_field.git
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009 Sebastián Bernardo Galkin

data/Rakefile

@@ -0,0 +1,44 @@
+# encoding: utf-8
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require File.join(File.dirname(__FILE__), 'lib', 'enum_field', 'version')
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the enum_field plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the enum_field plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'EnumField'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = "galetahub-enum_field"
+    s.version = EnumField::VERSION
+    s.summary = "Enumerated attributes"
+    s.description = "Enables Active Record attributes to point to enum like objects, by saving in your database only an integer ID"
+    s.email = "galeta.igor@gmail.com"
+    s.homepage = "https://github.com/galetahub/enum_field"
+    s.authors = ["Igor Galeta", "Pavlo Galeta"]
+    s.files =  FileList["[A-Z]*", "lib/**/*"]
+    s.extra_rdoc_files = FileList["[A-Z]*"] - %w(Rakefile)
+  end
+  
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: gem install jeweler"
+end

data/lib/enum_field.rb

@@ -0,0 +1,22 @@
+# encoding: utf-8
+module EnumField
+  autoload :DefineEnum, 'enum_field/define_enum'
+  autoload :Builder, 'enum_field/builder'
+  autoload :EnumeratedAttribute, 'enum_field/enumerated_attribute'
+  autoload :Version, 'enum_field/version'
+  
+  class BadId < StandardError
+    def initialize(repeated_id)
+      @repeated_id = repeated_id
+    end
+    attr_reader :repeated_id
+  end
+
+  class RepeatedId < StandardError; end
+  class InvalidId < StandardError; end
+  class InvalidOptions < StandardError; end
+  class ObjectNotFound < StandardError; end
+end
+
+Module.send(:include, EnumField::DefineEnum)
+require 'enum_field/railtie'

data/lib/enum_field/builder.rb

@@ -0,0 +1,78 @@
+# encoding: utf-8
+module EnumField
+  class Builder
+    def initialize(target)
+      @target = target
+      @next_id = 0
+      @id2obj = {}
+      @name2obj = {}
+      @sorted = []
+    end
+
+    def member(name, options = {})
+      obj, candidate_id = process_options(options)
+      assign_id(obj, candidate_id)
+      define_in_meta(name) { obj }
+      save(name, obj)
+      obj.freeze
+    end
+
+    def all
+      @sorted.dup
+    end
+
+    def names
+      @name2obj.keys
+    end
+
+    def find(id)
+      find_by_id(id) or raise EnumField::ObjectNotFound
+    end
+
+    def find_by_id(id)
+      @id2obj[id.to_i]
+    end
+
+    def first; @sorted.first; end
+    def last; @sorted.last; end
+
+    private
+
+    def define_in_meta(name, &block)
+      metaclass = class << @target; self; end
+      metaclass.send(:define_method, name, &block)
+    end
+
+    def assign_id(obj, candidate_id)
+      id = new_id(candidate_id)
+      obj.class.send(:attr_reader, :id)
+      obj.instance_variable_set(:@id, id)
+    end
+
+    def new_id(candidate)
+      validate_candidate_id(candidate)
+      candidate || find_next_id
+    end
+
+    def validate_candidate_id(id)
+      raise EnumField::InvalidId.new(id) unless id.nil? || id.is_a?(Integer) && id > 0
+      raise EnumField::RepeatedId.new(id) if @id2obj.has_key?(id)
+    end
+
+    def find_next_id
+      @next_id += 1 while @id2obj.has_key?(@next_id) || @next_id <= 0
+      @next_id
+    end
+
+    def process_options(options)
+      raise EnumField::InvalidOptions unless options.reject {|k,v| k == :object || k == :id}.empty?
+      [options[:object] || @target.new, options[:id]]
+    end
+
+    def save(name, obj)
+      @id2obj[obj.id] = obj
+      @sorted << obj
+      @name2obj[name] = obj
+    end
+  end
+end

data/lib/enum_field/define_enum.rb

@@ -0,0 +1,17 @@
+# encoding: utf-8
+module EnumField
+  module DefineEnum
+    def define_enum(&block)
+      @enum_builder ||= EnumField::Builder.new(self)
+      yield @enum_builder
+
+      [:all, :names, :find_by_id, :find, :first, :last].each do |method|
+        instance_eval <<-END
+          def #{method}(*args, &block)
+            @enum_builder.send(:#{method}, *args, &block)
+          end
+        END
+      end
+    end
+  end
+end

data/lib/enum_field/enumerated_attribute.rb

@@ -0,0 +1,88 @@
+# encoding: utf-8
+module EnumField
+  # Easies the inclusion of enumerations as ActiveRecord columns.
+  # If you have a User AR, with a role_id column, you could do:
+  # <tt>
+  # class User
+  #   enumerated_attribute :role
+  # end
+  # </tt>
+  #
+  # This assumes a Role class, and will define role and role= methods in User class.
+  # These added methods expect an object of class Role, and Role should provide a find class method.
+  # You could get this by using Enumerated mixin
+  #
+  # Similar to has_many :through in AR, it creates reader and writter methods to get enumerated atributes going through an
+  # intermediate model.
+  # For instance:
+  # <tt>
+  # class User
+  #   has_many_enumerated_attributes :roles, :through  => UserRole
+  # end
+  #
+  # class UserRole < ActiveRecord::Base
+  #   belongs_to :user
+  #   enumerated_attribute :role
+  # end
+  # </tt>
+  # This assumes a Role class, the UserRole AR class is there just to persist the one-to-many relationship.
+  # This will define roles, roles=, role_ids and role_ids= methods in User class
+
+  module EnumeratedAttribute
+    # Define an enumerated field of the AR class
+    # * +name_attribute+: the name of the field that will be added, for instance +role+
+    # * +options+: Valid options are:
+    #    * +id_attribute+: the name of the AR column where the enumerated id will be save. Defaults to
+    #      +name_attribute+ with an +_id+ suffix.
+    #    * +class+: the class that will be instantiated when +name_attribute+ method is called. Defaults to
+    #      +name_attribute+ in camelcase form.
+    def enumerated_attribute(name_attribute, options  = {})
+      id_attribute = options[:id_attribute] || (name_attribute.to_s + '_id').to_sym
+      klass = options[:class] || name_attribute.to_s.camelcase.constantize
+      define_method(name_attribute) do
+        (raw = read_attribute(id_attribute)) && klass.find_by_id(raw)
+      end
+
+      define_method(name_attribute.to_s + '=') do |value|
+        write_attribute(id_attribute, value ? value.id : nil)
+      end
+    end
+
+    # alias of enumerated_attribute
+    alias belongs_to_enumerated_attribute enumerated_attribute
+
+    # Defines a one-to-many association between an AR class and the enumerated
+    # * +association+: the name of the one-to-many association, for instance +roles+
+    # * +options+: Valid options are:
+    #    * +through+ : the name of the AR class needed to persist the one-to-many association.
+    #       Defaults to AR class in camelcase form concatenated with the enumerated class in camelcase form.
+    #    * +class+:    the enumerated class, it will be instantiated +n+ times when +association+ method is called.
+    #       Defaults to +association+ in singular camelcase form.
+    def has_many_enumerated_attributes(association, options = {})
+      enum_attr = association.to_s.singularize
+      klass     = options[:class]   || enum_attr.camelcase.constantize
+      through   = options[:through] || (self.name + klass.name)
+      self_attribute = self.name.demodulize.underscore
+      association_ids = association.to_s.singularize + '_ids'
+      has_many_aux = through.demodulize.underscore.pluralize
+
+      has_many has_many_aux, {:class_name => through, :dependent => :destroy}
+
+      define_method(association) do
+        self.send(has_many_aux).map(&enum_attr.to_sym)
+      end
+
+      define_method(association.to_s + '=') do |values|
+        self.send(has_many_aux + '=', values.map{|g| through.constantize.new(self_attribute => self, enum_attr => g)})
+      end
+
+      define_method(association_ids) do
+         self.send(association).map(&:id)
+      end
+
+      define_method(association_ids + '=') do |values|
+        self.send(has_many_aux + '=', values.map{|g| g.to_i unless g.blank?}.compact.map{|g_id| through.constantize.new(self_attribute => self, enum_attr + '_id' => g_id) })
+      end
+    end
+  end
+end

data/lib/enum_field/railtie.rb

@@ -0,0 +1,13 @@
+# encoding: utf-8
+require 'rails'
+require 'enum_field'
+
+module EnumField
+  class Railtie < ::Rails::Railtie
+    config.before_initialize do
+      ActiveSupport.on_load :active_record do
+        ActiveRecord::Base.send(:extend, EnumField::EnumeratedAttribute)
+      end
+    end
+  end
+end

data/lib/enum_field/version.rb

@@ -0,0 +1,3 @@
+module EnumField
+  VERSION = "0.1.4".freeze
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification 
+name: galetahub-enum_field
+version: !ruby/object:Gem::Version 
+  hash: 19
+  prerelease: 
+  segments: 
+  - 0
+  - 1
+  - 4
+  version: 0.1.4
+platform: ruby
+authors: 
+- Igor Galeta
+- Pavlo Galeta
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-06-16 00:00:00 +03:00
+default_executable: 
+dependencies: []
+
+description: Enables Active Record attributes to point to enum like objects, by saving in your database only an integer ID
+email: galeta.igor@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- README.rdoc
+- Rakefile
+- lib/enum_field.rb
+- lib/enum_field/builder.rb
+- lib/enum_field/define_enum.rb
+- lib/enum_field/enumerated_attribute.rb
+- lib/enum_field/railtie.rb
+- lib/enum_field/version.rb
+has_rdoc: true
+homepage: https://github.com/galetahub/enum_field
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: Enumerated attributes
+test_files: []
+