bit_magic 0.1.1

data/lib/bit_magic/adapters/magician.rb

@@ -0,0 +1,226 @@
+module BitMagic
+  module Adapters
+    # A container for bit_magic settings and fields
+    # Meant to be used internally by the Base adapter (and by extension, all adapters).
+    #
+    # @attr_reader [Hash] field_options bit_magic options that define fields
+    # @attr_reader [Hash] action_options bit_magic options that define settings
+    # @attr_reader [Hash] field_list name => bits key pairs based off field_options
+    # @attr_reader [Integer] bits_length total number of bits defined in field_options
+    # @attr_reader [Integer] max_bit the largest bit defined in field_options
+    # @attr_reader [Symbol] bit_magic_name the name given to bit_magic
+    class Magician
+      
+      DEFAULT_ACTION_OPTIONS = Bits::DEFAULT_OPTIONS.merge({
+        :query_by_value => true, # can be true, false, or a number of bits
+        :helpers => true, # TODO: enable deeper access control over injected helper methods
+        :bits_wrapper => Bits,
+        :bits_generator => BitsGenerator,
+        }).freeze
+      
+      # Checks if the key is a a field key definition (Integer or Range, defining
+      # bit or bit ranges in question).
+      #
+      # @param [Integer, Range<Integer>] checkValue an integer bit or bit range
+      #   to check if it is a valid bit index
+      #
+      # @return [Integer, Array<Integer>] will return an integer or an array of
+      #   integers if the checkValue is a valid bit index or bit range
+      def self.field_key_value_check(check)
+        if check.is_a?(Integer)
+          check
+        elsif check.is_a?(Range)
+          list = check.to_a
+          valid = list.reduce(true) {|m, i| m && i.is_a?(Integer) }
+          list if valid and list.length > 0
+        elsif check.is_a?(Array)
+          valid = true
+          list = check.collect {|i|
+            key = self.field_key_value_check(i)
+            key.nil? ? (valid = false; break;) : key
+          }.flatten
+          list if valid and list.length > 0
+        end
+      end
+      
+      # Separate field and action options from the options passed to bit_magic
+      #
+      # Valid keys for field options are:
+      #   Integer - for a specific bit position
+      #   Range - for a range of bits
+      #   Array<Integer> - an array of bit positions
+      # The value of the key-pair should be a Symbol.
+      #
+      # Action options are everything else that's not a field option
+      #
+      # @param [Hash] options the options passed to bit_magic
+      #
+      # @return [Hash, Hash] returns an array of two options [field, actions]
+      #   field options and action options, in that order respectively
+      def self.options_splitter(options = {})
+        field_opts = {}
+        action_opts = DEFAULT_ACTION_OPTIONS.dup
+        
+        options.each_pair do |check_key, value|
+          if key = self.field_key_value_check(check_key)
+            field_opts[key] = value
+          else
+            if (!options[:allow_failed_fields]) and (check_key.is_a?(Integer) or check_key.is_a?(Range) or check_key.is_a?(Array))
+              raise BitMagic::FieldError.new("key-pair expected to be a valid field option, but it is not: #{check_key.inspect} => #{value.inspect}. If this is an action option, you can disable this error by passing ':allow_failed_fields => true' as an option")
+            end
+            action_opts[check_key] = value
+          end
+        end
+        
+        [field_opts.freeze, action_opts.freeze]
+      end
+      
+      attr_reader :field_options, :action_options
+      attr_reader :field_list
+      attr_reader :bits_length, :max_bit
+      attr_reader :bit_magic_name
+      
+      # Initialize a new Magician, a container for bit_magic settings and fields
+      #
+      # @param [Symbol] name the name to be used as a namespace
+      # @param [Hash] options the options given to bit_magic. Keys that are
+      #   Integer, Arrays or Range objects are treated as bit allocations, their
+      #   value should be the name of the bit field. Keys that are anything else
+      #   (usually Symbol) are treated as action options or settings.
+      #
+      # @example Initialize a Magician (usually you would not do this directly)
+      #   magician = Magician.new(:example, 0 => :is_odd, [1, 2] => :eyes, 3..6 => :fingers, default: 7)
+      #   # here, field names are :is_odd, :eyes, and :fingers
+      #   # with bits indices 0, [1, 2], and [3, 4, 5, 6] respectively
+      #   # default is an action option, set to 7
+      #
+      # @return a Magician
+      def initialize(name, options = {})
+        @bit_magic_name = name
+        @field_options, @action_options = self.class.options_splitter(options)
+        validate_field_options!
+      end
+      
+      # Define helper methods on the instance, namespaced to the name given in
+      # the bit_magic invocation.
+      #
+      # This is an internal method, only meant to be used by the Base adapter to
+      # during its setup phase. Should not be used directly.
+      #
+      # Methods that are defined is namespaced to the name during initialization.
+      # Referred to here as NAMESPACE. These methods are available on instances.
+      #
+      #   NAMESPACE - defined by Base adapter, returns a Bits wrapper
+      #   NAMESPACE_enabled?(*field_names) - checks if all the given field names
+      #     or bit indices are enabled (value > 0)
+      #   NAMESPACE_disabled?(*field_names) - checks if all the given field names
+      #     or bit indices are disabled (value == 0)
+      #   
+      # The following are helpers, defined based on field names during initialization
+      # Refered to here as 'name'.
+      #
+      #   name - returns the value of the field
+      #   name=(new_value) - sets the value of the field to the new value
+      #   name? - available only if the field is a single bit, returns true if 
+      #     the value of the bit is 1, or false if 0
+      #
+      # 
+      # @param [Class] klass the class to inject methods into.
+      #
+      # @return nothing useful.
+      def define_bit_magic_methods(klass)
+        names = @field_list
+        bit_magic_name = @bit_magic_name
+        
+        klass.instance_eval do
+        
+          define_method(:"#{bit_magic_name}_enabled?") do |*fields|
+            self.send(bit_magic_name).enabled?(*fields)
+          end
+        
+          define_method(:"#{bit_magic_name}_disabled?") do |*fields|
+            self.send(bit_magic_name).disabled?(*fields)
+          end
+        end
+        
+        if @action_options[:helpers]
+        
+          klass.instance_eval do
+            names.each_pair do |name, bits|
+              
+              define_method(:"#{name}") do
+                self.send(bit_magic_name)[name]
+              end
+              
+              define_method(:"#{name}=") do |val|
+                self.send(bit_magic_name)[name] = val
+              end
+              
+              if bits.is_a?(Integer) or bits.length == 1
+                define_method(:"#{name}?") do
+                  self.send(bit_magic_name)[name] == 1
+                end
+              end
+              
+            end
+          end
+        
+        end
+        
+      end
+      
+      # List of bits defined in @field_options
+      # 
+      # @return [Array<Integer>] an array of bits defined in @field_options
+      def bits
+        @field_list.values.flatten
+      end
+      
+      # Used by the Base#bit_magic to create a Bits wrapper around instances
+      # 
+      # @return [Class] a Bits class
+      def bits_wrapper
+        self.action_options[:bits_wrapper] || Bits
+      end
+      
+      # Used by adapters to generate value lists for particular bit operations
+      #
+      # @return [BitsGenerator] a BitsGenerator object with this magician's field
+      #   list
+      def bits_generator
+        @bits_generator ||= (self.action_options[:bits_generator] || BitsGenerator).new self
+      end
+      
+      # Inspect this object. This is customized just to shorten the output to
+      # actually be readable.
+      def inspect
+        "#<#{self.class.to_s} name=#{@bit_magic_name} field_list=#{@field_list.inspect}>"
+      end
+      
+      protected
+      # Internal use only. Sets @field_list @bits_length and @max_bit from @field_options
+      def validate_field_options!
+        @field_list = {}
+        
+        @field_options.each_pair do |bits, name|
+          name = name.to_sym if name.is_a?(String)
+          
+          if name.is_a?(Symbol)
+            raise FieldError.new("'#{name}' defined more than once") if @field_list.has_key?(name)
+            @field_list[name] = bits
+          else
+            raise FieldError.new("field name must be a symbol or string, #{name.inspect} is not")
+          end
+          
+        end
+        
+        bits = self.bits
+        @bits_length = bits.uniq.length
+        @max_bit = bits.max
+        @field_list.freeze
+      end
+      
+    end
+  
+  end
+end

data/lib/bit_magic/adapters/mongoid_adapter.rb

@@ -0,0 +1,233 @@
+require_relative './base'
+
+module BitMagic
+  module Adapters
+    # This is the adapter for Mongoid. It's implemented as a concern to be
+    # included inside Mongoid::Document models.
+    #
+    # It's expected that you have an integer column (default name 'flags',
+    # override using the attribute_name option). It's suggested, though not
+    # required, that you set the default value same as the bit_magic default.
+    # 
+    # If you have more than one model that you want to use BitMagic in, it's
+    # recommended that you just include this adapter globally:
+    #   require 'bit_magic/adapters/mongoid_adapter'
+    #   Mongoid::Document.include BitMagic::Adapters::MongoidAdapter
+    #
+    # Otherwise, you can include it on a per model basis before calling bit_magic
+    #
+    #   class Example
+    #     include Mongoid::Document
+    #     # this line below can be excluded if you included the adapter globally
+    #     include BitMagic::Adapters::MongoidAdapter 
+    #
+    #     bit_magic :settings, 0 => :is_odd, [1, 2, 3] => :amount, 4 => :is_cool
+    #     field :flags, type: Integer, default: 0
+    #   end
+    #   
+    # After that, you can start using query helpers and instance helpers.
+    # Query helpers return a standard Mongoid::Criteria, so you can do everything
+    # you normally would in a query (like chaining additional conditions).
+    # Instance helpers are wrapped around by a Bits object, in this case, 'settings'
+    # but also have helper methods added based on the name of the fields.
+    #
+    module MongoidAdapter
+      VERSION = "0.1.0".freeze
+      extend ActiveSupport::Concern
+      
+      included do
+        self.extend Base
+      end
+      
+      module ClassMethods
+        # Cast the given value into a Boolean, follows Mongoid::Boolean rules
+        BIT_MAGIC_BOOLEAN_CASTER = lambda do |val|
+          !!Mongoid::Boolean.mongoize(val)
+        end
+        
+        # Adapter options specific to this adapter
+        # 
+        # :named_scopes Enables (true) or disables (false) individual scopes to
+        # query fields
+        # 
+        # :query_by_value whether to use bitwise operations or IN (?) when querying
+        # by default will use IN (?) if the total bits defined by bit_magic is
+        # less than or equal to 8. true to always query by value, false to always
+        # query using bitwise operations
+        BIT_MAGIC_ADAPTER_DEFAULTS = {
+          :bool_caster => BIT_MAGIC_BOOLEAN_CASTER,
+          :named_scopes => true,
+          :query_by_value => 8
+        }.freeze
+        
+        # Method used to set adapter defaults as options to Magician,
+        # Used by the bit_magic definition to add custom options to the magician
+        #
+        # @param [Hash] options some options list
+        #
+        # @return new options list including our custom defaults
+        def bit_magic_adapter_defaults(options)
+          BIT_MAGIC_ADAPTER_DEFAULTS.merge(options)
+        end
+        
+        # This method is called by Base#bit_magic after setting up the magician
+        # Here, we inject query helpers, scopes, and other useful methods
+        #
+        # Query helpers: (NAMESPACE is the name given to bit_magic)
+        # All the methods that generate where queries take an optional options
+        # hash as the last value. Can be used to alter options given to bit_magic.
+        # eg: passing '{query_by_value: false}' as the last argument will force
+        # the query to generate bitwise operations instead of '$in => []' queries
+        # 
+        #   NAMESPACE_query_helper(field_names = nil)
+        #     an internal method used by other query helpers
+        #   NAMESPACE_where_in(array, column_name = nil)
+        #     generates a 'column_name => {:$in => [...]}' query for the array numbers
+        #     column_name defaults to attribute_name in the options
+        #   NAMESPACE_with_all(*field_names, options = {})
+        #     takes one or more field names, and queries for values where ALL of
+        #     them are enabled. For fields with multiple bits, they must be max value
+        #     This is the equivalent of: field[0] and field[1] and field[2] ...
+        #   NAMESPACE_with_any(*field_names, options = {})
+        #     takes one or more field names, and queries for values where any of
+        #     them are enabled
+        #     This is the equivalent of: field[0] or field[1] or field[2] ...
+        #   NAMESPACE_without_any(*field_names, options = {})
+        #     takes one or more field names, and queries for values where at least
+        #     one of them is disabled. For fields with multiple bits, any value
+        #     other than maximum number
+        #     This is the equivalent of "!field[0] or !field[1] or !field[2] ..."
+        #   NAMESPACE_without_all(*field_names, options = {})
+        #     takes one or more field names and queries for values where none of
+        #     them are enabled (all disabled). For fields with multiple bits,
+        #     value must be zero.
+        #     This is the equivalent of: !field[0] and !field[1] and !field[2] ...
+        #   NAMESPACE_equals(field_value_list, options = {})
+        #     * this will truncate values to match the number of bits available
+        #     field_value_list is a Hash with field_name => value key-pairs.
+        #     generates a query that matches the bits to the value, exactly
+        #     This is the equivalent of: field[0] = val and field[1] = value ...
+        #
+        # Additional named scopes
+        # These can be disabled by passing 'named_scopes: false' as an option
+        # FIELD is the field name for the bit/bit range
+        #
+        #   NAMESPACE_FIELD
+        #     queries for values where FIELD has been enabled
+        #   NAMESPACE_not_FIELD
+        #     queries for values where FIELD has been disabled (not enabled)
+        #   NAMESPACE_FIELD_equals(value)
+        #     * only exists for fields with more than one bit
+        #     queries for values where FIELD is exactly equal to value
+        #
+        # @param [Symbol] name the namespace (prefix) for our query helpers
+        # 
+        # @return nothing important
+        def bit_magic_adapter(name)
+          query_prep = :"#{name}_query_helper"
+          query_in = :"#{name}_where_in"
+          
+          self.class_eval do
+            define_singleton_method(query_prep) do |field_names = nil|
+              magician = @bit_magic_fields[name]
+              bit_gen = magician.bits_generator
+              
+              options = (field_names.is_a?(Array) and field_names.last.is_a?(Hash)) ? field_names.pop : {}
+              
+              by_value = options.key?(:query_by_value) ? options[:query_by_value] : magician.action_options[:query_by_value]
+              
+              by_value = (magician.bits_length <= by_value) if by_value.is_a?(Integer)
+              column_name = options[:column_name] || magician.action_options[:column_name] || magician.action_options[:attribute_name]
+              
+              [magician, bit_gen, by_value, column_name]
+            end
+            
+            define_singleton_method(query_in) do |column_name, arr|
+              where(column_name => {:$in => arr})
+            end
+            
+            define_singleton_method(:"#{name}_with_all") do |*field_names|
+              magician, bit_gen, by_value, column_name = self.send(query_prep, field_names)
+              
+              if by_value === true
+                self.send(query_in, column_name, bit_gen.all_of(*field_names))
+              else
+                where(column_name => {:$bitsAllSet => bit_gen.all_of_number(*field_names)})
+              end
+            end
+            
+            define_singleton_method(:"#{name}_without_any") do |*field_names|
+              magician, bit_gen, by_value, column_name = self.send(query_prep, field_names)
+              
+              if by_value === true
+                self.send(query_in, column_name, bit_gen.instead_of(*field_names))
+              else
+                where(column_name => {:$bitsAnyClear => bit_gen.any_of_number(*field_names)})
+              end
+            end
+          
+            define_singleton_method(:"#{name}_without_all") do |*field_names|
+              magician, bit_gen, by_value, column_name = self.send(query_prep, field_names)
+              
+              if by_value === true
+                self.send(query_in, column_name, bit_gen.none_of(*field_names))
+              else
+                where(column_name => {:$bitsAllClear => bit_gen.any_of_number(*field_names)})
+              end
+            end
+            
+            # Query for if any of these bits are set.
+            define_singleton_method(:"#{name}_with_any") do |*field_names|
+              magician, bit_gen, by_value, column_name = self.send(query_prep, field_names)
+              
+              if by_value === true
+                self.send(query_in, column_name, bit_gen.any_of(*field_names))
+              else
+                where(column_name => {:$bitsAnySet => bit_gen.any_of_number(*field_names)})
+              end
+            end
+            
+            define_singleton_method(:"#{name}_equals") do |field_value, options = {}|
+              magician, bit_gen, by_value, column_name = self.send(query_prep, [options])
+              
+              if by_value === true
+                self.send(query_in, column_name, bit_gen.equal_to(field_value))
+              else
+                all_num, none_num = bit_gen.equal_to_numbers(field_value)
+                where(column_name => {:$bitsAllSet => all_num, :$bitsAllClear => none_num})
+              end
+            end
+            
+          end
+          
+          
+          if @bit_magic_fields and @bit_magic_fields[name] and @bit_magic_fields[name].action_options[:named_scopes]
+            fields = @bit_magic_fields[name].field_list
+            
+            self.class_eval do
+              fields.each_pair do |field, value|
+                define_singleton_method(:"#{name}_#{field}") do
+                  self.send(:"#{name}_with_all", field)
+                end
+                
+                define_singleton_method(:"#{name}_not_#{field}") do
+                  self.send(:"#{name}_without_all", field)
+                end
+                
+                if value.is_a?(Array) and value.length > 1
+                  define_singleton_method(:"#{name}_#{field}_equals") do |val|
+                    self.send(:"#{name}_equals", field => val)
+                  end
+                end
+
+              end
+
+            end
+          end
+          
+        end
+      end
+      
+    end
+  end
+end