mcommons-enum_for 0.0.3 → 0.0.4

data/README.rdoc

@@ -1,25 +1,16 @@
-= Enum For
+= enum_for
+
+enum_for is an ActiveRecord extension enabling the easy use of enumerated types for your models.
+
+== Description
 
 enum_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, enum_for 
 stores the content of the enumerable attribute in a varchar column of the database.
 
-It also defines certain useful methods on your model.  For example, if you declare :state to be
-an enumerable column, enum_fu allow you to see the valid states by calling the method "states"
-(note the automatically pluralized form) on the class.
-
-enum_fu 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, enum_fu would
-define constants on your model Model::STATE_STARTING and Model::STATE_FINISHED with the contents of these 
-constants :starting and :finished respectively.
-
-enum_fu 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.
-
-Finally, enum_fu creates named scopes on your model, so that you can easily find all records belonging to 
-a given enumerable type.  Following the above example, Taco.taste_good would return all tacos that taste
-good.
+enum_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
 
@@ -29,34 +20,83 @@ enum_for is available as a gem available on GitHub.  Install with:
 
 You'll probable want a line like the following in your environment.rb:
 
-  config.gem "enum_for"
+  config.gem 'mcommons-enum_for', :lib => 'enum_for'
 
-== Examples
+== Basic Usage
 
-Sets up a basic enumerable attribute on an ActiveRecord model.  This assumes that a previous
+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
     enum_for :state, :has => [ :new, :composed, :served, :eaten ]
   end
-  
-To query all eaten tacos using the automatically-generated named scopes:
 
-  Taco.state_eaten
-  
-To find out valid states on a model:
+For all enum_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
+
+enum_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:
+
+  enum_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:
 
-  Taco.states
+  class Taco < ActiveRecord::Base
+    enum_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
+
+enum_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
+
+enum_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, 
+enum_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.
   
-To create an enumerable type on a model, overriding the default prefix given to named_scopes:
+== Configuration
+
+enum_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 enum_for.  You may 
+also omit the addition of the prefix by passing :prefix => nil to enum_for. Example:
 
   class Taco < ActiveRecord::Base
     enum_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.  Note that this feature 
-also allows for the prefix to be omitted entirely if the value 'nil' is given instead of a String.
+would have prefixed the named_scopes with the name of the attribute.
+
+= TODO
+
+ * Add option for default value
 
 == Authors
 

data/Rakefile

@@ -16,6 +16,6 @@ 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_files.include('README.rdoc')
   rdoc.rdoc_files.include('lib/**/*.rb')
 end

data/enum_for.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = %q{enum_for}
-  s.version = "0.0.3"
+  s.version = "0.0.4"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Mal McKay and Justin Leitgeb"]

data/lib/enum_for.rb

@@ -14,6 +14,7 @@ module EnumFor
     # to +enum_for+.
     def enum_for(*args)
       options   = args.extract_options!
+      additives = options[:add].respond_to?(:each) ? options[:add] : ( options[:add].nil? ? [ ] : [ options[:add] ] )
       attribute = args.first
       
       plural_attribute = attribute.to_s.pluralize
@@ -22,7 +23,7 @@ module EnumFor
       # so no need to accept only one form in the validation.
       all_valid_values = options[:has].map{|v| v.to_s} | options[:has].map{|v| v.to_sym}
       
-      validates_inclusion_of attribute, options.except(:has, :prefix).merge(:in => all_valid_values )
+      validates_inclusion_of attribute, options.except(:has, :prefix, :add).merge(:in => all_valid_values )
       const_set(plural_attribute.upcase, options[:has])
       
       prefix = options.has_key?(:prefix) ? options[:prefix] : attribute.to_s
@@ -32,14 +33,13 @@ module EnumFor
       end
 
       prefixed_values.each do |pv, v|
-        # Set constants for values
-        const_set(pv.upcase, v)
+        const_set(pv.upcase, v) if additives.include?(:constants)
         
         # Create named scope for this value
-        named_scope pv, :conditions => { attribute => v.to_s }
+        named_scope pv, :conditions => { attribute => v.to_s } if additives.include?(:named_scopes)
 
         # Create predicate methods for values
-        unless self.instance_methods.include?(pv)
+        if additives.include?(:predicate_methods) && !self.instance_methods.include?(pv)
           define_method("#{pv}?") do
             read_attribute(attribute) == v.to_s
           end

data/spec/enum_for_spec.rb

@@ -18,15 +18,16 @@ ActiveRecord::Base.silence do
   end
 end
 
-class Taco < ActiveRecord::Base
-  enum_for :state, :has => [ :new, :composed, :served, :eaten ]
-end
 
 describe EnumFor do
   before do
     @taco = Taco.new(:state => 'new')
   end
   
+  class Taco < ActiveRecord::Base
+    enum_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
@@ -57,22 +58,49 @@ describe EnumFor 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
+      enum_for :state, :has => [ :new, :composed, :served, :eaten ]
+    end
+    
+    class WithConstants < ActiveRecord::Base
+      enum_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
-      Taco::STATE_EATEN.should == :eaten
+      WithConstants::STATE_EATEN.should == :eaten
     end
   end
   
   describe "definition of predicate methods" do
-    it "should define predicate methods for each valid state" do
-      @taco.should respond_to(:state_eaten?)
+    class WithPredicateMethods < ActiveRecord::Base
+      set_table_name "tacos"
+      enum_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"
-      enum_for :state, :has => [:stuff, :morestuff], :prefix => nil
+      enum_for :state, :has => [:stuff, :morestuff], :prefix => nil, :add => :predicate_methods
     end
 
     it "should not prefix predicate methods if asked not to" do
@@ -91,6 +119,21 @@ describe EnumFor do
     end
   end
   
+  describe "with an Array of additives" do
+    class BeefJerkey < ActiveRecord::Base
+      set_table_name "tacos"
+      enum_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"
@@ -122,19 +165,32 @@ describe EnumFor do
   end
   
   describe "named scope creation" do
-    before do
-      Taco.delete_all
-      
-      2.times { Taco.create(:state => 'new') }
-      3.times { Taco.create(:state => 'composed') }
+    describe "when not added" do
+      it "should not create named scopes" do
+        Taco.should_not respond_to(:state_composed)
+      end
     end
     
-    it "should have two new tacos" do
-      Taco.state_new.size.should == 2
-    end
+    describe "when added" do
+      class Tequila < ActiveRecord::Base
+        set_table_name "tacos"
+        enum_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 composed tacos" do
-      Taco.state_composed.size.should == 3
+      it "should have two delicious tequilas" do
+        Tequila.state_delicious.size.should == 3
+      end
     end
   end
   

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: mcommons-enum_for
 version: !ruby/object:Gem::Version 
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors: 
 - Mal McKay and Justin Leitgeb