bitmask-attribute 1.0.0 → 1.1.0

data/README.markdown

@@ -1,14 +1,16 @@
-# bitmask-attribute
+bitmask-attribute
+=================
 
 Transparent manipulation of bitmask attributes.
 
-## Example
+Example
+-------
 
 Simply declare an existing integer column as a bitmask with its possible
 values.
 
     class User < ActiveRecord::Base
-      bitmask :roles, :as => [:writer, :publisher, :editor] 
+      bitmask :roles, :as => [:writer, :publisher, :editor, :proofreader] 
     end
     
 You can then modify the column using the declared values without resorting
@@ -21,27 +23,91 @@ to manual bitmasks.
     user.roles
     # => [:publisher, :editor, :writer]
     
-For the moment, querying for bitmasks is left as an exercise to the reader,
-but here's how to grab the bitmask for a specific possible value for use in
-your SQL query:
+It's easy to find out if a record has a given value:
 
-    bitmask = User.bitmasks[:roles][:editor]
-    # Use `bitmask` as needed
+    user.roles?(:editor)
+    # => true
+    
+You can check for multiple values (uses an `and` boolean):
+
+    user.roles?(:editor, :publisher)
+    # => true
+    user.roles?(:editor, :proofreader)
+    # => false
+
+Or, just check if any values are present:
+
+    user.roles?
+    # => true
+
+Named Scopes
+------------
+
+A couple useful named scopes are also generated when you use
+`bitmask`:
+
+    User.with_roles
+    # => (all users with roles)
+    User.with_roles(:editor)
+    # => (all editors)
+    User.with_roles(:editor, :writer)
+    # => (all users who are BOTH editors and writers)
+
+Later we'll support an `or` boolean; for now, do something like:
+
+    User.with_roles(:editor) + User.with_roles(:writer)
+    # => (all users who are EITHER editors and writers)
+
+Find records without any bitmask set:
+
+    User.without_roles
+    # => (all users without a role)
 
-## Modifying possible values
+Later we'll support finding records without a specific bitmask.
 
-Once you have data using a bitmask, don't change the order of the values,
-remove any values, or insert any new values in the array anywhere except at
-the end.
+Adding Methods
+--------------
 
-## Contributing and reporting issues
+You can add your own methods to the bitmasked attributes (similar to
+named scopes):
+
+    bitmask :other_attribute, :as => [:value1, :value2] do
+      def worked?
+        true
+      end
+    end
+
+    user = User.first
+    user.other_attribute.worked?
+    # => true
+
+
+Warning: Modifying possible values
+----------------------------------
+
+IMPORTANT: Once you have data using a bitmask, don't change the order
+of the values, remove any values, or insert any new values in the `:as`
+array anywhere except at the end.  You won't like the results.
+
+Contributing and reporting issues
+---------------------------------
 
 Please feel free to fork & contribute fixes via GitHub pull requests.
 The official repository for this project is
 http://github.com/bruce/bitmask-attribute
 
-Issues can be reported at http://github.com/bruce/bitmask-attribute/issues
+Issues can be reported at
+http://github.com/bruce/bitmask-attribute/issues
+
+Credits
+-------
+
+Thanks to the following contributors:
+
+* [Jason L Perry](http://github.com/ambethia)
+* [Nicolas Fouché](http://github.com/nfo)
 
-## Copyright
+Copyright
+---------
 
 Copyright (c) 2007-2009 Bruce Williams. See LICENSE for details.

data/VERSION

@@ -0,0 +1 @@
+1.1.0

data/lib/bitmask_attribute.rb

@@ -15,7 +15,9 @@ module BitmaskAttribute
       validate_for model
       generate_bitmasks_on model
       override model
-      create_convenience_method_on model
+      create_convenience_class_method_on(model)
+      create_convenience_instance_methods_on(model)
+      create_named_scopes_on(model)
     end
     
     #######
@@ -23,8 +25,13 @@ module BitmaskAttribute
     #######
 
     def validate_for(model)
-      unless model.columns.detect { |col| col.name == attribute.to_s && col.type == :integer }
-        raise ArgumentError, "`#{attribute}' is not an integer column of `#{model}'"
+      # The model cannot be validated if it is preloaded and the attribute/column is not in the
+      # database (the migration has not been run).  This usually
+      # occurs in the 'test' and 'production' environments.
+      return if defined?(Rails) && Rails.configuration.cache_classes
+
+      unless model.columns.detect { |col| col.name == attribute.to_s }
+        raise ArgumentError, "`#{attribute}' is not an attribute of `#{model}'"
       end
     end
     
@@ -53,12 +60,12 @@ module BitmaskAttribute
       model.class_eval %(
         def #{attribute}=(raw_value)
           values = raw_value.kind_of?(Array) ? raw_value : [raw_value]
-          #{attribute}.replace(values)
+          self.#{attribute}.replace(values.reject(&:blank?))
         end
       )
     end
     
-    def create_convenience_method_on(model)
+    def create_convenience_class_method_on(model)
       model.class_eval %(
         def self.bitmask_for_#{attribute}(*values)
           values.inject(0) do |bitmask, value|
@@ -70,6 +77,53 @@ module BitmaskAttribute
         end
       )
     end
+
+
+    def create_convenience_instance_methods_on(model)
+      values.each do |value|
+        model.class_eval %(
+          def #{attribute}_for_#{value}?                  
+            self.#{attribute}?(:#{value})
+          end
+        )
+      end
+      model.class_eval %(
+        def #{attribute}?(*values)
+          if !values.blank?
+            values.all? do |value|
+              self.#{attribute}.include?(value)
+            end
+          else
+            self.#{attribute}.present?
+          end
+        end
+      )
+    end
+    
+    def create_named_scopes_on(model)
+      model.class_eval %(
+        named_scope :with_#{attribute},
+          proc { |*values|
+            if values.blank?
+              {:conditions => '#{attribute} > 0 OR #{attribute} IS NOT NULL'}
+            else
+              sets = values.map do |value|
+                mask = #{model}.bitmask_for_#{attribute}(value)
+                "#{attribute} & \#{mask} <> 0"
+              end
+              {:conditions => sets.join(' AND ')}
+            end
+          }
+        named_scope :without_#{attribute}, :conditions => "#{attribute} == 0 OR #{attribute} IS NULL"
+        named_scope :no_#{attribute},      :conditions => "#{attribute} == 0 OR #{attribute} IS NULL"
+      )
+      values.each do |value|
+        model.class_eval %(
+          named_scope :#{attribute}_for_#{value},
+                      :conditions => ['#{attribute} & ? <> 0', #{model}.bitmask_for_#{attribute}(:#{value})]
+        )
+      end      
+    end
     
   end
   
@@ -97,4 +151,4 @@ module BitmaskAttribute
       
   end
   
-end
+end

data/lib/bitmask_attribute/value_proxy.rb

@@ -33,7 +33,7 @@ module BitmaskAttribute
     #######
     
     def validate!
-      each do |value| 
+      each do |value|
         if @mapping.key? value
           true
         else
@@ -53,7 +53,7 @@ module BitmaskAttribute
     end
   
     def extract_values
-      stored = @record.send(:read_attribute, @attribute) || 0
+      stored = [@record.send(:read_attribute, @attribute) || 0, 0].max
       @mapping.inject([]) do |values, (value, bitmask)|
         returning values do
           values << value.to_sym if (stored & bitmask > 0)

data/test/bitmask_attribute_test.rb

@@ -4,6 +4,11 @@ class BitmaskAttributeTest < Test::Unit::TestCase
   
   context "Campaign" do
 
+    teardown do
+      Company.destroy_all
+      Campaign.destroy_all
+    end
+
     should "can assign single value to bitmask" do
       assert_stored Campaign.new(:medium => :web), :web
     end
@@ -68,7 +73,7 @@ class BitmaskAttributeTest < Test::Unit::TestCase
         Campaign.bitmask_for_medium(:web, :print)
       )
     end
-
+    
     should "assert use of unknown value in convenience method will result in exception" do
       assert_unsupported { Campaign.bitmask_for_medium(:web, :and_this_isnt_valid)  }
     end
@@ -81,6 +86,113 @@ class BitmaskAttributeTest < Test::Unit::TestCase
       assert_equal Campaign.bitmask_for_medium(:web, :print), string_bit
     end
 
+    should "save bitmask with non-standard attribute names" do
+      campaign = Campaign.new(:Legacy => [:upper, :case])
+      assert campaign.save
+      assert_equal [:upper, :case], Campaign.find(campaign.id).Legacy
+    end
+
+    should "ignore blanks fed as values" do
+      campaign = Campaign.new(:medium => [:web, :print, ''])
+      assert_stored campaign, :web, :print
+    end
+    
+    context "checking" do
+
+      setup { @campaign = Campaign.new(:medium => [:web, :print]) }
+
+      context "for a single value" do
+      
+        should "be supported by an attribute_for_value convenience method" do
+          assert @campaign.medium_for_web?
+          assert @campaign.medium_for_print?
+          assert !@campaign.medium_for_email?
+        end
+        
+        should "be supported by the simple predicate method" do
+          assert @campaign.medium?(:web)
+          assert @campaign.medium?(:print)
+          assert !@campaign.medium?(:email)
+        end
+
+      end
+      
+      context "for multiple values" do
+        
+        should "be supported by the simple predicate method" do
+          assert @campaign.medium?(:web, :print)
+          assert !@campaign.medium?(:web, :email)
+        end
+
+      end
+
+    end
+
+    context "named scopes" do
+
+      setup do
+        @company = Company.create(:name => "Test Co, Intl.")
+        @campaign1 = @company.campaigns.create :medium => [:web, :print]        
+        @campaign2 = @company.campaigns.create
+        @campaign3 = @company.campaigns.create :medium => [:web, :email] 
+      end
+
+      should "support retrieval by any value" do
+        assert_equal [@campaign1, @campaign3], @company.campaigns.with_medium
+      end
+
+      should "support retrieval by one matching value" do
+        assert_equal [@campaign1], @company.campaigns.with_medium(:print)
+      end
+      
+      should "support retrieval by all matching values" do
+        assert_equal [@campaign1], @company.campaigns.with_medium(:web, :print)
+        assert_equal [@campaign3], @company.campaigns.with_medium(:web, :email)
+      end
+
+      should "support retrieval for no values" do
+        assert_equal [@campaign2], @company.campaigns.without_medium
+      end
+
+    end
+
+    should "can check if at least one value is set" do
+      campaign = Campaign.new(:medium => [:web, :print])
+      
+      assert campaign.medium?
+      
+      campaign = Campaign.new
+      
+      assert !campaign.medium?
+    end
+
+    should "find by bitmask values" do
+      campaign = Campaign.new(:medium => [:web, :print])
+      assert campaign.save
+      
+      assert_equal(
+        Campaign.find(:all, :conditions => ['medium & ? <> 0', Campaign.bitmask_for_medium(:print)]),
+        Campaign.medium_for_print
+      )
+      
+      assert_equal Campaign.medium_for_print, Campaign.medium_for_print.medium_for_web
+      
+      assert_equal [], Campaign.medium_for_email
+      assert_equal [], Campaign.medium_for_web.medium_for_email
+    end
+
+    should "find no values" do
+      campaign = Campaign.create(:medium => [:web, :print])
+      assert campaign.save
+      
+      assert_equal [], Campaign.no_medium
+      
+      campaign.medium = []
+      assert campaign.save
+      
+      assert_equal [campaign], Campaign.no_medium
+    end
+
     #######
     private
     #######

data/test/test_helper.rb

@@ -14,26 +14,37 @@ $LOAD_PATH.unshift(File.dirname(__FILE__))
 require 'bitmask-attribute'
 require File.dirname(__FILE__) + '/../rails/init'
 
+# ActiveRecord::Base.logger = Logger.new(STDOUT)
+
 ActiveRecord::Base.establish_connection(
   :adapter  => 'sqlite3',
   :database => ':memory:'
 )
 
 ActiveRecord::Schema.define do 
-  create_table :campaigns do |table|
-    table.column :medium, :integer
-    table.column :misc, :integer
+  create_table :campaigns do |t|
+    t.integer :company_id
+    t.integer :medium, :misc, :Legacy
+  end
+  create_table :companies do |t|
+    t.string :name
   end
 end
 
+class Company < ActiveRecord::Base
+  has_many :campaigns
+end
+
 # Pseudo model for testing purposes
 class Campaign < ActiveRecord::Base
+  belongs_to :company
   bitmask :medium, :as => [:web, :print, :email, :phone]
   bitmask :misc, :as => %w(some useless values) do
     def worked?
       true
     end
   end
+  bitmask :Legacy, :as => [:upper, :case]
 end
 
 class Test::Unit::TestCase

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: bitmask-attribute
 version: !ruby/object:Gem::Version 
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors: 
 - Bruce Williams
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-12-14 00:00:00 -08:00
+date: 2009-12-15 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -37,8 +37,7 @@ files:
 - LICENSE
 - README.markdown
 - Rakefile
-- VERSION.yml
-- bitmask-attribute.gemspec
+- VERSION
 - lib/bitmask-attribute.rb
 - lib/bitmask_attribute.rb
 - lib/bitmask_attribute/value_proxy.rb

data/VERSION.yml

@@ -1,4 +0,0 @@
---- 
-:major: 1
-:minor: 0
-:patch: 0

data/bitmask-attribute.gemspec

@@ -1,50 +0,0 @@
-# -*- encoding: utf-8 -*-
-
-Gem::Specification.new do |s|
-  s.name = %q{bitmask-attribute}
-  s.version = "1.0.0"
-
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["Bruce Williams"]
-  s.date = %q{2009-05-18}
-  s.email = %q{bruce@codefluency.com}
-  s.extra_rdoc_files = [
-    "LICENSE",
-    "README.markdown"
-  ]
-  s.files = [
-    "LICENSE",
-    "README.markdown",
-    "Rakefile",
-    "VERSION.yml",
-    "lib/bitmask-attribute.rb",
-    "lib/bitmask_attribute.rb",
-    "lib/bitmask_attribute/value_proxy.rb",
-    "rails/init.rb",
-    "test/bitmask_attribute_test.rb",
-    "test/test_helper.rb"
-  ]
-  s.has_rdoc = true
-  s.homepage = %q{http://github.com/bruce/bitmask-attribute}
-  s.rdoc_options = ["--charset=UTF-8"]
-  s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.2}
-  s.summary = %q{Simple bitmask attribute support for ActiveRecord}
-  s.test_files = [
-    "test/bitmask_attribute_test.rb",
-    "test/test_helper.rb"
-  ]
-
-  if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
-    s.specification_version = 3
-
-    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<activerecord>, [">= 0"])
-    else
-      s.add_dependency(%q<activerecord>, [">= 0"])
-    end
-  else
-    s.add_dependency(%q<activerecord>, [">= 0"])
-  end
-end