clean-bitmask-attribute 2.0.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,121 @@
+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
+
+Or with a clean class:
+
+    class User
+      include BitmaskAttribute
+      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` with ActiveRecord:
+
+    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)
+* [Pavel Chipiga](http://github.com/chipiga)
+
+Copyright
+---------
+
+Copyright (c) 2007-2010 Bruce Williams. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,59 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "clean-bitmask-attribute"
+    gem.summary = %Q{Simple bitmask attribute support for any class}
+    gem.email = "pavel.chipiga@gmail.com"
+    gem.homepage = "http://github.com/chipiga/bitmask-attribute/tree/clean"
+    gem.authors = ["Pavel Chipiga", "Bruce Williams"]
+    gem.add_development_dependency 'activerecord'
+    gem.add_development_dependency 'sqlite3-ruby'
+    gem.add_development_dependency "shoulda"
+    # 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 @@
+2.0.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/attribute.rb

@@ -0,0 +1,25 @@
+module BitmaskAttribute
+  module Attribute
+    attr_accessor :attributes
+    
+    def initialize(attrs = {})
+      @attributes = {}
+      attrs.each do |k,v|
+        sym = :"#{k}="
+        if respond_to? sym
+          send sym, v
+        else
+          write_attribute(k, v)
+        end
+      end
+    end
+
+    def read_attribute(attr_name)
+      @attributes[attr_name.to_s]
+    end
+    
+    def write_attribute(attr_name, value)
+      @attributes[attr_name.to_s] = value
+    end
+  end
+end

data/lib/bitmask_attribute/core_ext/blank.rb

@@ -0,0 +1,77 @@
+# Extracted from Active Support
+class Object
+  # An object is blank if it's false, empty, or a whitespace string.
+  # For example, "", "   ", +nil+, [], and {} are blank.
+  #
+  # This simplifies:
+  #
+  #   if !address.nil? && !address.empty?
+  #
+  # ...to:
+  #
+  #   if !address.blank?
+  def blank?
+    respond_to?(:empty?) ? empty? : !self
+  end
+
+  # An object is present if it's not blank.
+  def present?
+    !blank?
+  end
+  
+  # Returns object if it's #present? otherwise returns nil.
+  # object.presence is equivalent to object.present? ? object : nil.
+  #
+  # This is handy for any representation of objects where blank is the same
+  # as not present at all.  For example, this simplifies a common check for
+  # HTTP POST/query parameters:
+  #
+  #   state   = params[:state]   if params[:state].present?
+  #   country = params[:country] if params[:country].present?
+  #   region  = state || country || 'US'
+  #
+  # ...becomes:
+  #
+  #   region = params[:state].presence || params[:country].presence || 'US'
+  def presence
+    self if present?
+  end
+end
+
+class NilClass #:nodoc:
+  def blank?
+    true
+  end
+end
+
+class FalseClass #:nodoc:
+  def blank?
+    true
+  end
+end
+
+class TrueClass #:nodoc:
+  def blank?
+    false
+  end
+end
+
+class Array #:nodoc:
+  alias_method :blank?, :empty?
+end
+
+class Hash #:nodoc:
+  alias_method :blank?, :empty?
+end
+
+class String #:nodoc:
+  def blank?
+    self !~ /\S/
+  end
+end
+
+class Numeric #:nodoc:
+  def blank?
+    false
+  end
+end

data/lib/bitmask_attribute/core_ext/hash_with_indifferent_access.rb

@@ -0,0 +1,182 @@
+# Extracted from Active Support
+class Hash
+  # Return a new hash with all keys converted to strings.
+  def stringify_keys
+    dup.stringify_keys!
+  end
+
+  # Destructively convert all keys to strings.
+  def stringify_keys!
+    keys.each do |key|
+      self[key.to_s] = delete(key)
+    end
+    self
+  end
+
+  # Return a new hash with all keys converted to symbols, as long as
+  # they respond to +to_sym+.
+  def symbolize_keys
+    dup.symbolize_keys!
+  end
+
+  # Destructively convert all keys to symbols, as long as they respond
+  # to +to_sym+.
+  def symbolize_keys!
+    keys.each do |key|
+      self[(key.to_sym rescue key) || key] = delete(key)
+    end
+    self
+  end
+
+  alias_method :to_options,  :symbolize_keys
+  alias_method :to_options!, :symbolize_keys!
+
+  # Validate all keys in a hash match *valid keys, raising ArgumentError on a mismatch.
+  # Note that keys are NOT treated indifferently, meaning if you use strings for keys but assert symbols
+  # as keys, this will fail.
+  #
+  # ==== Examples
+  #   { :name => "Rob", :years => "28" }.assert_valid_keys(:name, :age) # => raises "ArgumentError: Unknown key(s): years"
+  #   { :name => "Rob", :age => "28" }.assert_valid_keys("name", "age") # => raises "ArgumentError: Unknown key(s): name, age"
+  #   { :name => "Rob", :age => "28" }.assert_valid_keys(:name, :age) # => passes, raises nothing
+  def assert_valid_keys(*valid_keys)
+    unknown_keys = keys - [valid_keys].flatten
+    raise(ArgumentError, "Unknown key(s): #{unknown_keys.join(", ")}") unless unknown_keys.empty?
+  end
+end
+
+class HashWithIndifferentAccess < Hash
+  def extractable_options?
+    true
+  end
+
+  def initialize(constructor = {})
+    if constructor.is_a?(Hash)
+      super()
+      update(constructor)
+    else
+      super(constructor)
+    end
+  end
+
+  def default(key = nil)
+    if key.is_a?(Symbol) && include?(key = key.to_s)
+      self[key]
+    else
+      super
+    end
+  end
+
+  alias_method :regular_writer, :[]= unless method_defined?(:regular_writer)
+  alias_method :regular_update, :update unless method_defined?(:regular_update)
+
+  # Assigns a new value to the hash:
+  #
+  #   hash = HashWithIndifferentAccess.new
+  #   hash[:key] = "value"
+  #
+  def []=(key, value)
+    regular_writer(convert_key(key), convert_value(value))
+  end
+
+  # Updates the instantized hash with values from the second:
+  #
+  #   hash_1 = HashWithIndifferentAccess.new
+  #   hash_1[:key] = "value"
+  #
+  #   hash_2 = HashWithIndifferentAccess.new
+  #   hash_2[:key] = "New Value!"
+  #
+  #   hash_1.update(hash_2) # => {"key"=>"New Value!"}
+  #
+  def update(other_hash)
+    other_hash.each_pair { |key, value| regular_writer(convert_key(key), convert_value(value)) }
+    self
+  end
+
+  alias_method :merge!, :update
+
+  # Checks the hash for a key matching the argument passed in:
+  #
+  #   hash = HashWithIndifferentAccess.new
+  #   hash["key"] = "value"
+  #   hash.key? :key  # => true
+  #   hash.key? "key" # => true
+  #
+  def key?(key)
+    super(convert_key(key))
+  end
+
+  alias_method :include?, :key?
+  alias_method :has_key?, :key?
+  alias_method :member?, :key?
+
+  # Fetches the value for the specified key, same as doing hash[key]
+  def fetch(key, *extras)
+    super(convert_key(key), *extras)
+  end
+
+  # Returns an array of the values at the specified indices:
+  #
+  #   hash = HashWithIndifferentAccess.new
+  #   hash[:a] = "x"
+  #   hash[:b] = "y"
+  #   hash.values_at("a", "b") # => ["x", "y"]
+  #
+  def values_at(*indices)
+    indices.collect {|key| self[convert_key(key)]}
+  end
+
+  # Returns an exact copy of the hash.
+  def dup
+    HashWithIndifferentAccess.new(self)
+  end
+
+  # Merges the instantized and the specified hashes together, giving precedence to the values from the second hash
+  # Does not overwrite the existing hash.
+  def merge(hash)
+    self.dup.update(hash)
+  end
+
+  # Performs the opposite of merge, with the keys and values from the first hash taking precedence over the second.
+  # This overloaded definition prevents returning a regular hash, if reverse_merge is called on a HashWithDifferentAccess.
+  def reverse_merge(other_hash)
+    super other_hash.with_indifferent_access
+  end
+
+  def reverse_merge!(other_hash)
+    replace(reverse_merge( other_hash ))
+  end
+
+  # Removes a specified key from the hash.
+  def delete(key)
+    super(convert_key(key))
+  end
+
+  def stringify_keys!; self end
+  def stringify_keys; dup end
+  undef :symbolize_keys!
+  def symbolize_keys; to_hash.symbolize_keys end
+  def to_options!; self end
+
+  # Convert to a Hash with String keys.
+  def to_hash
+    Hash.new(default).merge!(self)
+  end
+
+  protected
+    def convert_key(key)
+      key.kind_of?(Symbol) ? key.to_s : key
+    end
+
+    def convert_value(value)
+      case value
+      when Hash
+        value.with_indifferent_access
+      when Array
+        value.collect { |e| e.is_a?(Hash) ? e.with_indifferent_access : e }
+      else
+        value
+      end
+    end
+end

data/lib/bitmask_attribute/core_ext/returning.rb

@@ -0,0 +1,43 @@
+# Extracted from Active Support
+class Object
+  # Returns +value+ after yielding +value+ to the block. This simplifies the
+  # process of constructing an object, performing work on the object, and then
+  # returning the object from a method. It is a Ruby-ized realization of the K
+  # combinator, courtesy of Mikael Brockman.
+  #
+  # ==== Examples
+  #
+  #  # Without returning
+  #  def foo
+  #    values = []
+  #    values << "bar"
+  #    values << "baz"
+  #    return values
+  #  end
+  #
+  #  foo # => ['bar', 'baz']
+  #
+  #  # returning with a local variable
+  #  def foo
+  #    returning values = [] do
+  #      values << 'bar'
+  #      values << 'baz'
+  #    end
+  #  end
+  #
+  #  foo # => ['bar', 'baz']
+  #
+  #  # returning with a block argument
+  #  def foo
+  #    returning [] do |values|
+  #      values << 'bar'
+  #      values << 'baz'
+  #    end
+  #  end
+  #
+  #  foo # => ['bar', 'baz']
+  def returning(value)
+    yield(value)
+    value
+  end
+end

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