has_flags 0.0.1

data/README

@@ -0,0 +1,51 @@
+= has_flags.rb - Has Bit Flags Plugin
+
+Copyright 2006, Rain City Software, Inc. License: Apache 2.0, Version 0.1.4  11-Aug-2006
+
+== Overview
+
+The has_flags plugin provides a simple way to define and access multiple
+boolean flags that map to a single integer database column.  The primary
+objects for using flags are:
+
+  1) control and access the state of an object
+  2) to enable finding database rows with a particular state
+  3) to ease long term maintenance by providing a database definition independent way of extending states
+  4) to be able to adapt to legacy systems that use this approach
+
+
+== Conventions:
+
+  *) Db Column Name: bit_flags
+  *) attribute writer (setter) accepts true, 'true', 'yes', :yes, 1, '1', 'ok' to evaluate true.  all others are false.
+
+== Sample Use:
+
+    class PayableInvoice << ActiveRecord::Base
+      has_flags [ :active, true, :ok_to_post, 7, :posted, :archived ]
+    end
+
+=== instance attrs
+
+  invoice = Payable.new => new payable object created, uses 'after_initialize' to set defaults
+  invoice.active?      => true
+  invoice.active       => true
+  invoice.ok_to_post?  => false
+  invoice.bit_flags    => 1  # follows the 'active=true' configuration
+
+  invoice.active = v   => true where v is in [ true, 'true', 1, '1', 'yes', 'YeS', :yes, :ok 'OK', "oK" ]
+  invoice.active = v   => false where v.to_s.upcase is not in the list above
+
+=== Class Methods
+
+  PayableInvoice.flags    => { "active"=>1, "ok_to_post"=>128, "posted"=>256, "archived"=>512 }
+  PayableInvoice.mask(:ok_to_post, :posted) => 384 (0b0110000000)
+  PayableInvoice.mask(:active, :archived)   => 512 (0x1000000000)
+
+=== Finders
+
+  PayableInvoice.find_by_flags(:active, :ok_to_post)  => returns a list of objects that are 'active' and 'ok to post'
+  PayableInvoice.find_by_flags(:not_active)           => returns a list of objects that are not active
+
+For other examples, see http://RainCityOnRails.com/has_flags
+

data/lib/has_flags.rb

@@ -0,0 +1,214 @@
+################################################################################################
+# darryl.west@RainCitySoftware.com
+# Copyright 2006, Rain City Software, all rights reserved
+# version 0.1.4
+#
+# License: Apache 2.0
+#
+# Usage:
+#   class MyClass << ActiveRecord::Base
+#     has_flags [ :symbol, position, true/false, :symbol, ... ], [ options ]
+#   end
+# Options:
+#   :column = 'bit_flags'
+#
+# Attribute Accessors:
+#   readers: name, name?
+#   writer: name=(v)
+#   where 'name' is the name of the bit field.  the (v) parameter can be true/false, "true"/"false", 0/1, 'yes'/'no',
+#   or :yes/:no.  specifically, the following (v) inputs evaluate to true:
+#     [ true, 'true', 'yes', :yes, 'ok', :ok, 1, '1' ]
+#   all others, including nil evaluate false.
+#
+#
+# Note: db table must include the column 'bit_flags' as an integer. Use the :column option to
+#   override with an alternate name
+# Note: defaults are set in the 'after_initialized' callback.  If your model needs to use this
+#   callback, define it in the class and invoke: init_flags.  Here is an example:
+#
+#   class MyClass << ActiveRecord::Base
+#     has_flags [ :symbol, position, true/false, :symbol, ... ], [ options ]
+#     def after_initialize
+#       init_flags
+#       ... do more stuff ...
+#     end
+#   end
+# 
+# Example Use: 
+#   has_flags [ :active, true, :has_invoice, 3, :canceled, 8 ]
+#     this example creates nine accessor methods, active?, active, active=(v), has_invoice?, has_invoice,
+#     has_invoice=(v), canceled?, canceled and canceled=(v).  the 'bit_flags' bit flag is updated to follow 
+#     the setters, and when the class is initialized as new (not after a find), the default (active=true) is set.
+#
+#   has_flags [ :active, true, :deleted 8 ], [ :column = 'status_flags' ]
+#   The has_flags method registers the Symbol objects as ? and =(v) accessors.  it also takes care of
+#   updating the underlying data element (defaults to 'bit_flags') when the =(v) methods are invoked.  So
+#   if MyClass uses has_flags, then you could do the following:
+#     myclass = MyClass.new
+#     active = false if active?
+#     has_invoice = false
+#     myclass.save
+#   This would change the myclass.bit_flags value, then send it to the database.
+#
+require 'active_record'
+
+module RainCity
+  module Has #:nodoc:
+    module BitFlags #:nodoc:
+      
+      # this hook is called by ActiveRecord::Base
+      def self.included(mod)
+        mod.extend(ClassMethods)
+      end
+      
+      #
+      # declare the class method "has_flags" 
+      # create the instance methods based on bitflags and options
+      #
+      module ClassMethods
+        def has_flags(bitflags, options = { })
+          unless respond_to? :bitflag_attr
+            class_eval { cattr_accessor :bitflag_column, :bitflags, :default_mask }
+            # use config to lookup these values
+            self.bitflag_column, self.bitflags, self.default_mask = 'bit_flags', { }, 0
+          end
+          
+          parse_options options
+          create_accessors bitflags
+          
+          # now declare the class Singleton methods
+          class_eval { extend RainCity::Has::BitFlags::BitFlagMethods }
+        end
+        
+        private
+        def create_accessors(bitflags)
+          name = nil
+          position = 0
+          default = false
+          column = self.bitflag_column
+          bitflags.each do |v|
+            case v
+              when Symbol, String
+                if name
+                  add_accessors(column, name, position, default)
+
+                  default = false
+                  position += 1
+                end
+
+                name = v.to_s
+              when Fixnum
+                position = v
+              when TrueClass, FalseClass
+                default = v
+              else
+                raise RuntimeError, "BitFlag: initialize error: " + bitflags.inspect
+            end
+          end
+          # now do the last one
+          add_accessors(column, name, position, default)
+          
+          define_method( 'initialize_flags') do
+            if @new_record
+              self[column] = self.default_mask
+            end
+          end
+          
+          if true
+            define_method( 'after_initialize' ) do
+              initialize_flags
+            end
+          end
+        end
+        
+        #
+        # add the ? and = accessors.  add the after_initialize method unless it's optioned out (:after_init => false)
+        #
+        def add_accessors(column, name, position, default)
+          mask = (1 << position)
+          self.bitflags[name] = mask
+          if default 
+            self.default_mask += mask
+          end
+          
+          # now the instance accessors
+          # return true/false
+          define_method( (name + '?').to_sym ) do
+            bits = self[column] ||= 0
+            bits[position].eql? 1
+          end
+          
+          # set with true/false 
+          define_method( (name + '=').to_sym ) do |v|
+            bits = self[column] ||= 0
+            flag = [ "true", '1', 'yes', 'ok' ].include? v.to_s.downcase
+            self[column] = flag ? bits |= mask : bits &= ~mask
+          end
+          
+          # make this easy for the form builders like 'check_box' to use standard accessors
+          define_method( name.to_sym ) do
+            bits = self[column] ||= 0
+            bits[position].eql? 1
+          end
+        
+        end
+        
+        # parse the options for known symbols.  raise a Runtime if a symbol is unrecognized
+        def parse_options(options)
+          options.each do |option|
+            option.each_pair do |opt, val|
+              case opt
+                when :column
+                  self.bitflag_column = val.to_s
+                when :group
+                  raise RuntimeError, 'Groups not supported for alpha version...'
+                else
+                  raise RuntimeError, "BitFlag: unrecognized option: " + opt.to_s
+              end
+            end
+          end
+        end
+
+      end
+      
+      # static Singletons
+      module BitFlagMethods
+        #
+        # return the flags as a hash of labels and values, i.e., the symbols (as strings) and bit mask values
+        #
+        def flags
+          self.bitflags
+        end
+        
+        #
+        # return the integer mask given the list of defined symbols.
+        #
+        def mask(*args)
+          flags = self.flags
+          
+          args.inject(0) do |n, name|
+            n += flags[name.to_s]
+          end
+        end
+        
+        #
+        # return the list of objects using the defined symbols as bit arguments
+        #
+        def find_by_flags(*args)
+          flags = self.flags
+          
+          msk = args.inject(0) do |n, name|
+            n += flags[name.to_s]
+          end
+          
+          s = sprintf "(%s & %i)=%i", self.bitflag_column, msk, msk
+          self.find :all, :conditions => [ s ]
+        end
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.class_eval do
+  include RainCity::Has::BitFlags
+end

data/rails/init.rb

@@ -0,0 +1 @@
+require 'has_flags'

data/tasks/has_flags_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :has_flags do
+#   # Task goes here
+# end

data/test/has_flags_test.rb

@@ -0,0 +1,67 @@
+require 'test/unit'
+require 'active_record'
+require File.expand_path(File.dirname(__FILE__) + "/../lib/has_flags")
+
+#
+# darryl.west@RainCitySoftware.com
+# 
+# test all methods and combinations of 'has_flags'.
+#
+class HasFlagsTest < Test::Unit::TestCase
+  
+  class ModelA < ActiveRecord::Base
+    has_flags [ :active, true, :deleted, 7 ]
+    attr_accessor :bit_flags
+  end
+  
+  class ModelB < ActiveRecord::Base
+    has_flags [ :active, true, :banned, 4, :deleted, 8, :archived, 10 ]
+    attr_accessor :bit_flags
+  end
+  
+  def test_class_methods
+    assert_respond_to ModelA, 'flags', 'should understand flags method'
+    assert_respond_to ModelA, 'mask', 'should understand mask method'
+    assert_respond_to ModelA, 'bitflag_column'
+    assert_respond_to ModelA, 'find_by_flags'
+    
+    a = ModelA.flags
+    b = ModelB.flags
+    
+    assert_equal 2, a.size
+    assert a.include?( 'active' )
+    assert a.include?( 'deleted' )
+    assert !a.include?( 'banned' ) # verify no cross-blead between classes
+    assert !a.include?( 'archived' )
+    
+    assert_equal 4, b.size
+    assert b.include?( 'active' )
+    assert b.include?( 'banned' )
+    assert b.include?( 'deleted' )
+    assert b.include?( 'archived' )
+    
+    assert_equal 1, a['active']
+    assert_equal 1, ModelA.mask( :active )
+    assert_equal 128, ModelA.mask( :deleted )
+    assert_equal 129, ModelA.mask( :active, :deleted )
+    assert_equal 1, ModelB.mask( :active )
+    assert_equal 16, ModelB.mask( :banned )
+    assert_equal 256, ModelB.mask( :deleted )
+    assert_equal 1024, ModelB.mask( :archived )
+    assert_equal 1297, ModelB.mask( :active, :banned, :deleted, :archived )
+  end
+  
+  def test_instance_methods
+    # TODO figure out how to get a connection to the database, create model a & b tables in setup, drop in teardown
+  end
+     
+  def test_options
+    # test the good ones
+    ActiveRecord::Base.has_flags [ :active, true, :deleted, 7 ], [ :column => 'my_column_name' ]
+    
+    # test the bad...
+    assert_raise RuntimeError do
+      ActiveRecord::Base.has_flags [ :active, true, :deleted, 7 ], [ :bad_option => false ]
+    end
+  end
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification 
+name: has_flags
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Darryl West
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-05-09 00:00:00 Z
+dependencies: []
+
+description: 
+email: darryl.west@RainCitySoftware.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- lib/has_flags.rb
+- rails/init.rb
+- tasks/has_flags_tasks.rake
+- test/has_flags_test.rb
+- README
+homepage: https://github.com/ashleym1972/has-flags
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.7.2
+signing_key: 
+specification_version: 3
+summary: Using BitFlags in ActiveRecord
+test_files: []
+