preferences 0.3.0 → 0.3.1

data/CHANGELOG.rdoc

@@ -1,5 +1,9 @@
 == master
 
+== 0.3.1 / 2009-04-25
+
+* Rename Preference#attribute to #name to avoid conflicts with reserved methods in ActiveRecord
+
 == 0.3.0 / 2009-04-13
 
 * Add dependency on Rails 2.3

data/Rakefile

@@ -5,7 +5,7 @@ require 'rake/contrib/sshpublisher'
 
 spec = Gem::Specification.new do |s|
   s.name              = 'preferences'
-  s.version           = '0.3.0'
+  s.version           = '0.3.1'
   s.platform          = Gem::Platform::RUBY
   s.summary           = 'Adds support for easily creating custom preferences for models'
   

data/app/models/preference.rb

@@ -5,20 +5,20 @@
 # In addition to simple named preferences, preferences can also be grouped by
 # a particular value, be it a string or ActiveRecord object.  For example, a
 # User may have a preferred color for a particular Car.  In this case, the
-# +owner+ is the User, the +attribute+ is the color, and the +group+ is the Car.
-# This allows preferences to have a sort of context around them.
+# +owner+ is the User record, the +name+ is "color", and the +group+ is the
+# Car record.  This allows preferences to have a sort of context around them.
 class Preference < ActiveRecord::Base
-  belongs_to  :owner, :polymorphic => true
-  belongs_to  :group, :polymorphic => true
+  belongs_to :owner, :polymorphic => true
+  belongs_to :group, :polymorphic => true
   
-  validates_presence_of :attribute, :owner_id, :owner_type
+  validates_presence_of :name, :owner_id, :owner_type
   validates_presence_of :group_type, :if => :group_id?
   
   class << self
     # Splits the given group into its corresponding id and type. For simple
-    # primitives, the id will be nil.  For complex types, specifically ActiveRecord
-    # objects, the id is the unique identifier stored in the databse for the
-    # record.
+    # primitives, the id will be nil.  For complex types, specifically
+    # ActiveRecord objects, the id is the unique identifier stored in the
+    # database for the record.
     # 
     # For example,
     # 
@@ -36,7 +36,7 @@ class Preference < ActiveRecord::Base
     end
   end
   
-  # The definition for the attribute
+  # The definition of the preference as defined in the owner's model
   def definition
     # Optimize number of queries to the database by only looking up the actual
     # owner record for STI cases when the definition can't be found in the
@@ -58,9 +58,8 @@ class Preference < ActiveRecord::Base
   alias_method_chain :group, :optional_lookup
   
   private
-    # Finds the definition for this preference's attribute in the given owner
-    # class.
+    # Finds the definition for this preference in the given owner class.
     def find_definition(owner_class)
-      owner_class.respond_to?(:preference_definitions) && owner_class.preference_definitions[attribute]
+      owner_class.respond_to?(:preference_definitions) && owner_class.preference_definitions[name]
     end
 end

data/lib/preferences/preference_definition.rb

@@ -1,23 +1,23 @@
 module Preferences
   # Represents the definition of a preference for a particular model
   class PreferenceDefinition
-    def initialize(attribute, *args) #:nodoc:
+    def initialize(name, *args) #:nodoc:
       options = args.extract_options!
       options.assert_valid_keys(:default)
       
       @type = args.first ? args.first.to_s : 'boolean'
       
       # Create a column that will be responsible for typecasting
-      @column = ActiveRecord::ConnectionAdapters::Column.new(attribute.to_s, options[:default], @type == 'any' ? nil : @type)
+      @column = ActiveRecord::ConnectionAdapters::Column.new(name.to_s, options[:default], @type == 'any' ? nil : @type)
     end
     
-    # The attribute which is being preferenced
-    def attribute
+    # The name of the preference
+    def name
       @column.name
     end
     
     # The default value to use for the preference in case none have been
-    # previously defined      
+    # previously defined
     def default_value
       @column.default
     end

data/lib/preferences.rb

@@ -23,7 +23,7 @@ require 'preferences/preference_definition'
 # == Validations
 # 
 # Since the generated accessors for a preference allow the preference to be
-# treated just like regular ActiveRecord column attributes, they can also be
+# treated just like regular ActiveRecord attributes, they can also be
 # validated against in the same way.  For example,
 # 
 #   class User < ActiveRecord::Base
@@ -76,8 +76,8 @@ module Preferences
     # 
     # == Generated accessors
     # 
-    # In addition to calling <tt>prefers?</tt> and +preferred+ on a record, you
-    # can also use the shortcut accessor methods that are generated when a
+    # In addition to calling <tt>prefers?</tt> and +preferred+ on a record,
+    # you can also use the shortcut accessor methods that are generated when a
     # preference is defined.  For example,
     # 
     #   class User < ActiveRecord::Base
@@ -114,7 +114,7 @@ module Preferences
     #   user.preferred_color?(car)          # => true
     #   
     #   user.save!  # => true
-    def preference(attribute, *args)
+    def preference(name, *args)
       unless included_modules.include?(InstanceMethods)
         class_inheritable_hash :preference_definitions
         self.preference_definitions = {}
@@ -130,32 +130,32 @@ module Preferences
       end
       
       # Create the definition
-      attribute = attribute.to_s
-      definition = PreferenceDefinition.new(attribute, *args)
-      self.preference_definitions[attribute] = definition
-      self.default_preferences[attribute] = definition.default_value
+      name = name.to_s
+      definition = PreferenceDefinition.new(name, *args)
+      self.preference_definitions[name] = definition
+      self.default_preferences[name] = definition.default_value
       
-      # Create short-hand accessor methods, making sure that the attribute
+      # Create short-hand accessor methods, making sure that the name
       # is method-safe in terms of what characters are allowed
-      attribute = attribute.gsub(/[^A-Za-z0-9_-]/, '').underscore
+      name = name.gsub(/[^A-Za-z0-9_-]/, '').underscore
       
       # Query lookup
-      define_method("preferred_#{attribute}?") do |*group|
-        preferred?(attribute, group.first)
+      define_method("preferred_#{name}?") do |*group|
+        preferred?(name, group.first)
       end
-      alias_method "prefers_#{attribute}?", "preferred_#{attribute}?"
+      alias_method "prefers_#{name}?", "preferred_#{name}?"
       
       # Reader
-      define_method("preferred_#{attribute}") do |*group|
-        preferred(attribute, group.first)
+      define_method("preferred_#{name}") do |*group|
+        preferred(name, group.first)
       end
-      alias_method "prefers_#{attribute}", "preferred_#{attribute}"
+      alias_method "prefers_#{name}", "preferred_#{name}"
       
       # Writer
-      define_method("preferred_#{attribute}=") do |*args|
-        set_preference(*([attribute] + [args].flatten))
+      define_method("preferred_#{name}=") do |*args|
+        set_preference(*([name] + [args].flatten))
       end
-      alias_method "prefers_#{attribute}=", "preferred_#{attribute}="
+      alias_method "prefers_#{name}=", "preferred_#{name}="
       
       definition
     end
@@ -211,7 +211,7 @@ module Preferences
       # Find all of the stored preferences
       stored_preferences = self.stored_preferences.find(:all, :conditions => conditions)
       
-      # Hashify attribute -> value or group -> attribute -> value
+      # Hashify name -> value or group -> name -> value
       stored_preferences.inject(self.class.default_preferences.dup) do |all_preferences, preference|
         if !group && (preference_group = preference.group)
           preferences = all_preferences[preference_group] ||= self.class.default_preferences.dup
@@ -219,13 +219,13 @@ module Preferences
           preferences = all_preferences
         end
         
-        preferences[preference.attribute] = preference.value
+        preferences[preference.name] = preference.value
         all_preferences
       end
     end
     
-    # Queries whether or not a value is present for the given attribute.  This
-    # is dependent on how the value is type-casted.
+    # Queries whether or not a value is present for the given preference.
+    # This is dependent on how the value is type-casted.
     # 
     # == Examples
     # 
@@ -242,15 +242,15 @@ module Preferences
     #   user.set_preference(:color, nil)
     #   user.preferred(:color)              # => nil
     #   user.preferred?(:color)             # => false
-    def preferred?(attribute, group = nil)
-      attribute = attribute.to_s
+    def preferred?(name, group = nil)
+      name = name.to_s
       
-      value = preferred(attribute, group)
-      preference_definitions[attribute].query(value)
+      value = preferred(name, group)
+      preference_definitions[name].query(value)
     end
     alias_method :prefers?, :preferred?
     
-    # Gets the actual value stored for the given attribute, or the default
+    # Gets the actual value stored for the given preference, or the default
     # value if nothing is present.
     # 
     # == Examples
@@ -266,27 +266,27 @@ module Preferences
     #   
     #   user.set_preference(:color, 'blue')
     #   user.preferred(:color)            # => "blue"
-    def preferred(attribute, group = nil)
-      attribute = attribute.to_s
+    def preferred(name, group = nil)
+      name = name.to_s
       
-      if @preference_values && @preference_values[attribute] && @preference_values[attribute].include?(group)
-        # Value for this attribute/group has been written, but not saved yet:
+      if @preference_values && @preference_values[group] && @preference_values[group].include?(name)
+        # Value for this group/name has been written, but not saved yet:
         # grab from the pending values
-        value = @preference_values[attribute][group]
+        value = @preference_values[group][name]
       else
         # Split the group being filtered
         group_id, group_type = Preference.split_group(group)
         
         # Grab the first preference; if it doesn't exist, use the default value
-        preference = stored_preferences.find(:first, :conditions => {:attribute => attribute, :group_id => group_id, :group_type => group_type})
-        value = preference ? preference.value : preference_definitions[attribute].default_value
+        preference = stored_preferences.find(:first, :conditions => {:name => name, :group_id => group_id, :group_type => group_type})
+        value = preference ? preference.value : preference_definitions[name].default_value
       end
       
       value
     end
     alias_method :prefers, :preferred
     
-    # Sets a new value for the given attribute.  The actual Preference record
+    # Sets a new value for the given preference.  The actual Preference record
     # is *not* created until this record is saved.  In this way, preferences
     # act *exactly* the same as attributes.  They can be written to and
     # validated against, but won't actually be written to the database until
@@ -300,12 +300,12 @@ module Preferences
     #   
     #   user.set_preference(:color, 'blue', Car.first)  # => "blue"
     #   user.save!
-    def set_preference(attribute, value, group = nil)
-      attribute = attribute.to_s
+    def set_preference(name, value, group = nil)
+      name = name.to_s
       
       @preference_values ||= {}
-      @preference_values[attribute] ||= {}
-      @preference_values[attribute][group] = value
+      @preference_values[group] ||= {}
+      @preference_values[group][name] = value
       
       value
     end
@@ -315,10 +315,11 @@ module Preferences
       # was last saved
       def update_preferences
         if @preference_values
-          @preference_values.each do |attribute, grouped_records|
-            grouped_records.each do |group, value|
-              group_id, group_type = Preference.split_group(group)
-              attributes = {:attribute => attribute, :group_id => group_id, :group_type => group_type}
+          @preference_values.each do |group, new_preferences|
+            group_id, group_type = Preference.split_group(group)
+            
+            new_preferences.each do |name, value|
+              attributes = {:name => name, :group_id => group_id, :group_type => group_type}
               
               # Find an existing preference or build a new one
               preference = stored_preferences.find(:first, :conditions => attributes) ||  stored_preferences.build(attributes)

data/test/factory.rb

@@ -52,7 +52,7 @@ module Factory
   build Preference do |attributes|
     attributes[:owner] = create_user unless attributes.include?(:owner)
     attributes.reverse_merge!(
-      :attribute => 'notifications',
+      :name => 'notifications',
       :value => false
     )
   end

data/test/unit/preference_definition_test.rb

@@ -5,8 +5,8 @@ class PreferenceDefinitionByDefaultTest < ActiveSupport::TestCase
     @definition = Preferences::PreferenceDefinition.new(:notifications)
   end
   
-  def test_should_have_an_attribute
-    assert_equal 'notifications', @definition.attribute
+  def test_should_have_a_name
+    assert_equal 'notifications', @definition.name
   end
   
   def test_should_not_have_a_default_value

data/test/unit/preference_test.rb

@@ -5,8 +5,8 @@ class PreferenceByDefaultTest < ActiveSupport::TestCase
     @preference = Preference.new
   end
   
-  def test_should_not_have_an_attribute
-    assert @preference.attribute.blank?
+  def test_should_not_have_a_name
+    assert @preference.name.blank?
   end
   
   def test_should_not_have_an_owner
@@ -40,10 +40,10 @@ class PreferenceTest < ActiveSupport::TestCase
     assert preference.valid?
   end
   
-  def test_should_require_an_attribute
-    preference = new_preference(:attribute => nil)
+  def test_should_require_a_name
+    preference = new_preference(:name => nil)
     assert !preference.valid?
-    assert preference.errors.invalid?(:attribute)
+    assert preference.errors.invalid?(:name)
   end
   
   def test_should_require_an_owner_id
@@ -84,7 +84,7 @@ class PreferenceTest < ActiveSupport::TestCase
   def test_should_protect_attributes_from_mass_assignment
     preference = Preference.new(
       :id => 1,
-      :attribute => 'notifications',
+      :name => 'notifications',
       :value => '123',
       :owner_id => 1,
       :owner_type => 'User',
@@ -93,7 +93,7 @@ class PreferenceTest < ActiveSupport::TestCase
     )
     
     assert_nil preference.id
-    assert_equal 'notifications', preference.attribute
+    assert_equal 'notifications', preference.name
     assert_equal '123', preference.value
     assert_equal 1, preference.owner_id
     assert_equal 'User', preference.owner_type
@@ -132,7 +132,7 @@ class PreferenceAfterBeingCreatedTest < ActiveSupport::TestCase
   def setup
     User.preference :notifications, :boolean
     
-    @preference = create_preference(:attribute => 'notifications')
+    @preference = create_preference(:name => 'notifications')
   end
   
   def test_should_have_an_owner
@@ -178,18 +178,18 @@ class PreferenceWithActiveRecordGroupTest < ActiveSupport::TestCase
   end
 end
 
-class PreferenceWithBooleanAttributeTest < ActiveSupport::TestCase
+class PreferenceWithBooleanTypeTest < ActiveSupport::TestCase
   def setup
     User.preference :notifications, :boolean
   end
   
   def test_should_type_cast_nil_values
-    preference = new_preference(:attribute => 'notifications', :value => nil)
+    preference = new_preference(:name => 'notifications', :value => nil)
     assert_nil preference.value
   end
   
   def test_should_type_cast_numeric_values
-    preference = new_preference(:attribute => 'notifications', :value => 0)
+    preference = new_preference(:name => 'notifications', :value => 0)
     assert_equal false, preference.value
     
     preference.value = 1
@@ -197,7 +197,7 @@ class PreferenceWithBooleanAttributeTest < ActiveSupport::TestCase
   end
   
   def test_should_type_cast_boolean_values
-    preference = new_preference(:attribute => 'notifications', :value => false)
+    preference = new_preference(:name => 'notifications', :value => false)
     assert_equal false, preference.value
     
     preference.value = true
@@ -213,7 +213,7 @@ end
 class PreferenceWithSTIOwnerTest < ActiveSupport::TestCase
   def setup
     @manager = create_manager
-    @preference = create_preference(:owner => @manager, :attribute => 'health_insurance', :value => true)
+    @preference = create_preference(:owner => @manager, :name => 'health_insurance', :value => true)
   end
   
   def test_should_have_an_owner

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: preferences
 version: !ruby/object:Gem::Version 
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors: 
 - Aaron Pfeifer
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-04-13 00:00:00 -04:00
+date: 2009-04-25 00:00:00 -04:00
 default_executable: 
 dependencies: []