r3trofitted-bitmask-attribute 1.1.0

data/.document

@@ -0,0 +1,5 @@
+README.markdown
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,7 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg
+\#*
+.#*

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2007-2009 Bruce Williams
+
+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.markdown

@@ -0,0 +1,113 @@
+bitmask-attribute
+=================
+
+Transparent manipulation of bitmask attributes.
+
+Example
+-------
+
+Simply declare an existing integer column as a bitmask with its possible
+values.
+
+    class User < ActiveRecord::Base
+      bitmask :roles, :as => [:writer, :publisher, :editor, :proofreader] 
+    end
+    
+You can then modify the column using the declared values without resorting
+to manual bitmasks.
+    
+    user = User.create(:name => "Bruce", :roles => [:publisher, :editor])
+    user.roles
+    # => [:publisher, :editor]
+    user.roles << :writer
+    user.roles
+    # => [:publisher, :editor, :writer]
+    
+It's easy to find out if a record has a given value:
+
+    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)
+
+Later we'll support finding records without a specific bitmask.
+
+Adding Methods
+--------------
+
+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
+
+Credits
+-------
+
+Thanks to the following contributors:
+
+* [Jason L Perry](http://github.com/ambethia)
+* [Nicolas Fouché](http://github.com/nfo)
+
+Copyright
+---------
+
+Copyright (c) 2007-2009 Bruce Williams. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,57 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "bitmask-attribute"
+    gem.summary = %Q{Simple bitmask attribute support for ActiveRecord}
+    gem.email = "bruce@codefluency.com"
+    gem.homepage = "http://github.com/bruce/bitmask-attribute"
+    gem.authors = ["Bruce Williams"]
+    gem.add_dependency 'activerecord'
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "bitmask-attribute #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+

data/VERSION

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

data/lib/bitmask-attribute.rb

@@ -0,0 +1,2 @@
+# Stub for dash-style requires
+require File.dirname(__FILE__) << "/bitmask_attribute"

data/lib/bitmask_attribute/value_proxy.rb

@@ -0,0 +1,77 @@
+module BitmaskAttribute
+
+  class ValueProxy < Array
+      
+    def initialize(record, attribute, &extension)
+      @record = record
+      @attribute = attribute
+      find_mapping
+      instance_eval(&extension) if extension
+      super(extract_values)
+    end
+    
+    # =========================
+    # = OVERRIDE TO SERIALIZE =
+    # =========================
+    
+    %w(push << delete replace reject! select!).each do |override|
+      class_eval(<<-EOEVAL)
+        def #{override}(*args)
+          returning(super) do
+            updated!
+          end
+        end
+      EOEVAL
+    end
+    
+    def to_i
+      inject(0) { |memo, value| memo | @mapping[value] }
+    end
+  
+    #######
+    private
+    #######
+    
+    def validate!
+      each do |value|
+        if @mapping.key? value
+          true
+        else
+          raise ArgumentError, "Unsupported value for `#{@attribute}': #{value.inspect}"
+        end
+      end
+    end
+    
+    def symbolize!
+      map!(&:to_sym)
+    end
+    
+    def updated!
+      symbolize!
+      validate!
+      uniq!
+      serialize!
+    end
+    
+    def serialize!
+      @record.send(:write_attribute, @attribute, to_i)
+    end
+  
+    def extract_values
+      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)
+        end
+      end        
+    end
+    
+    def find_mapping
+      unless (@mapping = @record.class.bitmasks[@attribute])
+        raise ArgumentError, "Could not find mapping for bitmask attribute :#{@attribute}"
+      end
+    end
+      
+  end
+
+end

data/lib/bitmask_attribute.rb

@@ -0,0 +1,154 @@
+require 'bitmask_attribute/value_proxy'
+
+module BitmaskAttribute
+  
+  class Definition
+    
+    attr_reader :attribute, :values, :extension
+    def initialize(attribute, values=[], &extension)
+      @attribute = attribute
+      @values = values
+      @extension = extension
+    end
+    
+    def install_on(model)
+      validate_for model
+      generate_bitmasks_on model
+      override model
+      create_convenience_class_method_on(model)
+      create_convenience_instance_methods_on(model)
+      create_named_scopes_on(model)
+    end
+    
+    #######
+    private
+    #######
+
+    def validate_for(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
+    
+    def generate_bitmasks_on(model)
+      model.bitmasks[attribute] = returning HashWithIndifferentAccess.new do |mapping|
+        values.each_with_index do |value, index|
+          mapping[value] = 0b1 << index
+        end
+      end
+    end
+    
+    def override(model)
+      override_getter_on(model)
+      override_setter_on(model)
+    end
+    
+    def override_getter_on(model)
+      model.class_eval %(
+        def #{attribute}
+          @#{attribute} ||= BitmaskAttribute::ValueProxy.new(self, :#{attribute}, &self.class.bitmask_definitions[:#{attribute}].extension)
+        end
+      )
+    end
+    
+    def override_setter_on(model)
+      model.class_eval %(
+        def #{attribute}=(raw_value)
+          values = raw_value.kind_of?(Array) ? raw_value : [raw_value]
+          self.#{attribute}.replace(values.reject(&:blank?))
+        end
+      )
+    end
+    
+    def create_convenience_class_method_on(model)
+      model.class_eval %(
+        def self.bitmask_for_#{attribute}(*values)
+          values.inject(0) do |bitmask, value|
+            unless (bit = bitmasks[:#{attribute}][value])
+              raise ArgumentError, "Unsupported value for #{attribute}: \#{value.inspect}"
+            end
+            bitmask | bit
+          end
+        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
+  
+  def self.included(model)
+    model.extend ClassMethods
+  end
+    
+  module ClassMethods
+    
+    def bitmask(attribute, options={}, &extension)
+      unless options[:as] && options[:as].kind_of?(Array)
+        raise ArgumentError, "Must provide an Array :as option"
+      end
+      bitmask_definitions[attribute] = BitmaskAttribute::Definition.new(attribute, options[:as].to_a, &extension)
+      bitmask_definitions[attribute].install_on(self)
+    end
+    
+    def bitmask_definitions
+      @bitmask_definitions ||= {}
+    end
+    
+    def bitmasks
+      @bitmasks ||= {}
+    end
+      
+  end
+  
+end

data/rails/init.rb

@@ -0,0 +1,3 @@
+ActiveRecord::Base.instance_eval do
+  include BitmaskAttribute
+end

data/test/bitmask_attribute_test.rb

@@ -0,0 +1,222 @@
+require 'test_helper'
+
+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
+
+    should "can assign multiple values to bitmask" do
+      assert_stored Campaign.new(:medium => [:web, :print]), :web, :print
+    end
+
+    should "can add single value to bitmask" do
+      campaign = Campaign.new(:medium => [:web, :print])
+      assert_stored campaign, :web, :print
+      campaign.medium << :phone
+      assert_stored campaign, :web, :print, :phone
+    end
+
+    should "ignores duplicate values added to bitmask" do
+      campaign = Campaign.new(:medium => [:web, :print])
+      assert_stored campaign, :web, :print
+      campaign.medium << :phone
+      assert_stored campaign, :web, :print, :phone
+      campaign.medium << :phone
+      assert_stored campaign, :web, :print, :phone
+      assert_equal 1, campaign.medium.select { |value| value == :phone }.size
+    end
+
+    should "can assign new values at once to bitmask" do
+      campaign = Campaign.new(:medium => [:web, :print])
+      assert_stored campaign, :web, :print
+      campaign.medium = [:phone, :email]
+      assert_stored campaign, :phone, :email
+    end
+
+    should "can save bitmask to db and retrieve values transparently" do
+      campaign = Campaign.new(:medium => [:web, :print])
+      assert_stored campaign, :web, :print
+      assert campaign.save
+      assert_stored Campaign.find(campaign.id), :web, :print
+    end
+
+    should "can add custom behavor to value proxies during bitmask definition" do
+      campaign = Campaign.new(:medium => [:web, :print])
+      assert_raises NoMethodError do
+        campaign.medium.worked?
+      end
+      assert_nothing_raised do
+        campaign.misc.worked?
+      end
+      assert campaign.misc.worked?
+    end
+
+    should "cannot use unsupported values" do
+      assert_unsupported { Campaign.new(:medium => [:web, :print, :this_will_fail]) }
+      campaign = Campaign.new(:medium => :web)
+      assert_unsupported { campaign.medium << :this_will_fail_also }
+      assert_unsupported { campaign.medium = [:so_will_this] }
+    end
+
+    should "can determine bitmasks using convenience method" do
+      assert Campaign.bitmask_for_medium(:web, :print)
+      assert_equal(
+        Campaign.bitmasks[:medium][:web] | Campaign.bitmasks[:medium][:print],
+        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
+
+    should "hash of values is with indifferent access" do
+      string_bit = nil
+      assert_nothing_raised do
+        assert (string_bit = Campaign.bitmask_for_medium('web', 'print'))
+      end
+      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
+    
+    should "convert values passed as strings to symbols" do
+      campaign = Campaign.new
+      campaign.medium << "web"
+      assert_equal [:web], campaign.medium
+    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
+    #######
+
+    def assert_unsupported(&block)
+      assert_raises(ArgumentError, &block)
+    end
+
+    def assert_stored(record, *values)
+      values.each do |value|
+        assert record.medium.any? { |v| v.to_s == value.to_s }, "Values #{record.medium.inspect} does not include #{value.inspect}"
+      end
+      full_mask = values.inject(0) do |mask, value|
+        mask | Campaign.bitmasks[:medium][value]
+      end
+      assert_equal full_mask, record.medium.to_i
+    end
+
+  end
+
+end

data/test/test_helper.rb

@@ -0,0 +1,66 @@
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+begin
+  require 'redgreen'
+rescue LoadError
+end
+
+require 'active_support'
+require 'active_record'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$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 |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
+  
+  def assert_unsupported(&block)
+    assert_raises(ArgumentError, &block)
+  end
+  
+  def assert_stored(record, *values)
+    values.each do |value|
+      assert record.medium.any? { |v| v.to_s == value.to_s }, "Values #{record.medium.inspect} does not include #{value.inspect}"
+    end
+    full_mask = values.inject(0) do |mask, value|
+      mask | Campaign.bitmasks[:medium][value]
+    end
+    assert_equal full_mask, record.medium.to_i
+  end
+  
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification 
+name: r3trofitted-bitmask-attribute
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 1
+  - 1
+  - 0
+  version: 1.1.0
+platform: ruby
+authors: 
+- Bruce Williams
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-05-12 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+description: 
+email: bruce@codefluency.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.markdown
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.markdown
+- Rakefile
+- VERSION
+- 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
+has_rdoc: true
+homepage: http://github.com/bruce/bitmask-attribute
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Simple bitmask attribute support for ActiveRecord
+test_files: 
+- test/bitmask_attribute_test.rb
+- test/test_helper.rb