attr_bitwise 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1c7bc7f15d2c51cdaa8e8fc01987c4b3e500d89a
-  data.tar.gz: fe4fbf205f6c998ea684a45f56e61a833623e1fc
+  metadata.gz: 0fe35e1015d6b3d56fad87e17480767740a23dd0
+  data.tar.gz: c0ca410c937a40d73eab1b8dac53087cd93c4ab2
 SHA512:
-  metadata.gz: 5aaa7af4fc47354187a8c654f296642d7a0699ebac3676d5ef6891895b730da09b674f8dba5f639d9b7e003605d85f5a87fb780da880f29e8531a562dc809866
-  data.tar.gz: b70fcaf5b88f2eaea060277a4860c1e018a714002ddcf7fb76f5d33fb4a5a99e5c30a08f42acad45ce4b2c44cb6c7ca50a613c61b7a1d07a9f207e2da5460f83
+  metadata.gz: ddb05f9230a5a78c3f4534422eb8ec36c1ccabea059ce52a0b8fbc03456e468e59a64c3c7104afe9adfc5134c339223d94042d980d9e958359ed27fe96065927
+  data.tar.gz: 29bc9ace8d2e82f5459802ebd7e69d3a4978ef9712b6814a6742de4bd0606f0e78a1a2d2fdf3841aa2cd141dbda74646ba6baf9e106c977ac85a363ca353311f

data/Gemfile

@@ -1,3 +1,5 @@
 source 'https://rubygems.org'
 
+ruby '2.1.1'
+
 gemspec

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    attr_bitwise (0.0.1)
+    attr_bitwise (0.0.2)
       activesupport
 
 GEM
@@ -43,3 +43,6 @@ DEPENDENCIES
   bundler (~> 1.6)
   rake
   rspec
+
+BUNDLED WITH
+   1.10.6

data/README.md

@@ -1,36 +1,12 @@
-# `attr_bitwise`
+# `attr_bitwise` ![https://circleci.com/gh/wittydeveloper/attr_bitwise.png?circle-token=7f58370c3b13faaf1954b9e8fe6c7b1fb329daf2](https://circleci.com/gh/wittydeveloper/attr_bitwise.png?circle-token=7f58370c3b13faaf1954b9e8fe6c7b1fb329daf2) [![Gem Version](https://badge.fury.io/rb/attr_bitwise.svg)](https://badge.fury.io/rb/attr_bitwise)
 Bitwise attribute for ruby class and Rails model
 
-```ruby
-# Helper to define a bits based value on a Rails model attribute
-#   this helper expose a set of methods to make bitwise operations
-#
-#
-# Usage :
-#   attr_bitwise :<name>, [column_name: <column_name>,] mapping: <values_sym>
-#
-# Example
-# class MyModel < ActiveRecord::Base
-#   include BitwiseUtils
-#
-#   attr_bitwise :payment_types, mapping: [:slots, :credits]
-# end
-#
-# Will define the following high-level methods :
-#   - Class#payment_types => [<Symbol>, ...]
-#   - Class#payment_type?(value_or_sym) => Boolean
-#   - Class#add_payment_type(value_or_sym) => Fixnum
-#   - Class#remove_payment_type(value_or_sym) => Fixnum
-#
-# Will define the following low-level methods :
-#   - Class.to_bitwise_values(object, name) => [<Fixnum>, ...]
-#   - Class#payment_types_union([Fixnum, ..]) => [Fixnum, ..]
-#   - Class.bitwise_union([Fixnum, ..], name) => [Fixnum, ..]
-#   - Class#payment_types_intersection([Fixnum, ..]) => [Fixnum, ..]
-#   - Class.bitwise_intersection([Fixnum, ..], name) => [Fixnum, ..]
-#   - Class#payment_types_mapping => Hash
-#
-```
+## Features
+
+- bitwise attribute + helpers, useful for storing multiple states in one place
+- ActiveRecord compatible
+
+[Please read this article for some concrete examples](https://medium.com/jobteaser-dev-team/rails-bitwise-enum-with-super-powers-5030bda5dbab)
 
 
 ## Install
@@ -38,12 +14,230 @@ Bitwise attribute for ruby class and Rails model
 
 ### Inline
 
-- `gem install bitwise_attr`
+- `gem install attr_bitwise`
 
 ### Gemfile
 
-- `gem 'bitwise_attr'`
+- `gem 'attr_bitwise'`
+
+
+## Usage
+
+```ruby
+attr_bitwise :<name>, mapping: <values_sym> [, column_name: <column_name>]
+```
+
+## Example
+
+You have a website with many locales (English, French, German...) with specific content in each locale. You want your users to be able to chose which content they want to see and you want to be able to query the users by the locales they have choosen.
+
+Start with migration
+```ruby
+class CreateUsers < ActiveRecord::Migration
+  def change
+    create_table :users do |t|
+      # [...]
+      t.integer :locales_value
+    end
+  end
+end
+```
+   
+Model
+```ruby
+
+class User < ActiveRecord::Base
+  include AttrBitwise
+
+  attr_bitwise :locales, mapping: [:en, :fr, :de]
+
+  scope :with_any_locales, lambda { |*locales_sym|
+    where(locales_value: bitwise_union(*locales_sym, 'locales'))
+  }
+
+  scope :with_all_locales, lambda { |*locales_sym|
+    where(locales_value: bitwise_intersection(*locales_sym, 'locales'))
+  }
+
+end
+
+### 
+
+# return all users who can see at least english or french content
+User.with_any_locales(:en, :fr)
+
+# return all users who can see english and french content
+User.with_all_locales(:en, :fr)
+
+```
+
+
+## API
+
+**Examples with <code>name = 'locales'</code>**
+
+### High level methods
+<table>
+  <tr>
+    <th>Method</th>
+    <th>Return</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>
+      <code>Class#locales</code>
+    </td>
+    <td>
+      <code>[<Symbol>, ...]</code>
+    </td>
+    <td>
+      Return values as symbols
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <code>Class#locales=([value_or_sym, ..])</code>
+    </td>
+    <td>
+      <code>[<Symbol>, ...]</code>
+    </td>
+    <td> 
+      Given an array of values (Fixnum or Symbol) or single value (Fixnum or Symbol) add them to value.
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <code>Class#locale == fixnum_or_sym</code>
+    </td>
+    <td>
+      <code>Boolean</code>
+    </td>
+    <td>
+      Return true if value contains only Fixnum or Symbol
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <code>Class#locale?(fixnum_or_sym)</code>
+    </td>
+    <td>
+      <code>Boolean</code>
+    </td>
+    <td>
+      Return true if value contains Fixnum or Symbol
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <code>Class#add_locale(value_or_sym)</code>
+    </td>
+    <td>
+      <code>Fixnum</code>
+    </td>
+    <td>
+      Add Fixnum or Symbol to value
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <code>Class#remove_locale(value_or_sym)</code>
+    </td>
+    <td>
+      <code>Fixnum</code>
+    </td>
+    <td>
+      Remove Fixnum or Symbol to value
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <code>Class#locales_union([value_or_sym, ..])</code>
+    </td>
+    <td>
+      <code>[Fixnum, ..]</code>
+    </td>
+    <td>
+      Given an array of values (Fixnum or Symbol), return bitwise union computation <br>
+      Return all possible values (mask) for an union of given values
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <code>Class#locales_intersection([value_or_sym, ..])</code>
+    </td>
+    <td>
+      <code>[Fixnum, ..]</code>
+    </td>
+    <td>
+      Given an array of values (Fixnum or Symbol), return bitwise intersection computation <br>
+      Return all possible values (mask) for an intersection of given values
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <code>Class#locales_mapping</code>
+    </td>
+    <td>
+      <code>Hash</code>
+    </td>
+    <td>
+      Return <code>Symbol</code> -> <code>Fixnum</code> mapping
+    </td>
+  </tr>
+
+
+</table>
+
+
+### Low level methods
+
+*Theses methods are static, so a <code>name</code> parameters is mandatory in order to fetch mapping*
+
+
+<table>
+  <tr>
+    <th>Method</th>
+    <th>Return</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>
+      <code>Class.to_bitwise_values(object, name)</code>
+    </td>
+    <td>
+      <code>[Fixnum, ...]</code>
+    </td>
+    <td>
+      Given an Object and a attribute name, return Fixnum value depending on mapping
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <code>Class.bitwise_union([Fixnum, ..], name)</code>
+    </td>
+    <td>
+      <code>[Fixnum, ..]</code>
+    </td>
+    <td>
+      Given an array of values (Fixnum or Symbol) and a attribute name, return bitwise union computation <br>
+      Return all possible values (mask) for an union of given values
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <code>Class.bitwise_intersection([Fixnum, ..], name)</code>
+    </td>
+    <td>
+      <code>[Fixnum, ..]</code>
+    </td>
+    <td>
+      Given an array of values (Fixnum or Symbol) and a attribute name, return bitwise intersection computation <br>
+      Return all possible values (mask) for an intersection of given values
+    </td>
+  </tr>
+
+</table>
 
 
 ----------------------------------------
-Maintainers :  @wittydeveloper and @FSevaistre 
+Maintainers :  [@wittydeveloper](https://github.com/wittydeveloper) and [@FSevaistre](https://github.com/FSevaistre)

data/circle.yml

@@ -0,0 +1,3 @@
+machine:
+  ruby:
+    version: 2.1.1

data/lib/attr_bitwise/version.rb

@@ -1,3 +1,3 @@
 module AttrBitwise
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/lib/attr_bitwise.rb

@@ -12,7 +12,7 @@ require "attr_bitwise/version"
 #
 # Example
 # class MyModel < ActiveRecord::Base
-#   include BitwiseUtils
+#   include AttrBitwise
 #
 #   attr_bitwise :payment_types, mapping: [:slots, :credits]
 # end
@@ -35,6 +35,21 @@ require "attr_bitwise/version"
 module AttrBitwise
   extend ActiveSupport::Concern
 
+
+  # Custom class that allow to use shortcut :
+  #   my_column == :banana
+  # instead of
+  #   my_column == [:banana]
+  class ComparableSymbolsArray < Array
+    def ==(other_object)
+      if other_object.is_a?(Symbol)
+        self.size == 1 && self.first == other_object
+      else
+        super(other_object)
+      end
+    end
+  end
+
   # ClassMethods
   module ClassMethods
     ######################
@@ -59,10 +74,7 @@ module AttrBitwise
       define_method("#{name}") { send(:value_getter, bitwise_mapping) }
 
       define_method("#{name}=") do |values_or_symbols_array|
-        unless values_or_symbols_array.is_a?(Array)
-          values_or_symbols_array = [values_or_symbols_array]
-        end
-        send(:value_setter, values_or_symbols_array, bitwise_mapping)
+        send(:value_setter, Array(values_or_symbols_array), bitwise_mapping)
       end
 
       # masks symbol presence
@@ -199,8 +211,10 @@ module AttrBitwise
   # Return current value to symbols array
   #   Ex : 011 => :slots, :credits
   def value_getter(mapping)
-    mapping.values.select { |pv| (value & pv) != 0 }.
-      map { |v| value_to_sym(v, mapping) }
+    ComparableSymbolsArray.new(
+      mapping.values.select { |pv| (value & pv) != 0 }.
+        map { |v| value_to_sym(v, mapping) }
+    )
   end
 
   # Set current values from values array

data/spec/attr_bitwise_spec.rb

@@ -7,12 +7,12 @@ describe AttrBitwise do
 
     include AttrBitwise
 
-    attr_accessor :payment_types_value
+    attr_accessor :fruits_value
 
-    attr_bitwise :payment_types, mapping: [:slots, :credits]
+    attr_bitwise :fruits, mapping: [:banana, :apple]
 
     def initialize
-      @payment_types_value = 0
+      @fruits_value = 0
     end
 
   end
@@ -26,10 +26,10 @@ describe AttrBitwise do
         expect(
           TestClass.to_bitwise_values(
             {
-              a: :credits,
-              b: :slots
+              a: :apple,
+              b: :banana
             },
-            'payment_types'
+            'fruits'
           )
         ).to eq [2, 1]
       end
@@ -38,101 +38,121 @@ describe AttrBitwise do
     context 'with Array argument' do
       it do
         expect(TestClass.to_bitwise_values(
-          [:credits, :slots],
-          'payment_types'
+          [:apple, :banana],
+          'fruits'
         )).to eq [2, 1]
       end
     end
 
     context 'with Fixnum argument' do
       it do
-        expect(TestClass.to_bitwise_values(1, 'payment_types')).to eq 1
+        expect(TestClass.to_bitwise_values(1, 'fruits')).to eq 1
       end
     end
 
   end
 
-  context 'with `payment_types` attribute_name' do
+  context 'with `fruits` attribute_name' do
 
-    context '#payment_types=' do
+    context '#fruits=' do
 
-      before { subject.payment_types = [:slots, :credits] }
+      before { subject.fruits = [:banana, :apple] }
 
       it 'should set proper value' do
-        expect(subject.payment_types_value).to eq 3
-        expect(subject.payment_types).to eq [:slots, :credits]
+        expect(subject.fruits_value).to eq 3
+        expect(subject.fruits).to eq [:banana, :apple]
       end
 
     end
 
-    context 'with `payment_types_value` = 0' do
-      context '#payment_types' do
+    context '#fruits==' do
+
+      context 'when value is incorrect' do
+        before { subject.fruits = [:banana, :apple] }
+
+        it do
+          expect(subject.fruits == :banana).to eq false
+        end
+      end
+
+      context 'when value is correct' do
+        before { subject.fruits = [:banana] }
+
+        it do
+          expect(subject.fruits == :banana).to eq true
+        end
+      end
+
+    end
+
+    context 'with `fruits_value` = 0' do
+      context '#fruits' do
 
         it do
-          expect(subject.payment_types).to eq []
+          expect(subject.fruits).to eq []
         end
 
       end
 
-      context '#add_payment_type' do
+      context '#add_fruit' do
 
         it do
-          subject.add_payment_type(:slots)
-          expect(subject.payment_types).to eq [:slots]
+          subject.add_fruit(:banana)
+          expect(subject.fruits).to eq [:banana]
         end
 
         context 'when called twice, each type remains unique' do
           it do
-            subject.add_payment_type(:slots)
-            subject.add_payment_type(:slots)
-            expect(subject.payment_types).to eq [:slots]
+            subject.add_fruit(:banana)
+            subject.add_fruit(:banana)
+            expect(subject.fruits).to eq [:banana]
           end
         end
 
       end
 
-      context '#payment_type?(:slots)' do
+      context '#fruit?(:banana)' do
 
         it do
-          expect(subject.payment_type?(:slots)).to eq false
+          expect(subject.fruit?(:banana)).to eq false
         end
 
       end
     end
 
-    context 'with `payment_types_value` = 3' do
+    context 'with `fruits_value` = 3' do
 
-      before { subject.payment_types_value = 3 }
+      before { subject.fruits_value = 3 }
 
-      context '#payment_types' do
+      context '#fruits' do
 
         it do
-          expect(subject.payment_types).to eq [:slots, :credits]
+          expect(subject.fruits).to eq [:banana, :apple]
         end
 
       end
 
-      context '#payment_type?(:slots)' do
+      context '#fruit?(:banana)' do
 
         it do
-          expect(subject.payment_type?(:slots)).to eq true
+          expect(subject.fruit?(:banana)).to eq true
         end
 
       end
 
-      context '#remove_payment_type' do
+      context '#remove_fruit' do
 
         it do
-          subject.remove_payment_type(:slots)
-          expect(subject.payment_types).to eq [:credits]
+          subject.remove_fruit(:banana)
+          expect(subject.fruits).to eq [:apple]
         end
 
       end
 
-      context '#payment_types_union' do
+      context '#fruits_union' do
 
         it do
-          expect(subject.payment_types_union(1, 2)).to eq [1, 3, 2]
+          expect(subject.fruits_union(1, 2)).to eq [1, 3, 2]
         end
 
       end
@@ -141,7 +161,7 @@ describe AttrBitwise do
 
         it do
           expect(
-            TestClass.bitwise_union(1, 2, 'payment_types')
+            TestClass.bitwise_union(1, 2, 'fruits')
           ).to eq [1, 3, 2]
         end
 
@@ -151,7 +171,7 @@ describe AttrBitwise do
 
         it do
           expect(
-            TestClass.bitwise_intersection(1, 2, 'payment_types')
+            TestClass.bitwise_intersection(1, 2, 'fruits')
           ).to eq [3]
         end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: attr_bitwise
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Charly POLY
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-02-24 00:00:00.000000000 Z
+date: 2016-04-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -80,6 +80,7 @@ files:
 - README.md
 - Rakefile
 - attr_bitwise.gemspec
+- circle.yml
 - lib/attr_bitwise.rb
 - lib/attr_bitwise/version.rb
 - spec/attr_bitwise_spec.rb
@@ -103,7 +104,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.8
 signing_key: 
 specification_version: 4
 summary: Bitwise attribute for ruby class and Rails model