mcommons-values_for 0.0.7

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Mal McKay and Justin S. Leitgeb
+
+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.rdoc

@@ -0,0 +1,105 @@
+= values_for
+
+values_for is an ActiveRecord extension enabling the easy use of enumerated types for your models.
+
+== Description
+
+values_for makes your ActiveRecord-backed class work with an enumerable type.  Instead of existing 
+ActiveRecord plugins such as enum_fu, which store the enumerable attribute as an integer, values_for 
+stores the content of the enumerable attribute in a varchar column of the database.
+
+values_for will also optionally create named scopes, predicate methods, and constants defining the 
+possible values for enumerable types on your model.  By default, however, it avoids polluting your
+model with things you may not need unless these features are specifically requested.
+
+== Installation
+
+values_for is available as a gem available on GitHub.  Install with:
+
+  sudo gem install mcommons-values_for
+
+You'll probable want a line like the following in your environment.rb:
+
+  config.gem 'mcommons-values_for', :lib => 'values_for'
+
+== Basic Usage
+
+The following example sets up an enumerable attribute on an ActiveRecord model.  This assumes that a previous
+migration has created a column of type VARCHAR on the table "taco".
+
+  class Taco < ActiveRecord::Base
+    values_for :state, :has => [ :new, :composed, :served, :eaten ]
+  end
+
+For all values_for-enabled models, valid states are able to be read for an attribute by calling the plural of
+the attribute name:
+
+  >> Taco.states 
+  => [ :new, :composed, :served, :eaten ]
+
+== Options
+
+values_for will optionally create named scopes, predicate methods, and constants defining values for
+enumerable types on your model.  These may be specified on a case-by-case basis by using the :adds
+option.  As an example, the following would create an enumerable attribute called "flavor" with the 
+possible values "sour" and "sweet", while creating named scopes, predicate methods, and constants on 
+your class:
+
+  values_for :flavor, :has => [ :sour, :sweet ], :adds => [ :named_scopes, :predicate_methods, :constants ]
+
+The different additive options are described below.
+
+=== Named Scopes
+
+The named_scopes option adds a named scope, with either the default or custom prefix, to your model.
+For example, the following model definition would create a named_scope Taco.flavor_sour on your class:
+
+  class Taco < ActiveRecord::Base
+    values_for :flavor, :has => [ :sour, :sweet ], :adds => :named_scopes
+  end
+
+Afterwards, you may use the named scopes as follows.  Remember to add the prefix!
+
+  Taco.flavor_sour
+  Taco.flavor_sweet
+
+The prefix may be overridden or omitted by using the :prefix option.
+
+=== Predicate methods
+
+values_for also creates predicate methods on instances of your class so that you can ask if they have any
+of the given enumerable states.  For example, if a Taco class has an enumerable type :taste with values
+:good and :bad, taco.good? would return a boolean value indicating whether or not the taste is good.
+
+This option is only enabled when the additive option predicate_methods is specified.
+
+=== Constants
+
+values_for optionally defines constants corresponding to each of the valid enumerable types on your model.  
+For example, if you have an enumerable column called "states" with valid states :starting and :finished, 
+values_for would define constants on your model Model::STATE_STARTING and Model::STATE_FINISHED with the 
+contents of these constants :starting and :finished respectively.  This is only enabled when the additive
+option :constants is specified.
+  
+== Configuration
+
+values_for by default adds the attribute being modified as a prefix to constant declarations, named scopes,
+and predicate methods.  If you wish to modify this prefix, pass the :prefix option to values_for.  You may 
+also omit the addition of the prefix by passing :prefix => nil to values_for. Example:
+
+  class Taco < ActiveRecord::Base
+    values_for :state, :has => [ :new, :composed, :served, :eaten ], :prefix => 'wacky'
+  end
+  
+This makes Taco respond to named scopes like Taco.wacky_composed instead of the default, which
+would have prefixed the named_scopes with the name of the attribute.
+
+== Notes
+
+This plugin doesn't implement default values for a model.  If this behavior is desired, you may be interested
+in the default_value_for plugin (available http://github.com/FooBarWidget/default_value_for/tree/master), 
+which has been successfully tested with values_for.
+
+== Authors
+
+Mal McKay, Justin Leitgeb and Ben Stein

data/Rakefile

@@ -0,0 +1,21 @@
+require 'rake'
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
+
+desc 'Test the plugin.'
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.libs << 'lib'
+  t.verbose = true
+end
+
+desc "Run all the tests"
+task :default => :spec
+
+desc 'Generate documentation for the values_for plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Enum For'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/lib/values_for.rb

@@ -0,0 +1,76 @@
+module EnumFor
+
+  def self.included(base)
+    base.extend(SingletonMethods)
+  end
+
+  module SingletonMethods
+
+    # Creates an enumerable attribute on an ActiveRecord model.  Usage is as 
+    # follows:
+    #
+    #   values_for :state, :has => [ :new, :composed, :served, :eaten ]
+    #
+    # Any additional options will be passed directly to the ActiveRecord method 
+    # :validates_inclusion_of, which is used to validate the assigned values to 
+    # this attribute.  Requires a column of type VARCHAR with the name of the 
+    # first argument to +values_for+.
+    def values_for(*args)
+      opts        = args.extract_options!
+      attribute   = args.first
+      
+      attribute_s = attribute.to_s
+
+      additives         = Array.wrap(opts[:add])
+      plural_attribute  = attribute_s.pluralize
+      
+      prefix = opts.has_key?(:prefix) ? opts[:prefix] : attribute_s
+
+      # Valid values are most likely Symbols anyway, but coerce them to be safe.
+      valid_symbols = opts[:has].map{|v| v.to_sym }
+
+      valid_symbols.each do |val_sym|
+        val_s = val_sym.to_s
+        
+        prefixed_val = [ prefix, val_s ].compact.join('_')
+        
+        # Create +optional+ constants
+        const_set(prefixed_val.upcase, val_sym) if additives.include?(:constants)
+        
+        # Create +optional+ named scopes
+        named_scope prefixed_val, :conditions => { attribute => val_s } if additives.include?(:named_scopes)
+
+        # Create +optional+ predicate methods, but don't overwrite existing methods
+        if additives.include?(:predicate_methods) && !self.instance_methods.include?(prefixed_val)
+          define_method(prefixed_val + '?') do    # def foo?
+            read_attribute(attribute) == val_s    #   read_attribute(:foo) == 'foo'  
+          end                                     # end
+        end
+        
+      end
+      
+      # Accepts assignment both from String and Symbol form of valid values.
+      validates_inclusion_of attribute, opts.except(:has, :prefix, :add).
+        merge(:in => valid_symbols | valid_symbols.map{|s| s.to_s } )
+      
+      # Custom reader method presents attribute value in Symbol form.
+      define_method(attribute_s) do                           # def foo
+        self[attribute].to_sym unless self[attribute].nil?    #   self[:foo].to_sym unless self[:foo].nil?
+      end                                                     # end
+      
+      # Custom setter method casting all attribute input to String, allows 
+      # assignment from Symbol form.
+      define_method(attribute_s + '=') do |other|  # def foo=(other)
+        self[attribute] = other.to_s               #    self[foo] = other 
+      end                                          # end
+      
+      # Make collection of all valid attribute Symbols available to user
+      # from plural name of attribute as class method.
+      cattr_reader plural_attribute.to_sym
+      class_variable_set(:"@@#{plural_attribute}", opts[:has])    
+    end
+  end
+  
+end
+
+ActiveRecord::Base.send(:include, EnumFor)

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+require 'rubygems'
+require 'mocha'
+require 'spec'
+
+require File.join(File.dirname(__FILE__), %w[.. lib values_for])
+
+Spec::Runner.configure do |config|
+  config.mock_with(:mocha)
+end

data/spec/values_for_spec.rb

@@ -0,0 +1,193 @@
+require 'rubygems'
+require 'activerecord'
+
+require File.join(File.dirname(__FILE__), 'spec_helper')
+
+ActiveRecord::Base.establish_connection(
+  :adapter => 'sqlite3',
+  :dbfile => ":memory:"
+)
+
+ActiveRecord::Migration.verbose = false
+
+ActiveRecord::Base.silence do
+  ActiveRecord::Schema.define do
+    create_table :tacos do |table|
+      table.string :state
+    end
+  end
+end
+
+
+describe EnumFor do
+  before do
+    @taco = Taco.new(:state => 'new')
+  end
+  
+  class Taco < ActiveRecord::Base
+    values_for :state, :has => [ :new, :composed, :served, :eaten ]
+  end
+
+  describe "model validation" do
+    it "should make a valid model when given a valid state" do
+      @taco.should be_valid
+    end
+
+    it "should retrieve a symbol when the model is created with attribute set to string" do
+      @taco.state.should == :new
+    end
+
+    it "should be valid when an attribute is set to a valid symbol" do
+      Taco.new(:state => :composed).should be_valid
+    end
+
+    it "should not be valid when an attribute is set to an invalid symbol" do
+      Taco.new(:state => :bogus).should_not be_valid
+    end
+
+    it "should not create a valid model when given an invalid state" do
+      Taco.create(:state => 'barfed').should_not be_valid
+    end
+  end
+  
+  describe "storage and retrieval of possible states in class" do
+    it "should return all possible states when plural of attribute is called as class method" do
+      Taco.states.should == [ :new, :composed, :served, :eaten ]
+    end
+  end
+  
+  describe "definition of constants for each attribute value" do
+    class WithoutConstants < ActiveRecord::Base
+      values_for :state, :has => [ :new, :composed, :served, :eaten ]
+    end
+    
+    class WithConstants < ActiveRecord::Base
+      values_for :state, :has => [ :new, :composed, :served, :eaten ], :add => :constants
+    end
+    
+    it "should be disabled by default" do
+      WithoutConstants.constants.should_not include('WithoutConstants::STATE_NEW')
+    end
+    
+    it "should be enabled when added" do
+      WithConstants.constants.should_not include('WithoutConstants::STATE_NEW')
+    end
+
+    it "should define constants for each type" do
+      WithConstants::STATE_EATEN.should == :eaten
+    end
+  end
+  
+  describe "definition of predicate methods" do
+    class WithPredicateMethods < ActiveRecord::Base
+      set_table_name "tacos"
+      values_for :state, :has => [ :new, :composed, :served, :eaten ], :add => :predicate_methods
+    end
+    
+    it "should not define predicate methods for each valid state by default" do
+      @taco.should_not respond_to(:state_eaten?)
+    end
+    
+    it "should define predicate methods for each state when specified" do
+      WithPredicateMethods.new.should respond_to(:state_eaten?)
+    end
+  end
+
+  describe "with prefix option" do
+    class Food < ActiveRecord::Base
+      set_table_name "tacos"
+      values_for :state, :has => [:stuff, :morestuff], :prefix => nil, :add => :predicate_methods
+    end
+
+    it "should not prefix predicate methods if asked not to" do
+      Food.new(:state => :stuff).should respond_to(:stuff?)
+    end
+  end
+  
+  describe "casting of values set and retrieved to correct type" do
+    it "should allow strings for attribute values even when initialized with symbols" do
+      Food.new(:state => 'stuff').should be_valid
+    end
+    
+    it "should retrieve a symbol when a string is set and the attribute value is a symbol" do
+      f = Food.new(:state => 'stuff')
+      f.state.should == :stuff
+    end
+  end
+  
+  describe "with an Array of additives" do
+    class BeefJerkey < ActiveRecord::Base
+      set_table_name "tacos"
+      values_for :flavor, :has => [:sour, :spicy], :add => [:named_scopes, :predicate_methods]
+    end
+    
+    it "should construct named scopes" do
+      BeefJerkey.should respond_to(:flavor_sour)
+    end
+    
+    it "should construct predicate methods" do
+      BeefJerkey.new.should respond_to(:flavor_sour?)
+    end
+  end
+  
+  describe "behavior with existing methods of same name" do
+    class Balloon < ActiveRecord::Base
+      set_table_name "tacos"
+      values_for :state, :has => [:stuff, :morestuff], :prefix => nil
+
+      def stuff?
+        "not a boolean"
+      end
+    end
+
+    it "should not define a predicate method when a one already exists" do
+      Balloon.new(:state => :stuff).stuff?.should == "not a boolean"
+    end
+  end
+
+  describe "with validation options" do   
+    class Food2 < ActiveRecord::Base
+      set_table_name "tacos"
+      values_for :state, :has => ['stuff', 'morestuff'], :prefix => nil, :allow_nil => true, :message => "is great!"
+    end
+
+    it "should allow validation message to be set" do
+      Food2.create(:state => :junk).errors.full_messages.should include('State is great!')
+    end
+    
+    it "should respect :allow_nil setting" do
+      Food2.new.should be_valid
+    end
+  end
+  
+  describe "named scope creation" do
+    describe "when not added" do
+      it "should not create named scopes" do
+        Taco.should_not respond_to(:state_composed)
+      end
+    end
+    
+    describe "when added" do
+      class Tequila < ActiveRecord::Base
+        set_table_name "tacos"
+        values_for :state, :has => [ :wormy, :delicious ], :add => :named_scopes
+      end
+
+      before do
+        Tequila.delete_all
+      
+        2.times { Tequila.create(:state => 'wormy') }
+        3.times { Tequila.create(:state => 'delicious') }
+      end
+    
+      it "should have two wormy tequilas" do
+        Tequila.state_wormy.size.should == 2
+      end
+    
+      it "should have two delicious tequilas" do
+        Tequila.state_delicious.size.should == 3
+      end
+    end
+  end
+  
+end

data/values_for.gemspec

@@ -0,0 +1,38 @@
+Gem::Specification.new do |s|
+  s.name = %q{values_for}
+  s.version = "0.0.7"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Mal McKay and Justin Leitgeb"]
+  s.date = %q{2009-06-17}
+  s.description = %q{Adds an enumerable attribute to an ActiveRecord-backed class}
+  s.email = %q{justin@mobilecommons.com}
+  
+  s.files = ["values_for.gemspec", "lib/values_for.rb", "LICENSE", "Rakefile", "README.rdoc", "spec/values_for_spec.rb", "spec/spec_helper.rb"]
+  
+  s.has_rdoc = true
+  s.homepage = %q{http://github.com/mcommons/values_for}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.1}
+  s.summary = %q{Adds an enumerable attribute to an ActiveRecord-backed class}
+  s.test_files = ["spec/values_for_spec.rb", "spec/spec_helper.rb"]
+
+  s.extra_rdoc_files = [ "README.rdoc" ]
+  
+  s.rdoc_options += [
+    '--title', 'Enum For',
+    '--main', 'README.rdoc',
+    '--line-numbers',
+    '--inline-source'
+   ]
+
+  %w[ activerecord activesupport ].each do |dep|
+    s.add_dependency(dep)
+  end
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+  end
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification 
+name: mcommons-values_for
+version: !ruby/object:Gem::Version 
+  version: 0.0.7
+platform: ruby
+authors: 
+- Mal McKay and Justin Leitgeb
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-06-17 00:00:00 -07: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: activesupport
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: Adds an enumerable attribute to an ActiveRecord-backed class
+email: justin@mobilecommons.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- values_for.gemspec
+- lib/values_for.rb
+- LICENSE
+- Rakefile
+- README.rdoc
+- spec/values_for_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/mcommons/values_for
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+- --title
+- Enum For
+- --main
+- README.rdoc
+- --line-numbers
+- --inline-source
+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: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Adds an enumerable attribute to an ActiveRecord-backed class
+test_files: 
+- spec/values_for_spec.rb
+- spec/spec_helper.rb