bruce-bitmask-attribute 1.0.0

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,47 @@
+# 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] 
+    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]
+    
+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:
+
+    bitmask = User.bitmasks[:roles][:editor]
+    # Use `bitmask` as needed
+
+## Modifying possible values
+
+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.
+
+## 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
+
+## Copyright
+
+Copyright (c) 2007-2009 Bruce Williams. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,56 @@
+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
+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.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 1
+:minor: 0
+:patch: 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.rb

@@ -0,0 +1,100 @@
+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_method_on model
+    end
+    
+    #######
+    private
+    #######
+
+    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}'"
+      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(<<-EVAL)
+        def #{attribute}
+          @#{attribute} ||= BitmaskAttribute::ValueProxy.new(self, :#{attribute}, &self.class.bitmask_definitions[:#{attribute}].extension)
+        end
+      EVAL
+    end
+    
+    def override_setter_on(model)
+      model.class_eval(<<-EVAL)
+        def #{attribute}=(raw_value)
+          values = raw_value.kind_of?(Array) ? raw_value : [raw_value]
+          #{attribute}.replace(values)
+        end
+      EVAL
+    end
+    
+    def create_convenience_method_on(model)
+      model.class_eval(<<-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
+      EVAL
+    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/lib/bitmask_attribute/value_proxy.rb

@@ -0,0 +1,72 @@
+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 updated!
+      validate!
+      uniq!
+      serialize!
+    end
+    
+    def serialize!
+      @record.send(:write_attribute, @attribute, to_i)
+    end
+  
+    def extract_values
+      stored = @record.send(:read_attribute, @attribute) || 0
+      @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/rails/init.rb

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

data/test/bitmask_attribute_test.rb

@@ -0,0 +1,104 @@
+require 'test_helper'
+
+class BitmaskAttributeTest < Test::Unit::TestCase
+  
+  context "Campaign" do
+
+    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
+
+    #######
+    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,55 @@
+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.establish_connection(
+  :adapter  => 'sqlite3',
+  :database => ':memory:'
+)
+
+ActiveRecord::Schema.define do 
+  create_table :campaigns do |table|
+    table.column :medium, :integer
+    table.column :misc, :integer
+  end
+end
+
+# Pseudo model for testing purposes
+class Campaign < ActiveRecord::Base
+  bitmask :medium, :as => [:web, :print, :email, :phone]
+  bitmask :misc, :as => %w(some useless values) do
+    def worked?
+      true
+    end
+  end
+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,73 @@
+--- !ruby/object:Gem::Specification 
+name: bruce-bitmask-attribute
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+platform: ruby
+authors: 
+- Bruce Williams
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-05-18 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: 
+email: bruce@codefluency.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.markdown
+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
+has_rdoc: true
+homepage: http://github.com/bruce/bitmask-attribute
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 3
+summary: Simple bitmask attribute support for ActiveRecord
+test_files: 
+- test/bitmask_attribute_test.rb
+- test/test_helper.rb