bitfields 0.1.0

data/README.markdown

@@ -0,0 +1,45 @@
+Save migrations and columns by storing multiple booleans in a single integer.  
+e.g. 3 = 1->true 2->true 4->false, 4 = 1->false 2->false 4->true, 5 = 1->true 2->false 4->true
+
+    class User < ActiveRecord::Base
+      include Bitfields
+      bitfield :my_bits, 1 => :seller, 2 => :insane, 4 => :stupid
+    end
+
+    user = User.new(:seller => true, :insane => true)
+    user.seller == true
+    user.stupid? == false
+    user.my_bits == 9
+
+ - records changes `user.chamges == {:seller => [false, true]}`
+ - adds scopes `User.seller.stupid.first` (deactivate with `bitfield ..., :scopes => false`)
+ - builds sql `User.bitfield_sql(:insane => true, :stupid => false) == 'users.my_bits IN (2, 3)'` (2 and 1+2)
+ - builds not-index-using sql with `bitfield ... ,:query_mode => :bit_operator` and `User.bitfield_sql(:insane => true, :stupid => false) == '(users.my_bits & 3) = 1'`, always slower than IN() sql, since it will not use an existing index (tested for up to 64 values)
+ - builds update sql `User.set_bitfield_sql(:insane => true, :stupid => false) == 'my_bits = (my_bits | 6) - 4'`
+ - gives access to bits `User.bitfields[:my_bits][:stupid] == 4`
+
+Install
+=======
+As Gem: ` sudo gem install bitfields `  
+Or as Rails plugin: ` script/plugins install git://github.com/grosser/bitfields.git `
+
+### Migration
+ALWAYS set a default, bitfield queries will not work for NULL
+    t.integer :my_bits, :default => 0, :null => false
+    OR
+    add_column :users, :my_bits, :integer, :default => 0, :null => false
+
+Usage
+=====
+
+    # update all users
+    User.seller.not_stupid.update_all(User.set_bitfield_sql(:seller => true, :insane => true))
+
+    # delete the shop when a user is no longer a seller
+    before_save :delete_shop, :if => lambda{|u| u.changes['seller'] == [true, false]}
+
+Author
+======
+[Michael Grosser](http://pragmatig.wordpress.com)  
+grosser.michael@gmail.com  
+Hereby placed under public domain, do what you want, just do not hold me accountable...

data/Rakefile

@@ -0,0 +1,19 @@
+task :default => :spec
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new {|t| t.spec_opts = ['--color']}
+
+begin
+  require 'jeweler'
+  project_name = 'bitfields'
+  Jeweler::Tasks.new do |gem|
+    gem.name = project_name
+    gem.summary = "Save migrations and columns by storing multiple booleans in a single integer."
+    gem.email = "grosser.michael@gmail.com"
+    gem.homepage = "http://github.com/grosser/#{project_name}"
+    gem.authors = ["Michael Grosser"]
+  end
+
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler, or one of its dependencies, is not available. Install it with: sudo gem install jeweler"
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/bitfields.rb

@@ -0,0 +1,139 @@
+require 'active_support'
+
+module Bitfields
+  VERSION = File.read( File.join(File.dirname(__FILE__),'..','VERSION') ).strip
+  TRUE_VALUES = [true, 1, '1', 't', 'T', 'true', 'TRUE'] # taken from ActiveRecord::ConnectionAdapters::Column
+
+  def self.included(base)
+    base.class_inheritable_accessor :bitfields, :bitfield_options
+    base.extend Bitfields::ClassMethods
+  end
+
+  def self.extract_bits(options)
+    bitfields = {}
+    options.keys.select{|key| key.is_a?(Numeric) }.each do |bit|
+      bit_name = options.delete(bit).to_sym
+      bitfields[bit_name] = bit
+    end
+    bitfields
+  end
+
+  module ClassMethods
+    def bitfield(column, options)
+      # prepare ...
+      column = column.to_sym
+      options = options.dup # since we will modify them...
+
+      # extract options
+      self.bitfields ||= {}
+      self.bitfield_options ||= {}
+      bitfields[column] = Bitfields.extract_bits(options)
+      bitfield_options[column] = options
+
+      # add instance methods and scopes
+      bitfields[column].keys.each do |bit_name|
+        define_method(bit_name){ bitfield_value(bit_name) }
+        define_method("#{bit_name}?"){ bitfield_value(bit_name) }
+        define_method("#{bit_name}="){|value| set_bitfield_value(bit_name, value) }
+        if options[:scopes] != false
+          scoping_method = (respond_to?(:scope) ? :scope : :named_scope) # AR 3.0+ uses scope
+          send scoping_method, bit_name, :conditions => bitfield_sql(bit_name => true)
+          send scoping_method, "not_#{bit_name}", :conditions => bitfield_sql(bit_name => false)
+        end
+      end
+
+      include Bitfields::InstanceMethods
+    end
+
+    def bitfield_column(bit_name)
+      bitfields.detect{|c, bits| bits.keys.include?(bit_name.to_sym) }.first
+    end
+
+    def bitfield_sql(bit_values)
+      bits = group_bits_by_column(bit_values)
+      bits.map{|column, bit_values| bitfield_sql_by_column(column, bit_values) } * ' AND '
+    end
+
+    def set_bitfield_sql(bit_values)
+      columns = group_bits_by_column(bit_values)
+      columns.map{|column, bit_values| set_bitfield_sql_by_column(column, bit_values) } * ', '
+    end
+
+    private
+
+    def bitfield_sql_by_column(column, bit_values)
+      mode = (bitfield_options[column][:query_mode] || :in_list)
+      case mode
+      when :in_list then
+        max = (bitfields[column].values.max * 2) - 1
+        bits = (0..max).to_a # all possible bits
+        bit_values.each do |bit_name, value|
+          bit = bitfields[column][bit_name]
+          # reject values with: bit off for true, bit on for false
+          bits.reject!{|i| i & bit == (value ? 0 : bit) }
+        end
+        "#{table_name}.#{column} IN (#{bits * ','})"
+      when :bit_operator
+        on, off = bit_values_to_on_off(column, bit_values)
+        "(#{table_name}.#{column} & #{on+off}) = #{on}"
+      else raise("bitfields: unknown query mode #{mode.inspect}")
+      end
+    end
+
+    def set_bitfield_sql_by_column(column, bit_values)
+      on, off = bit_values_to_on_off(column, bit_values)
+      "#{column} = (#{column} | #{on+off}) - #{off}"
+    end
+
+    def group_bits_by_column(bit_values)
+      columns = {}
+      bit_values.each do |bit_name, value|
+        column = bitfield_column(bit_name.to_sym)
+        columns[column] ||= {}
+        columns[column][bit_name.to_sym] = value
+      end
+      columns
+    end
+
+    def bit_values_to_on_off(column, bit_values)
+      on = off = 0
+      bit_values.each do |bit_name, value|
+        bit = bitfields[column][bit_name]
+        value ? on += bit : off += bit
+      end
+      [on, off]
+    end
+  end
+
+  module InstanceMethods
+    private
+    def bitfield_value(bit_name)
+      column, bit, current_value = bitfield_info(bit_name)
+      current_value & bit != 0
+    end
+
+    def set_bitfield_value(bit_name, value)
+      column, bit, current_value = bitfield_info(bit_name)
+      new_value = TRUE_VALUES.include?(value)
+      old_value = bitfield_value(bit_name)
+      return if new_value == old_value
+
+      if defined? changed_attributes
+        send(:changed_attributes).merge!(bit_name.to_s => old_value)
+      end
+
+      # 8 + 1 == 9 // 8 + 8 == 8 // 1 - 8 == 1 // 8 - 8 == 0
+      new_bits = if new_value then current_value | bit else (current_value | bit) - bit end
+      send("#{column}=", new_bits)
+    end
+
+    def bitfield_info(bit_name)
+      column = self.class.bitfield_column(bit_name)
+      [
+        column,
+        self.class.bitfields[column][bit_name], # bit
+        (send(column)||0) # current value
+      ]
+    end
+  end
+end

data/spec/bitfields_spec.rb

@@ -0,0 +1,277 @@
+require 'spec/spec_helper'
+
+class User < ActiveRecord::Base
+  include Bitfields
+  bitfield :bits, 1 => :seller, 2 => :insane, 4 => :stupid
+end
+
+class UserWithBitfieldOptions < ActiveRecord::Base
+  include Bitfields
+  bitfield :bits, 1 => :seller, 2 => :insane, 4 => :stupid, :scopes => false
+end
+
+class MultiBitUser < ActiveRecord::Base
+  set_table_name 'users'
+  include Bitfields
+  bitfield :bits, 1 => :seller, 2 => :insane, 4 => :stupid
+  bitfield :more_bits, 1 => :one, 2 => :two, 4 => :four
+end
+
+class UserWithoutScopes < ActiveRecord::Base
+  set_table_name 'users'
+  include Bitfields
+  bitfield :bits, 1 => :seller, 2 => :insane, 4 => :stupid, :scopes => false
+end
+
+class InheritedUser < User
+end
+
+class OverwrittenUser < User
+  bitfield :bits, 1 => :seller_inherited
+end
+
+class BitOperatorMode < ActiveRecord::Base
+  set_table_name 'users'
+  include Bitfields
+  bitfield :bits, 1 => :seller, 2 => :insane, :query_mode => :bit_operator
+end
+
+describe Bitfields do
+  before do
+    User.delete_all
+  end
+
+  describe :bitfields do
+    it "parses them correctly" do
+      User.bitfields.should == {:bits => {:seller => 1, :insane => 2, :stupid => 4}}
+    end
+  end
+
+  describe :bitfield_options do
+    it "parses them correctly when not set" do
+      User.bitfield_options.should == {:bits => {}}
+    end
+
+    it "parses them correctly when set" do
+      UserWithBitfieldOptions.bitfield_options.should == {:bits => {:scopes => false}}
+    end
+  end
+
+  describe 'attribute accessors' do
+    it "has everything on false by default" do
+      User.new.seller.should == false
+      User.new.seller?.should == false
+    end
+
+    it "is true when set to true" do
+      User.new(:seller => true).seller.should == true
+    end
+
+    it "is true when set to truthy" do
+      User.new(:seller => 1).seller.should == true
+    end
+
+    it "is false when set to false" do
+      User.new(:seller => false).seller.should == false
+    end
+
+    it "is false when set to falsy" do
+      User.new(:seller => 'false').seller.should == false
+    end
+
+    it "stays true when set to true twice" do
+      u = User.new
+      u.seller = true
+      u.seller = true
+      u.seller.should == true
+      u.bits.should == 1
+    end
+
+    it "stays false when set to false twice" do
+      u = User.new(:bits => 3)
+      u.seller = false
+      u.seller = false
+      u.seller.should == false
+      u.bits.should == 2
+    end
+
+    it "changes the bits when setting to false" do
+      user = User.new(:bits => 7)
+      user.seller = false
+      user.bits.should == 6
+    end
+
+    it "does not get negative when unsetting high bits" do
+      user = User.new(:seller => true)
+      user.stupid = false
+      user.bits.should == 1
+    end
+
+    it "changes the bits when setting to true" do
+      user = User.new(:bits => 2)
+      user.seller = true
+      user.bits.should == 3
+    end
+
+    it "does not get too high when setting high bits" do
+      user = User.new(:bits => 7)
+      user.seller = true
+      user.bits.should == 7
+    end
+
+    describe 'changes' do
+      it "has no changes by defaut" do
+        User.new.changes.should == {}
+      end
+
+      it "records a change when setting" do
+        User.new(:seller => true).changes.should == {'seller' => [false, true], 'bits' => [0,1]}
+      end
+
+      it "records a change when unsetting" do
+        u = User.create!(:seller => true)
+        u.seller = false
+        u.changes.should == {'seller' => [true, false], 'bits' => [1,0]}
+      end
+
+      it "does not track duplicate changes" do
+        User.create!(:seller => false).changes.should == {}
+      end
+    end
+  end
+
+  describe :bitfield_sql do
+    it "includes true states" do
+      User.bitfield_sql(:insane => true).should == 'users.bits IN (2,3,6,7)' # 2, 1+2, 2+4, 1+2+4
+    end
+
+    it "includes invalid states" do
+      User.bitfield_sql(:insane => false).should == 'users.bits IN (0,1,4,5)' # 0, 1, 4, 4+1
+    end
+
+    it "can combine multiple fields" do
+      User.bitfield_sql(:seller => true, :insane => true).should == 'users.bits IN (3,7)' # 1+2, 1+2+4
+    end
+
+    it "can combine multiple fields with different values" do
+      User.bitfield_sql(:seller => true, :insane => false).should == 'users.bits IN (1,5)' # 1, 1+4
+    end
+
+    it "combines multiple columns into one sql" do
+      sql = MultiBitUser.bitfield_sql(:seller => true, :insane => false, :one => true, :four => true)
+      sql.should == 'users.bits IN (1,5) AND users.more_bits IN (5,7)' # 1, 1+4 AND 1+4, 1+2+4
+    end
+
+    it "produces working sql" do
+      u1 = MultiBitUser.create!(:seller => true, :one => true)
+      u2 = MultiBitUser.create!(:seller => true, :one => false)
+      u3 = MultiBitUser.create!(:seller => false, :one => false)
+      MultiBitUser.all(:conditions => MultiBitUser.bitfield_sql(:seller => true, :one => false)).should == [u2]
+    end
+
+    describe 'with bit operator mode' do
+      it "generates bit-operator sql" do
+        BitOperatorMode.bitfield_sql(:seller => true).should == '(users.bits & 1) = 1'
+      end
+
+      it "generates sql for each bit" do
+        BitOperatorMode.bitfield_sql(:seller => true, :insane => false).should == '(users.bits & 3) = 1'
+      end
+
+      it "generates working sql" do
+        u1 = BitOperatorMode.create!(:seller => true, :insane => true)
+        u2 = BitOperatorMode.create!(:seller => true, :insane => false)
+        u3 = BitOperatorMode.create!(:seller => false, :insane => false)
+        BitOperatorMode.all(:conditions => MultiBitUser.bitfield_sql(:seller => true, :insane => false)).should == [u2]
+      end
+    end
+  end
+
+  describe :set_bitfield_sql do
+    it "sets a single bit" do
+      User.set_bitfield_sql(:seller => true).should == 'bits = (bits | 1) - 0'
+    end
+
+    it "unsets a single bit" do
+      User.set_bitfield_sql(:seller => false).should == 'bits = (bits | 1) - 1'
+    end
+
+    it "sets multiple bits" do
+      User.set_bitfield_sql(:seller => true, :insane => true).should == 'bits = (bits | 3) - 0'
+    end
+
+    it "unsets multiple bits" do
+      User.set_bitfield_sql(:seller => false, :insane => false).should == 'bits = (bits | 3) - 3'
+    end
+
+    it "sets and unsets in one command" do
+      User.set_bitfield_sql(:seller => false, :insane => true).should == 'bits = (bits | 3) - 1'
+    end
+
+    it "sets and unsets for multiple columns in one sql" do
+      sql = MultiBitUser.set_bitfield_sql(:seller => false, :insane => true, :one => true, :two => false)
+      sql.should == "bits = (bits | 3) - 1, more_bits = (more_bits | 3) - 2"
+    end
+
+    it "produces working sql" do
+      u = MultiBitUser.create!(:seller => true, :insane => true, :stupid => false, :one => true, :two => false, :four => false)
+      sql = MultiBitUser.set_bitfield_sql(:seller => false, :insane => true, :one => true, :two => false)
+      MultiBitUser.update_all(sql)
+      u.reload
+      u.seller.should == false
+      u.insane.should == true
+      u.stupid.should == false
+      u.one.should == true
+      u.two.should == false
+      u.four.should == false
+    end
+  end
+
+  describe 'named scopes' do
+    before do
+      @u1 = User.create!(:seller => true, :insane => false)
+      @u2 = User.create!(:seller => true, :insane => true)
+    end
+
+    it "creates them when nothing was passed" do
+      User.respond_to?(:seller).should == true
+      User.respond_to?(:not_seller).should == true
+    end
+
+    it "does not create them when false was passed" do
+      UserWithoutScopes.respond_to?(:seller).should == false
+      UserWithoutScopes.respond_to?(:not_seller).should == false
+    end
+
+    it "produces working positive scopes" do
+      User.insane.seller.to_a.should == [@u2]
+    end
+
+    it "produces working negative scopes" do
+      User.not_insane.seller.to_a.should == [@u1]
+    end
+  end
+
+  describe 'overwriting' do
+    it "does not change base class" do
+      OverwrittenUser.bitfields[:bits][:seller_inherited].should_not == nil
+      User.bitfields[:bits][:seller_inherited].should == nil
+    end
+
+    it "has inherited methods" do
+      User.respond_to?(:seller).should == true
+      OverwrittenUser.respond_to?(:seller).should == true
+    end
+
+    it "knows inherited values" do
+      pending
+      OverwrittenUser.bitfield_column(:seller).should == :bits
+    end
+  end
+
+  describe 'inheritance' do
+    it "knows inherited values" do
+      InheritedUser.bitfield_column(:seller).should == :bits
+    end
+  end
+end

data/spec/database.rb

@@ -0,0 +1,15 @@
+require 'active_record'
+
+# connect
+ActiveRecord::Base.establish_connection(
+  :adapter => "sqlite3",
+  :database => ":memory:"
+)
+
+# create tables
+ActiveRecord::Schema.define(:version => 1) do
+  create_table :users do |t|
+    t.integer :bits, :default => 0, :null => false
+    t.integer :more_bits, :default => 0, :null => false
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,4 @@
+require 'rubygems'
+$LOAD_PATH << 'lib'
+require 'bitfields'
+require 'spec/database'

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification 
+name: bitfields
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Michael Grosser
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-03-06 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: 
+email: grosser.michael@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.markdown
+files: 
+- README.markdown
+- Rakefile
+- VERSION
+- lib/bitfields.rb
+- spec/bitfields_spec.rb
+- spec/database.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/grosser/bitfields
+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: Save migrations and columns by storing multiple booleans in a single integer.
+test_files: 
+- spec/spec_helper.rb
+- spec/bitfields_spec.rb
+- spec/database.rb