one-pivot 0.9.2

data/Gemfile

@@ -0,0 +1,7 @@
+source :rubygems
+
+gem 'shoulda',   '2.11.3'
+gem 'yard',      '0.6.4'
+gem 'bluecloth', '2.0.10'
+
+

data/Gemfile.lock

@@ -0,0 +1,14 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    bluecloth (2.0.10)
+    shoulda (2.11.3)
+    yard (0.6.4)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bluecloth (= 2.0.10)
+  shoulda (= 2.11.3)
+  yard (= 0.6.4)

data/README.md

@@ -0,0 +1,137 @@
+#[1on1](http://1on1.com/) one-pivot GEM
+
+##Overview
+The **one-pivot** GEM provides a simple way to mine data from a list of objects. There are no constraints on the types of objects that you can pivot. You can pivot anything from a list of numbers to a list of ActiveRecord objects to anything in between.  
+
+**`One::Pivot`** exposes two methods of importance.  
+
+* **`pivot`** - runs a single pivot 
+* **`multi-pivot`** - stacks multiple pivots into a single result
+
+A **`pivot`** is simply a Ruby block (or Proc) that executes for each item in the list.  The result returned from this block then serves as the key in the resulting Hash.
+
+Lets have a look at some examples.
+
+_Note: there are a few advanced features not demonstrated in the examples below. For example, adding identifiers to pivots or attaching observers to pivot operations. We use these features at 1on1 to cache pivot results for each item. This gives us a big performance boost when the same item participates in multiple pivots during its lifetime... especially when the pivot Proc is an expensive operation.  Have a look at the [tests](https://github.com/one-on-one/pivot/tree/master/test) when you want to dig a little deeper._
+
+##A simple single pivot
+<pre>
+<code>
+require 'one-pivot'
+
+# create the pivot instance
+pivoter = One::Pivot.new
+
+# create a list of objects to pivot
+list = [1,2,3,4,5,6,7,8,9]
+
+# run a single pivot
+# note: the block passed to the pivot method is invoked for each item in the list
+# note: the result from the block will act as the 'key' in the resulting Hash
+result = pivoter.pivot {|item| item <= 5}
+
+# 'result' will be a Hash with the following structure
+{
+  true => [1,2,3,4,5],
+  false => [6,7,8,9]
+}
+</code>
+</pre>
+
+
+##A simple multi-pivot
+<pre>
+<code>
+require 'one-pivot'
+
+# create the pivot instance
+# note: the multi-pivot delimiter that was specified
+pivoter = One::Pivot.new
+
+# create a list of objects to pivot
+list = [1,2,3,4,5,6,7,8,9]
+
+# run several pivots together
+pivots = []
+
+pivots << lambda do |i|
+  key = "less than or equal to 5" if i <= 5
+  key ||= "greater than 5"
+end
+
+pivots << lambda do |i|
+  key = "greater than or equal to 3" if i >= 3
+  key ||= "less than 3"
+end
+
+pivots << {:delimiter => " & "}
+
+result = pivoter.multi_pivot(list, *pivots)
+
+# 'result' will be a Hash with the following structure
+{
+  "less than or equal to 5 & greater than or equal to 3" => [3, 4, 5], 
+  "less than or equal to 5 & less than 3" => [1, 2], 
+  "greater than 5 & greater than or equal to 3" => [6, 7, 8, 9]
+}
+</code>
+</pre>
+
+##A real world example
+<pre>
+<code>
+# we'll be working with ActiveRecord objects based on the following schema
+# ============================================================================
+# create_table "users", :force => true do |t|
+#   t.string   "name"
+#   t.datetime "created_at"
+#   t.datetime "updated_at"
+# end
+#
+# create_table "skills", :force => true do |t|
+#   t.string   "name"
+#   t.datetime "created_at"
+#   t.datetime "updated_at"
+# end
+#
+# create_table "skills_users", :id => false, :force => true do |t|
+#   t.integer "user_id"
+#   t.integer "skill_id"
+# end
+# 
+# and will seed the datbase with the following data
+# ============================================================================
+# ruby = Skill.create(:name => "Ruby")
+# python = Skill.create(:name => "Python")
+# php = Skill.create(:name => "PHP")
+# javascript = Skill.create(:name => "JavaScript")
+# 
+# users = User.create([
+#   {:name => "Ryan", :skills => [ruby]},
+#   {:name => "Dave", :skills => [php, javascript]},
+#   {:name => "Brett", :skills => [ruby, javascript]},
+#   {:name => "Jay", :skills => [ruby, python, php, javascript]},
+#   {:name => "Doug"}
+# ])
+#
+
+require 'one-pivot'
+
+pivoter = One::Pivot.new
+# note that the pivot block returns an array
+# each unique value in the arrays returned will become a key in the resulting Hash
+result = pivoter.pivot(User.all) do |user|
+  user.skills
+end
+
+# 'result' will be Hash with the following structure
+# note: I've simplified the object structure (using names only) for clarity 
+{
+  "Ruby" => ["Brett", "Jay", "Ryan"],
+  "PHP" => ["Dave", "Jay"],
+  "JavaScript" => ["Brett", "Dave", "Jay"],
+  "Python" => ["Jay"],
+  nil => ["Doug"]
+} 
+</code>
+</pre>

data/Rakefile

@@ -0,0 +1,10 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+Rake::TestTask.new(:test) do |t|
+  t.test_files = FileList['test/*_test.rb']
+end
+
+task 'test:units' => ['test'] do
+end

data/lib/one-pivot.rb

@@ -0,0 +1,2 @@
+require File.expand_path(File.join(File.dirname(__FILE__), 'one', 'pivot'))
+require File.expand_path(File.join(File.dirname(__FILE__), 'one', 'pivoter'))

data/lib/one/pivot.rb

@@ -0,0 +1,21 @@
+module One
+
+  # Simple class to hold meta information about a pivot.
+  # This class was created to support invoking One::Pivot#multi_pivot with identifiers for each pivot.
+  class Pivot
+    attr_reader :identifier
+    attr_reader :pivot_proc
+
+    # Constructor.
+    # param [String, Symbol] identifier The name of the pivot
+    # @yield [item] This block will be called for each item in the list when pivot is invoked
+    # @yieldparam [Object] item An item in the list
+    # @yieldreturn [Object] The value returned from the pivot block will serve as the key in the pivot results
+    def initialize(identifier, &block)
+      raise LocalJumpError.new("no block given") unless block_given?
+      @identifier = identifier
+      @pivot_proc = block
+    end
+  end
+
+end

data/lib/one/pivoter.rb

@@ -0,0 +1,139 @@
+require 'observer'
+
+# Namespace module for One on One Marketing.
+module One
+
+  # Class that can be used for mining data from lists of objects.
+  class Pivoter
+    include Observable
+
+    # Pivots a list of Objects grouping them into an organized Hash.
+    #
+    # @example Pivot a list of numbers into 2 groups, those less than or equal to 5 and those greater than 5
+    #   list = [1,2,3,4,5,6,7,8,9]
+    #   result = pivot(list) {|num| num <=5 }
+    #
+    #   # the result will be a Hash with the following structure
+    #   {
+    #     true=>[1, 2, 3, 4, 5],
+    #     false=>[6, 7, 8, 9] 
+    #   }
+    #
+    # @param [Array<Object>] list The list to pivot
+    # @param [optional, Hash] options Options to pivot with
+    # @option options [Object] :identifier A name that uniquely identifies the pivot operation 
+    # @yield [item] The block passed to pivot will be called for each item in the list 
+    # @yieldparam [Object] item An item in the list
+    # @yieldreturn [Object] The value returned from the pivot block will serve as the key in the pivot results
+    # @return [Hash] The pivoted results
+    def pivot(list, options={}, &block)
+      pivoted = {}
+      list.each do |item|
+        value = yield(item)
+
+        # notify observers that a pivot block was just called
+        identifier = options[:identifier] || "#{item.hash}:#{block.hash}"
+        changed
+        notify_observers(identifier, item, value) 
+
+        if value.is_a?(Array)
+          if value.empty?
+            pivoted[nil] ||= []
+            pivoted[nil] << item 
+          else
+            value.each do |val|
+              pivoted[val] ||= []
+              pivoted[val] << item 
+            end
+          end
+        else
+          pivoted[value] ||= []
+          pivoted[value] << item 
+        end
+      end
+
+      pivoted
+    end    
+
+    # Runs multiple pivots against a list of Objects.
+    #
+    # @example Multi-pivot a list of numbers
+    #   list = [1,2,3,4,5,6,7,8,9]
+    #   pivots = []
+    #
+    #   pivots << lambda do |i|
+    #     key = "less than or equal to 5" if i <= 5
+    #     key ||= "greater than 5"
+    #   end
+    #
+    #   pivots << lambda do |i|
+    #     key = "greater than or equal to 3" if i >= 3
+    #     key ||= "less than 3"
+    #   end
+    # 
+    #   # note the last pivot is an options Hash
+    #   pivots << {:delimiter => " & "}
+    #    
+    #   pivoter = One::Pivot.new
+    #   result = pivoter.multi_pivot(list, *pivots) 
+    #   
+    #   # the result will be a Hash with the following structure
+    #   {
+    #     "less than or equal to 5 & greater than or equal to 3" => [3, 4, 5], 
+    #     "less than or equal to 5 & less than 3" => [1, 2], 
+    #     "greater than 5 & greater than or equal to 3" => [6, 7, 8, 9]
+    #   }
+    #
+    # @param [Array<Object>] list The list to run the pivots against
+    # @param [Array<Proc, One::Pivot>] pivots An argument list that accepts N number of pivots.<br />
+    #   The last pivot in the list can be an options Hash for the multi_pivot operation.<br />
+    #   Supported options are:<br />
+    #   * :delimiter, The delimiter to use between pivot keys.  Defaults to '[PIVOT]']
+    # @return [Hash] The pivoted results
+    def multi_pivot(list, *pivots)
+      options = pivots.pop if pivots.last.is_a?(Hash)
+      options ||= {}
+      delimiter = options[:delimiter] || "[PIVOT]"
+      pivoted = nil
+      pass = 0
+
+      while pivots.length > 0
+        p = pivots.shift
+        
+        # handle the case where the pivots are One::Pivot objects
+        pivot_options = {}
+        if p.is_a?(One::Pivot)
+          pivot_options[:identifier] = p.identifier
+          p = p.pivot_proc
+        end
+
+        if pass == 0
+          pivoted = pivot(list, pivot_options, &p)
+        else
+          new_pivoted = {}
+          pivoted.each do |old_key, old_list|
+            tmp_pivoted = pivot(old_list, pivot_options, &p)
+            tmp_pivoted.each do |key, list|
+              new_key = "#{safe_key(old_key)}#{delimiter}#{safe_key(key)}"
+              new_pivoted[new_key] = list
+            end
+          end
+          pivoted = new_pivoted
+        end
+
+        pass += 1
+      end
+
+      pivoted
+    end
+
+    private
+
+    def safe_key(key)
+      key = "nil" if key.to_s.strip.empty?
+      key.to_s
+    end
+
+  end
+end
+

data/test/pivot_test.rb

@@ -0,0 +1,29 @@
+require File.expand_path(File.join(File.dirname(__FILE__), 'test_helper'))
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'one', 'pivot'))
+
+class PivotTest < Test::Unit::TestCase
+
+  context "A Pivot instance" do
+ 
+    should "expect an identifier passed to construct" do
+      assert_raise ArgumentError do
+        One::Pivot.new
+      end
+    end
+ 
+    should "expect a block to construct" do 
+      assert_raise LocalJumpError do 
+        One::Pivot.new :test
+      end
+    end
+
+    should "store the identifier and pivot proc correctly" do 
+      block = lambda {|item| item.class.name }
+      instance = One::Pivot.new(:test, &block)
+      assert_equal :test, instance.identifier      
+      assert_equal block, instance.pivot_proc
+    end
+
+  end
+
+end

data/test/pivoter_test.rb

@@ -0,0 +1,268 @@
+require File.expand_path(File.join(File.dirname(__FILE__), 'test_helper'))
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'one', 'pivot'))
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'one', 'pivoter'))
+
+class PivotTest < Test::Unit::TestCase
+
+  context "A One::Pivot instance" do
+    setup do
+      @pivoter = One::Pivoter.new
+    end
+
+    should "pivot a simple array properly" do
+      list = [1,2,3,4,5,6,7,8,9]
+      result = @pivoter.pivot(list) {|item| item <= 5}
+      assert_equal [6,7,8,9], result[false]
+      assert_equal [1,2,3,4,5], result[true] 
+    end
+
+    should "multi pivot a simple array properly" do 
+      list = [1,2,3,4,5,6,7,8,9]
+      pivots = []
+    
+      pivots << lambda do |i|
+        key = "less than or equal to 5" if i <= 5
+        key ||= "greater than 5"
+      end
+    
+      pivots << lambda do |i|
+        key = "greater than or equal to 3" if i >= 3
+        key ||= "less than 3"
+      end
+        
+      pivots << {:delimiter => " & "}
+
+      result = @pivoter.multi_pivot(list, *pivots)
+       
+      # the result will be a Hash with the following structure:
+      hash = {
+        "less than or equal to 5 & greater than or equal to 3" => [3, 4, 5], 
+        "less than or equal to 5 & less than 3" => [1, 2], 
+        "greater than 5 & greater than or equal to 3" => [6, 7, 8, 9]
+      } 
+
+      assert_equal hash, result
+    end
+
+    should "support both procs and One::Pivot objects with multi_pivot" do
+      list = [1,2,3,4,5,6,7,8,9]
+      pivots = []
+    
+      pivots << One::Pivot.new("comparison to 5") do |i|
+        key = "less than or equal to 5" if i <= 5
+        key ||= "greater than 5"
+      end
+    
+      pivots << One::Pivot.new("comparison to 3") do |i|
+        key = "greater than or equal to 3" if i >= 3
+        key ||= "less than 3"
+      end
+        
+      pivots << {:delimiter => " & "}
+
+      result = @pivoter.multi_pivot(list, *pivots)
+       
+      # the result will be a Hash with the following structure:
+      hash = {
+        "less than or equal to 5 & greater than or equal to 3" => [3, 4, 5], 
+        "less than or equal to 5 & less than 3" => [1, 2], 
+        "greater than 5 & greater than or equal to 3" => [6, 7, 8, 9]
+      } 
+
+      assert_equal hash, result
+    end
+
+    should "support pivot observers (for example: to perform caching)" do
+      # Pivot operations can be expensive.
+      # 
+      # Demonstrate how you can use the observer pattern to cache
+      # pivot results per item to save time on subsequent pivots for the same item.
+      # 
+      # This strategy can be helpful if each item remains in memory for a period of time 
+      # that spans its participation in several pivot calls
+
+      # extend Fixnum so we can cache pivot results
+      Fixnum.class_eval do
+        def pivot_cache
+          @pivot_cache ||= {}
+        end
+      end
+
+      assert 1.respond_to?(:pivot_cache)
+
+      # create a pivot observer that caches pivot results per item
+      class PivotObserver
+        def initialize(pivoter)
+          pivoter.add_observer(self)
+        end
+
+        # this method gets invoked by the pivot object whenever a pivot block is executed
+        def update(identifier, item, value)
+          item.pivot_cache[identifier] = value
+        end 
+      end 
+
+      observer = PivotObserver.new(@pivoter)
+  
+      list = [1,2,3,4,5,6,7,8,9]
+      result = @pivoter.pivot(list, :identifier => :less_than_5) do |item|
+        if item.pivot_cache.has_key?(:less_than_5)
+          raise Exception.new("Attempting to use a cached value that shouldn't exist")
+        else
+          item <= 5
+        end
+      end
+
+      list.each do |item|
+        assert item.pivot_cache.has_key?(:less_than_5)
+      end
+     
+      # pivot again but this time use the pivot cache stored on each item 
+      cached_result = @pivoter.pivot(list, :identifier => :less_than_5) do |item|
+        if item.pivot_cache.has_key?(:less_than_5)
+          item.pivot_cache[:less_than_5]
+        else
+          raise Exception.new("Attempting to calculate a value that should be cached")
+        end
+      end
+
+      assert_equal result, cached_result
+    end
+
+    should "support pivot observers when using multi_pivot (for example: to perform caching)" do
+      # Pivot operations can be expensive.
+      # 
+      # Demonstrate how you can use the observer pattern to cache
+      # pivot results per item to save time on subsequent pivots for the same item.
+      # 
+      # This strategy can be helpful if each item remains in memory for a period of time 
+      # that spans its participation in several pivot calls
+
+      # extend Fixnum so we can cache pivot results
+      Fixnum.class_eval do
+        def pivot_cache
+          @pivot_cache ||= {}
+        end
+      end
+
+      assert 1.respond_to?(:pivot_cache)
+
+      # create a pivot observer that caches pivot results per item
+      class PivotObserver
+        def initialize(pivoter)
+          pivoter.add_observer(self)
+        end
+
+        # this method gets invoked by the pivot object whenever a pivot block is executed
+        def update(identifier, item, value)
+          item.pivot_cache[identifier] = value
+        end 
+      end 
+
+      observer = PivotObserver.new(@pivoter)
+  
+      list = [1,2,3,4,5,6,7,8,9]
+
+      pivots = []
+    
+      pivots << One::Pivot.new("comparison to 5") do |i|
+        key = "less than or equal to 5" if i <= 5
+        key ||= "greater than 5"
+      end
+    
+      pivots << One::Pivot.new("comparison to 3") do |i|
+        key = "greater than or equal to 3" if i >= 3
+        key ||= "less than 3"
+      end
+
+      result = @pivoter.multi_pivot(list, *pivots) 
+
+      list.each do |item|
+        assert item.pivot_cache.has_key?("comparison to 5")
+        assert item.pivot_cache.has_key?("comparison to 3")
+      end
+     
+      # pivot again but this time use the pivot cache stored on each item 
+      pivots = []
+    
+      pivots << One::Pivot.new("comparison to 5") do |i|
+        i.pivot_cache["comparison to 5"]
+      end
+    
+      pivots << One::Pivot.new("comparison to 3") do |i|
+        i.pivot_cache["comparison to 3"]
+      end
+
+      cached_result = @pivoter.multi_pivot(list, *pivots) 
+      assert_equal result, cached_result
+    end
+
+    context "working on complex data structures" do
+
+      setup do
+        users = []
+        users << {:name => "Frank", :gender => "M", :roles => []}
+        users << {:name => "Joe", :gender => "M", :roles => []}
+        users << {:name => "John", :gender => "M", :roles => []}
+        users << {:name => "Sally", :gender => "F", :roles => []}
+
+        # assign some roles to the users
+
+        # Frank gets Read
+        users[0][:roles] << "Read"
+       
+        # Joe gets Write
+        users[1][:roles] << "Write" 
+
+        # John gets Read & Write
+        users[2][:roles] << "Read" 
+        users[2][:roles] << "Write"
+
+        # Sally gets no roles
+       
+        @users = users
+      end
+
+      should "pivot Array values individually using a nil key for empty Arrays" do
+        result = @pivoter.pivot(@users) {|user| user[:roles]}
+
+        # this is what the resulting hash should look like:
+        hash = {
+          nil => [
+            {:name=>"Sally", :gender => "F", :roles=>[]}], 
+          "Read" => [
+            {:name=>"Frank", :gender => "M", :roles=>["Read"]}, 
+            {:name=>"John", :gender => "M", :roles=>["Read", "Write"]}], 
+          "Write" => [
+            {:name=>"Joe", :gender => "M", :roles=>["Write"]}, 
+            {:name=>"John", :gender => "M", :roles=>["Read", "Write"]}]
+        }
+        
+        assert_equal hash, result
+      end
+
+      should "stack pivots with multi_pivot" do
+        pivots = []
+        pivots << lambda {|user| user[:gender]}
+        pivots << lambda {|user| user[:roles]}
+        
+        result = @pivoter.multi_pivot(@users, *pivots)
+
+        # this is what the resulting hash should look like
+        hash = {
+          "M[PIVOT]Write" => [
+            {:name=>"Joe", :gender=>"M", :roles=>["Write"]}, 
+            {:name=>"John", :gender=>"M", :roles=>["Read", "Write"]}], 
+          "M[PIVOT]Read" => [
+            {:name=>"Frank", :gender=>"M", :roles=>["Read"]}, 
+            {:name=>"John", :gender=>"M", :roles=>["Read", "Write"]}], 
+          "F[PIVOT]nil" => [
+            {:name=>"Sally", :gender=>"F", :roles=>[]}]
+        }
+              
+        assert_equal hash, result
+      end
+
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,2 @@
+require 'rubygems'
+require 'shoulda'

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification 
+name: one-pivot
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.9.2
+platform: ruby
+authors: 
+- Nathan Hopkins
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-02-23 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: shoulda
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        version: 2.11.3
+  type: :development
+  version_requirements: *id001
+description: "    Pivot provides basic pivoting functionality for sorting an Array of objects.\n"
+email: 
+- natehop@gmail.com
+- natehop@1on1.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/one/pivot.rb
+- lib/one/pivoter.rb
+- lib/one-pivot.rb
+- Gemfile
+- Gemfile.lock
+- Rakefile
+- README.md
+- test/pivot_test.rb
+- test/pivoter_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: https://github.com/one-on-one/pivot
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.5.2
+signing_key: 
+specification_version: 3
+summary: Pivot provides basic pivoting functionality for sorting an Array of objects.
+test_files: []
+