enum_field 0.1.2

data/History.txt

@@ -0,0 +1,10 @@
+== 0.0.1 2009-06-10
+
+* Initial release
+
+
+== 0.1.0 2009-06-15
+
+* Fixed bug in finder methods definition
+* Improved documentation
+

data/Manifest.txt

@@ -0,0 +1,18 @@
+History.txt
+Manifest.txt
+PostInstall.txt
+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/exceptions.rb
+script/console
+script/destroy
+script/generate
+spec/define_enum_spec.rb
+spec/enumerated_attribute_spec.rb
+spec/spec.opts
+spec/spec_helper.rb
+tasks/rspec.rake

data/PostInstall.txt

@@ -0,0 +1,3 @@
+
+For more information on enum_field, see http://enum_field.rubyforge.org
+

data/README.rdoc

@@ -0,0 +1,117 @@
+= 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
+
+== REQUIREMENTS:
+
+* activerecord
+* hoe
+* rubyforge
+
+
+== INSTALL:
+
+sudo gem install enum_field
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009 Sebastián Bernardo Galkin
+
+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/Rakefile

@@ -0,0 +1,28 @@
+require 'rubygems' unless ENV['NO_RUBYGEMS']
+%w[rake rake/clean fileutils newgem rubigen].each { |f| require f }
+require File.dirname(__FILE__) + '/lib/enum_field'
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.new('enum_field', EnumField::VERSION) do |p|
+  p.developer('Sebastián Bernardo Galkin', 'sgalkin@grantaire.com.ar')
+  p.changes              = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  p.post_install_message = 'PostInstall.txt' # TODO remove if post-install message not required
+  p.rubyforge_name       = p.name # TODO this is default value
+  p.extra_deps         = [
+     ['activerecord'],
+   ]
+  p.extra_dev_deps = [
+    ['newgem', ">= #{::Newgem::VERSION}"]
+  ]
+
+  p.clean_globs |= %w[**/.DS_Store tmp *.log]
+  path = (p.rubyforge_name == p.name) ? p.rubyforge_name : "\#{p.rubyforge_name}/\#{p.name}"
+  p.remote_rdoc_dir = File.join(path.gsub(/^#{p.rubyforge_name}\/?/,''), 'rdoc')
+  p.rsync_args = '-av --delete --ignore-errors'
+end
+
+require 'newgem/tasks' # load /tasks/*.rake
+Dir['tasks/**/*.rake'].each { |t| load t }
+
+task :default => [:spec]

data/lib/enum_field/builder.rb

@@ -0,0 +1,79 @@
+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)
+      obj.freeze
+      assign_id(obj, candidate_id)
+      define_in_meta(name) { obj }
+      save(name, obj)
+    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,16 @@
+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,35 @@
+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
+#
+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
+end
+
+end

data/lib/enum_field/exceptions.rb

@@ -0,0 +1,19 @@
+module EnumField
+  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
+

data/lib/enum_field.rb

@@ -0,0 +1,17 @@
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'rubygems'
+require 'enum_field/define_enum'
+require 'enum_field/exceptions'
+require 'enum_field/builder'
+require 'enum_field/enumerated_attribute'
+require 'activerecord'
+
+Module.send(:include, EnumField::DefineEnum)
+ActiveRecord::Base.send(:extend, EnumField::EnumeratedAttribute)
+
+module EnumField
+  VERSION = '0.1.1'
+
+end

data/script/console

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# File: script/console
+irb = RUBY_PLATFORM =~ /(:?mswin|mingw)/ ? 'irb.bat' : 'irb'
+
+libs =  " -r irb/completion"
+# Perhaps use a console_lib to store any extra methods I may want available in the cosole
+# libs << " -r #{File.dirname(__FILE__) + '/../lib/console_lib/console_logger.rb'}"
+libs <<  " -r #{File.dirname(__FILE__) + '/../lib/enum_field.rb'}"
+puts "Loading enum_field gem"
+exec "#{irb} #{libs} --simple-prompt"

data/script/destroy

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+APP_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
+begin
+  require 'rubigen'
+rescue LoadError
+  require 'rubygems'
+  require 'rubigen'
+end
+require 'rubigen/scripts/destroy'
+
+ARGV.shift if ['--help', '-h'].include?(ARGV[0])
+RubiGen::Base.use_component_sources! [:rubygems, :newgem, :newgem_theme, :test_unit]
+RubiGen::Scripts::Destroy.new.run(ARGV)

data/script/generate

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+APP_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
+begin
+  require 'rubigen'
+rescue LoadError
+  require 'rubygems'
+  require 'rubigen'
+end
+require 'rubigen/scripts/generate'
+
+ARGV.shift if ['--help', '-h'].include?(ARGV[0])
+RubiGen::Base.use_component_sources! [:rubygems, :newgem, :newgem_theme, :test_unit]
+RubiGen::Scripts::Generate.new.run(ARGV)

data/spec/define_enum_spec.rb

@@ -0,0 +1,209 @@
+require File.dirname(__FILE__) + '/spec_helper.rb'
+
+describe EnumField::DefineEnum do
+  class Colors
+    define_enum do |builder|
+      builder.member :red
+      builder.member :green
+    end
+  end
+
+  context "defining enums" do
+    it "should add method :define_enum to class" do
+      class TestClass
+      end
+
+      TestClass.should respond_to(:define_enum)
+    end
+
+    it "should yield in define_enum" do
+      class Checkpoint
+        @list = []
+        class << self
+          attr_accessor :list
+        end
+      end
+
+      class Test
+        define_enum {|builder| Checkpoint.list << :here}
+      end
+
+      Checkpoint.list.should == [:here]
+    end
+
+    it "should yield a builder in define_enum" do
+      lambda {
+        class Test
+          define_enum do |builder|
+            raise unless builder.respond_to?(:member)
+          end
+        end
+      }.should_not raise_error
+    end
+
+    it "should reject invalid options" do
+      lambda {
+        class Test
+          define_enum do |builder|
+            builder.member :foo, :bar => 1
+          end
+        end
+      }.should raise_error(EnumField::InvalidOptions)
+    end
+
+    class NotEnum
+    end
+
+    it "should not define enumerated methods in base Class" do
+      NotEnum.should_not respond_to(:red)
+      Class.should_not respond_to(:red)
+    end
+
+    it "should generate instances of class for the enums" do
+      Colors.red.should be_instance_of(Colors)
+      Colors.green.should be_instance_of(Colors)
+    end
+
+    it "should allow creation of simple constants" do
+      Colors.red.should_not be_nil
+      Colors.green.should_not be_nil
+    end
+
+    it "should define incremental ids for created constants" do
+      Colors.red.id.should == 1
+      Colors.green.id.should == 2
+    end
+
+    it "should allow custom objects" do
+      class Colors
+        define_enum do |b|
+          b.member :blue, :object => 'blue'
+        end
+      end
+      Colors.red.should be_instance_of(Colors)
+      Colors.blue.should be_instance_of(String)
+    end
+
+    it "should allow custom ids" do
+      class Colors
+        define_enum do |b|
+          b.member :yellow, :id => 98765
+        end
+      end
+      Colors.yellow.id.should == 98765
+    end
+
+    it "should not accept repeated ids during deffinition" do
+      lambda {
+        class Colors
+          define_enum do |b|
+            b.member :brown, :id => 2
+          end
+        end
+      }.should raise_error(EnumField::RepeatedId)
+    end
+
+    it "should not accept invalid ids" do
+      lambda {
+        class Colors
+          define_enum do |b|
+            b.member :cyan, :id => :hola
+          end
+        end
+      }.should raise_error(EnumField::InvalidId)
+    end
+
+    it "should not generate repeated ids" do
+      class Sizes
+        define_enum do |b|
+          b.member :small, :id => 1
+          b.member :medium
+        end
+      end
+      Sizes.small.id.should == 1
+      Sizes.medium.id.should == 2
+    end
+
+    it "should accept both object and id options" do
+      class Sizes
+        define_enum do |b|
+          b.member :large, :id => 10
+        end
+      end
+      Sizes.large.id.should == 10
+    end
+  end
+
+  context "providing interface" do
+
+    class Positions
+      define_enum do |b|
+        b.member :top
+        b.member :right
+        b.member :bottom
+        b.member :left, :id => 100
+      end
+    end
+
+    it "should define all method" do
+      Positions.should respond_to(:all)
+    end
+
+    it "should return ordered members in all" do
+      Positions.all.should == [Positions.top, Positions.right, Positions.bottom, Positions.left]
+    end
+
+    it "should define names method" do
+      Positions.should respond_to(:names)
+    end
+
+    it "should return all names method" do
+      Positions.names.should include(:top, :right, :bottom, :left)
+      Positions.names.size.should == 4
+    end
+
+    it "should provide find_by_id and find working for autogenerated ids" do
+      Positions.find_by_id(1).should == Positions.top
+      Positions.find(1).should == Positions.top
+    end
+
+    it "should provide find_by_id and find working for custom ids" do
+      Positions.find_by_id(100).should == Positions.left
+    end
+
+    it 'should return nil in find_by_id for nonnexistent ids' do
+      Positions.find_by_id(200).should be_nil
+    end
+
+    it 'should return throw in find for nonnexistent ids' do
+      lambda { Positions.find(200)}.should raise_error(EnumField::ObjectNotFound)
+    end
+
+    it "should return first defined element in .first" do
+      Positions.first.should == Positions.first
+    end
+
+    it "should return last defined element in .first" do
+      Positions.last.should == Positions.left
+    end
+  end
+
+  context "with rich classes" do
+    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
+
+    it "should allow behaviour to be called" do
+      PhoneType.home.name.should == 'home'
+    end
+  end
+end

data/spec/enumerated_attribute_spec.rb

@@ -0,0 +1,64 @@
+require File.dirname(__FILE__) + '/spec_helper.rb'
+
+describe EnumField::EnumeratedAttribute do
+  class Role
+    define_enum do |b|
+      b.member :admin
+      b.member :supervisor
+      b.member :manager
+    end
+  end
+
+  class User < ActiveRecord::Base
+    enumerated_attribute :role
+  end
+
+  
+  before(:each) {
+    User.stub!(:columns).and_return([ActiveRecord::ConnectionAdapters::Column.new(:role_id, nil)])
+  }
+
+  it "should add enumerated_attribute class method to ActiveRecord::Base" do
+    ActiveRecord::Base.should respond_to(:enumerated_attribute)
+  end
+
+  context "with AR objects" do
+
+    before(:each) {@user = User.new}
+
+    it "should define reader on the field" do
+      @user.should respond_to(:role)
+    end
+
+    it "should define writter on the field" do
+      @user.should respond_to(:'role=')
+    end
+
+    it "should assign field id when field is assigned" do
+      @user.role = Role.admin
+      @user.role_id.should == Role.admin.id
+    end
+
+    it "should return field after field_id is assigned" do
+      @user.role_id = Role.admin.id
+      @user.role.should == Role.admin
+    end
+
+    it "should return nil field for nil field id" do
+      @user.role.should be_nil
+    end
+
+    it "should return nil field id for nilled field" do
+      @user.role_id = Role.admin.id
+      @user.role = nil
+      @user.role_id.should be_nil
+    end
+
+    it "should return nil field for nilled field id" do
+      @user.role = Role.admin
+      @user.role_id = nil
+      @user.role.should be_nil
+    end
+  end
+end
+

data/spec/spec.opts

@@ -0,0 +1,5 @@
+--colour
+--format specdoc
+--backtrace
+--reverse
+

data/spec/spec_helper.rb

@@ -0,0 +1,10 @@
+begin
+  require 'spec'
+rescue LoadError
+  require 'rubygems' unless ENV['NO_RUBYGEMS']
+  gem 'rspec'
+  require 'spec'
+end
+
+$:.unshift(File.dirname(__FILE__) + '/../lib')
+require 'enum_field'

data/tasks/rspec.rake

@@ -0,0 +1,21 @@
+begin
+  require 'spec'
+rescue LoadError
+  require 'rubygems' unless ENV['NO_RUBYGEMS']
+  require 'spec'
+end
+begin
+  require 'spec/rake/spectask'
+rescue LoadError
+  puts <<-EOS
+To use rspec for testing you must install rspec gem:
+    gem install rspec
+EOS
+  exit(0)
+end
+
+desc "Run the specs under spec/models"
+Spec::Rake::SpecTask.new do |t|
+  t.spec_opts = ['--options', "spec/spec.opts"]
+  t.spec_files = FileList['spec/**/*_spec.rb']
+end

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification 
+name: enum_field
+version: !ruby/object:Gem::Version 
+  version: 0.1.2
+platform: ruby
+authors: 
+- "Sebasti\xC3\xA1n Bernardo Galkin"
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-06-23 00:00:00 -03:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: newgem
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.4.1
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.8.0
+    version: 
+description: Enables Active Record attributes to point to enum like objects, by saving in your database only an integer ID.
+email: 
+- sgalkin@grantaire.com.ar
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- Manifest.txt
+- PostInstall.txt
+- README.rdoc
+files: 
+- History.txt
+- Manifest.txt
+- PostInstall.txt
+- 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/exceptions.rb
+- script/console
+- script/destroy
+- script/generate
+- spec/define_enum_spec.rb
+- spec/enumerated_attribute_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+- tasks/rspec.rake
+has_rdoc: true
+homepage: http://github.com/paraseba/enum_field
+licenses: []
+
+post_install_message: PostInstall.txt
+rdoc_options: 
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: enum_field
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 2
+summary: Enables Active Record attributes to point to enum like objects, by saving in your database only an integer ID.
+test_files: []
+