values_for 0.0.9

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,109 @@
+= 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.  The field will
+automatically validate using validates_inclusion_of and accepts all the same options. 
+
+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 automatically runs validates_inclusion_of on this field.  All the validates_inclusion_of options are 
+supported. For example, you can pass :allow_nil=>true to allow the field to be nil.
+
+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 :add
+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 ], :add => [ :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 ], :add => :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
+
+Justin Leitgeb, with contributions from Mal McKay 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,80 @@
+module ValuesFor
+
+  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
+
+      # We don't accept the case where an empty string is a valid value, but we should provide a useful error message
+      raise ArgumentError, "Can't use values_for with an empty string" if opts[:has].any?{|v| v.respond_to?(:empty?) && v.empty? }
+      
+      # 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
+        unless self[attribute].nil? || self[attribute].empty?   #   unless self[:foo].nil? || self[:foo].empty?
+          self[attribute].to_sym                                #     self[:foo].to_sym unless self[:foo].nil?
+        end                                                     #   end
+      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.nil? ? nil : other.to_s   #   self[foo] = other unless other.nil?
+      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, ValuesFor)

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+require 'rubygems'
+require 'mocha'
+require 'spec'
+
+require 'values_for'
+
+Spec::Runner.configure do |config|
+  config.mock_with(:mocha)
+end

data/spec/values_for_spec.rb

@@ -0,0 +1,230 @@
+require 'rubygems'
+require 'activerecord'
+
+require '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 ValuesFor 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 "when a user tries to set an empty String as a valid value" do
+    it "should raise an IllegalArgumentError" do
+      lambda {
+        class Food2 < ActiveRecord::Base
+          set_table_name "tacos"
+          values_for :state, :has => ['stuff', '']
+        end
+      }.should raise_error(ArgumentError)
+    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 "getting and setting nil values" do
+    class Food2 < ActiveRecord::Base
+      set_table_name "tacos"
+      values_for :state, :has => ['stuff', 'morestuff'], :prefix => nil, :allow_nil => true, :message => "is great!"
+    end
+    
+    before do
+      @f = Food2.new
+      @f.state = nil
+    end
+    
+    it "should return a nil value without error" do
+      lambda {
+        @f.state
+      }.should_not raise_error
+    end
+    
+    it "should return nil when nil is set" do
+      @f.state.should == nil
+    end
+    
+    it "should store nil when nil is set" do
+      @f.state_before_type_cast.should == nil
+    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 three delicious tequilas" do
+        Tequila.state_delicious.size.should == 3
+      end
+    end
+  end
+  
+end

data/values_for.gemspec

@@ -0,0 +1,52 @@
+Gem::Specification.new do |s|
+  s.name = "values_for"
+  s.version = "0.0.9"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.author = "Justin Leitgeb"
+  
+  s.date = "2009-06-17"
+  s.description = <<-EOS
+    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.  The field will
+    automatically validate using validates_inclusion_of and accepts all the same options. 
+
+    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.
+  EOS
+  
+  s.email = "justin@stackbuilders.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 = "http://github.com/jsl/values_for"
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.1}
+  s.summary = "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', 'Values 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,107 @@
+--- !ruby/object:Gem::Specification 
+name: values_for
+version: !ruby/object:Gem::Version 
+  hash: 13
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 9
+  version: 0.0.9
+platform: ruby
+authors: 
+- Justin Leitgeb
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-06-17 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id002
+description: "    values_for makes your ActiveRecord-backed class work with an enumerable type.  Instead of existing \n    ActiveRecord plugins such as enum_fu, which store the enumerable attribute as an integer, values_for \n    stores the content of the enumerable attribute in a varchar column of the database.  The field will\n    automatically validate using validates_inclusion_of and accepts all the same options. \n\n    values_for will also optionally create named scopes, predicate methods, and constants defining the \n    possible values for enumerable types on your model.  By default, however, it avoids polluting your\n    model with things you may not need unless these features are specifically requested.\n"
+email: justin@stackbuilders.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/jsl/values_for
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+- --title
+- Values For
+- --main
+- README.rdoc
+- --line-numbers
+- --inline-source
+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.3.7
+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