grouped_scope 0.6.1 → 3.1.0

data/.travis.yml

@@ -0,0 +1,5 @@
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - ree

data/CHANGELOG

@@ -1,6 +1,19 @@
 
 = master
 
+= 3.1.0 (unreleased)
+
+* Works with ActiveRecord 3.1
+
+* The group object is now an ActiveRecord::Relation so you can further scope it.
+
+* New group scoped #blank? and #present? which simply checks if the proxy owner has a group set.
+  This allows us to tune the SQL generated to IN statements only when needed, even if a grouped 
+  scope is being used.
+
+* New group.ids_sql which is an Arel SQL literal. Avoids large groups IDs and better query plans.
+
+
 = 0.6.0 (May 06, 2009)
 
 * ActiveRecord 2.3.14 compatibility.

data/Gemfile

@@ -7,16 +7,14 @@ ar_version = spec.dependencies.detect{ |d|d.name == 'activerecord' }.requirement
 
 gem 'sqlite3', '1.3.4'
 gem 'activerecord', ar_version, :require => 'active_record'
-gem 'will_paginate', '2.3.16'
 
 group :development do
-  gem 'rake', '0.8.7'
+  gem 'rake', '~> 0.9.2'
 end
 
 group :test do
-  gem 'minitest', '2.5.1'
-  gem 'mini_shoulda', '0.4.0'
-  gem 'factory_girl', '2.1.0'
-  gem 'mocha', '0.10.0'
+  gem 'minitest',     '~> 2.8.1'
+  gem 'factory_girl', '~> 2.3.2'
+  gem 'mocha',        '~> 0.10.0'
 end
 

data/README.md

@@ -0,0 +1,173 @@
+
+# GroupedScope: Has Many Associations IN (GROUPS)
+
+<img src="http://metaskills.net/assets/jack.png" alt="Jack Has Many Things" width="320" height="214" style="float:right; margin:0 0 15px 15px; background-color:#fff; padding:13px;">
+
+GroupedScope provides an easy way to group objects and to allow those groups to share association collections via existing `has_many` relationships. You may enjoy my original article titled [*Jack has_many :things*](http://metaskills.net/2008/09/28/jack-has_many-things/).
+
+
+## Installation
+
+Install the gem with bundler. We follow a semantic versioning format that tracks ActiveRecord's minor version. So this means to use the latest 3.1.x version of GroupedScope with any ActiveRecord 3.1 version.
+
+```ruby
+gem 'grouped_scope', '~> 3.1.0'
+```
+
+
+## Setup
+
+To use GroupedScope on a model it must have a `:group_id` column.
+
+```ruby
+class AddGroupId < ActiveRecord::Migration
+  def up
+    add_column :employees, :group_id, :integer
+  end
+  def down
+    remove_column :employees, :group_id
+  end
+end
+```
+
+
+## General Usage
+
+Assume the following model.
+
+```ruby
+class Employee < ActiveRecord::Base
+  has_many :reports
+  grouped_scope :reports
+end
+```
+
+By calling grouped_scope on any association you create a new group accessor for each 
+instance. The object returned will act just like an array and at least include the 
+current object that called it.
+
+```ruby
+@employee_one.group   # => [#<Employee id: 1, group_id: nil>]
+```
+
+To group resources, just assign the same `:group_id` to each record in that group.
+
+```ruby
+@employee_one.update_attribute :group_id, 1
+@employee_two.update_attribute :group_id, 1
+@employee_one.group   # => [#<Employee id: 1, group_id: 1>, #<Employee id: 2, group_id: 1>]
+```
+
+Calling grouped_scope on the :reports association leaves the existing association intact.
+
+```ruby
+@employee_one.reports  # => [#<Report id: 2, employee_id: 1>]
+@employee_two.reports  # => [#<Report id: 18, employee_id: 2>, #<Report id: 36, employee_id: 2>]
+```
+
+Now the good part, all associations passed to the grouped_scope method can be called 
+on the group proxy. The collection will return resources shared by the group.
+
+```ruby
+@employee_one.group.reports # => [#<Report id: 2, employee_id: 1>, 
+                                  #<Report id: 18, employee_id: 2>, 
+                                  #<Report id: 36, employee_id: 2>]
+```
+
+You can even call scopes or association extensions defined on the objects in the collection
+defined on the original association. For instance:
+
+```ruby
+@employee.group.reports.urgent.assigned_to(user)
+```
+
+
+## Advanced Usage
+
+The group scoped object can respond to either `blank?` or `present?` which checks the group's 
+target `group_id` presence or not. We use this internally so that grouped scopes only use grouping
+SQL when absolutely needed.
+
+```ruby
+@employee_one = Employee.create :group_id => nil
+@employee_two = Employee.create :group_id => 38
+
+@employee_one.group.blank?   # => true
+@employee_two.group.present? # => true
+```
+
+The object returned by the `#group` method is an ActiveRecord relation on the targets class, 
+in this case `Employee`. Given this, you can further scope the grouped proxy if needed. Below,
+we use the `:email_present` scope to refine the group down.
+
+```ruby
+class Employee < ActiveRecord::Base
+  has_many :reports
+  grouped_scope :reports
+  scope :email_present, where("email IS NOT NULL")
+end
+
+@employee_one = Employee.create :group_id => 5, :name => 'Ken'
+@employee_two = Employee.create :group_id => 5, :name => 'MetaSkills', :email => 'ken@metaskills.net'
+
+# Only one employee is returned now.
+@employee_one.group.email_present # => [#<Employee id: 1, group_id: 5, name: 'MetaSkills', email: 'ken@metaskills.net']
+```
+
+We always use raw SQL to get the group ids vs. mapping them to an array and using those in scopes. 
+This means that large groups can avoid pushing down hundreds of keys in SQL form. So given an employee
+with a `group_id` of `43` and calling `@employee.group.reports`, you would get something similar to
+the following SQL.
+
+```sql
+SELECT "reports".* 
+FROM "reports"  
+WHERE "reports"."employee_id" IN (
+  SELECT "employees"."id" 
+  FROM "employees"  
+  WHERE "employees"."group_id" = 43
+)
+```
+
+You can pass the group scoped object as a predicate to ActiveRecord's relation interface. In past 
+versions, this would have treated the group object as an array of IDs. The new behavior is to return 
+a SQL literal to be used with IN statements. So note, the following would generate SQL similar to 
+the one above.
+
+```ruby
+Employee.where(:group_id => @employee.group).all
+```
+
+If you need more control and you are working with the group at a lower level, you can always 
+use the `#ids` or `#ids_sql` methods on the group.
+
+```ruby
+# Returns primary key array.
+@employee.group.ids # => [33, 58, 240]
+
+# Returns a Arel::Nodes::SqlLiteral object.
+@employee.group.ids_sql # => 'SELECT "employees"."id" FROM "employees"  WHERE "employees"."group_id" = 33'
+```
+
+
+## Todo List
+
+* Raise errors for :finder_sql/:counter_sql.
+* Add a user definable group_id schema.
+* Remove SelfGrouping#with_relation, has not yet proved useful.
+
+
+
+## Testing
+
+Simple! Just clone the repo, then run `bundle install` and `bundle exec rake`. The tests will begin to run. We also use Travis CI to run our tests too. Current build status is:
+
+[![Build Status](https://secure.travis-ci.org/metaskills/grouped_scope.png)](http://travis-ci.org/metaskills/grouped_scope)
+
+
+
+## License
+
+Released under the MIT license.
+Copyright (c) 2011 Ken Collins
+

data/lib/grouped_scope.rb

@@ -1,11 +1,11 @@
 require 'active_record/version'
 require 'grouped_scope/errors'
-require 'grouped_scope/grouping'
 require 'grouped_scope/self_grouping'
-require 'grouped_scope/association_reflection'
-require 'grouped_scope/class_methods'
-require 'grouped_scope/has_many_association'
-require 'grouped_scope/has_many_through_association'
-require 'grouped_scope/core_ext'
-require 'grouped_scope/version'
 
+require 'grouped_scope/arish/reflection'
+require 'grouped_scope/arish/associations/collection_association'
+require 'grouped_scope/arish/associations/builder/grouped_association'
+require 'grouped_scope/arish/associations/builder/grouped_collection_association'
+require 'grouped_scope/arish/associations/association_scope'
+require 'grouped_scope/arish/relation/predicate_builer'
+require 'grouped_scope/arish/base'

data/lib/grouped_scope/arish/associations/association_scope.rb

@@ -0,0 +1,90 @@
+module GroupedScope
+  module Arish
+    module Associations
+      class AssociationScope < ActiveRecord::Associations::AssociationScope
+        
+        
+        private
+        
+        # A direct copy of of ActiveRecord's AssociationScope#add_constraints. If this was 
+        # in chunks, it would be easier to hook into. This more elegant version which supers
+        # up will only work for the has_many. https://gist.github.com/1434980 
+        # 
+        # We will just have to monitor rails every now and then and update this. Thankfully this
+        # copy is only used in a group scope. FYI, our one line change is commented below.
+        def add_constraints(scope)
+          tables = construct_tables
+        
+          chain.each_with_index do |reflection, i|
+            table, foreign_table = tables.shift, tables.first
+        
+            if reflection.source_macro == :has_and_belongs_to_many
+              join_table = tables.shift
+        
+              scope = scope.joins(join(
+                join_table,
+                table[reflection.association_primary_key].
+                in(join_table[reflection.association_foreign_key])
+              ))
+        
+              table, foreign_table = join_table, tables.first
+            end
+        
+            if reflection.source_macro == :belongs_to
+              if reflection.options[:polymorphic]
+                key = reflection.association_primary_key(klass)
+              else
+                key = reflection.association_primary_key
+              end
+        
+              foreign_key = reflection.foreign_key
+            else
+              key         = reflection.foreign_key
+              foreign_key = reflection.active_record_primary_key
+            end
+        
+            conditions = self.conditions[i]
+        
+            if reflection == chain.last
+              # GroupedScope changed this line.
+              # scope = scope.where(table[key].eq(owner[foreign_key]))
+              scope = if owner.group.present?
+                        scope.where(table[key].in(owner.group.ids_sql))
+                      else
+                        scope.where(table[key].eq(owner[foreign_key]))
+                      end
+        
+              if reflection.type
+                scope = scope.where(table[reflection.type].eq(owner.class.base_class.name))
+              end
+        
+              conditions.each do |condition|
+                if options[:through] && condition.is_a?(Hash)
+                  condition = { table.name => condition }
+                end
+        
+                scope = scope.where(interpolate(condition))
+              end
+            else
+              constraint = table[key].eq(foreign_table[foreign_key])
+        
+              if reflection.type
+                type = chain[i + 1].klass.base_class.name
+                constraint = constraint.and(table[reflection.type].eq(type))
+              end
+        
+              scope = scope.joins(join(foreign_table, constraint))
+        
+              unless conditions.empty?
+                scope = scope.where(sanitize(conditions, table))
+              end
+            end
+          end
+        
+          scope
+        end
+
+      end
+    end
+  end
+end

data/lib/grouped_scope/arish/associations/builder/grouped_association.rb

@@ -0,0 +1,50 @@
+module GroupedScope
+  module Arish
+    module Associations
+      module Builder
+        class GroupedAssociation
+          
+          attr_reader :model, :ungrouped_name, :ungrouped_reflection, :grouped_name, :grouped_options
+          
+          def self.build(model, *association_names)
+            association_names.each { |ungrouped_name| new(model, ungrouped_name).build }
+          end
+          
+          def initialize(model, ungrouped_name)
+            @model = model
+            @ungrouped_name = ungrouped_name
+            @ungrouped_reflection = find_ungrouped_reflection
+            @grouped_name = :"grouped_scope_#{ungrouped_name}"
+            @grouped_options = copy_ungrouped_reflection_options
+          end
+          
+          def build
+            model.send(ungrouped_reflection.macro, grouped_name, grouped_options).tap do |grouped_reflection|
+              grouped_reflection.grouped_scope = true
+              model.grouped_reflections = model.grouped_reflections.merge(ungrouped_name => grouped_reflection)
+              define_grouped_scope_reader(model)
+            end
+          end
+          
+          
+          private
+          
+          def define_grouped_scope_reader(model)
+            model.send(:define_method, :group) do
+              @group ||= GroupedScope::SelfGroupping.new(self)
+            end
+          end
+          
+          def find_ungrouped_reflection
+            model.reflections[ungrouped_name]
+          end
+          
+          def copy_ungrouped_reflection_options
+            ungrouped_reflection.options.dup
+          end
+          
+        end
+      end
+    end
+  end
+end

data/lib/grouped_scope/arish/associations/builder/grouped_collection_association.rb

@@ -0,0 +1,32 @@
+module GroupedScope
+  module Arish
+    module Associations
+      module Builder
+        class GroupedCollectionAssociation < GroupedAssociation
+          
+          private
+          
+          def find_ungrouped_reflection
+            reflection = model.reflections[ungrouped_name]
+            if reflection.blank? || [:has_many, :has_and_belongs_to_many].exclude?(reflection.macro)
+              msg = "Cannot create a group scope for #{ungrouped_name.inspect}. Either the reflection is blank or not supported. " + 
+                    "Make sure to call grouped_scope after the association you are trying to extend has been defined."
+              raise ArgumentError, msg
+            end
+            reflection
+          end
+          
+          def copy_ungrouped_reflection_options
+            ungrouped_reflection.options.dup.tap do |options|
+              options[:class_name] = ungrouped_reflection.class_name
+              if ungrouped_reflection.source_reflection && options[:source].blank?  
+                options[:source] = ungrouped_reflection.source_reflection.name 
+              end
+            end
+          end
+          
+        end
+      end
+    end
+  end
+end

data/lib/grouped_scope/arish/associations/collection_association.rb

@@ -0,0 +1,25 @@
+module GroupedScope
+  module Arish
+    module Associations
+      module CollectionAssociation
+
+        extend ActiveSupport::Concern
+
+        module InstanceMethods
+          
+          def association_scope
+            if reflection.grouped_scope?
+              @association_scope ||= Associations::AssociationScope.new(self).scope if klass
+            else
+              super
+            end
+          end
+
+        end
+
+      end
+    end
+  end
+end
+
+ActiveRecord::Associations::CollectionAssociation.send :include, GroupedScope::Arish::Associations::CollectionAssociation

data/lib/grouped_scope/arish/base.rb

@@ -0,0 +1,24 @@
+module GroupedScope
+  module Arish
+    module Base
+
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :grouped_reflections, :instance_reader => false, :instance_writer => false
+        self.grouped_reflections = {}.freeze
+      end
+
+      module ClassMethods
+
+        def grouped_scope(*association_names)
+          Associations::Builder::GroupedCollectionAssociation.build(self, *association_names)
+        end
+
+      end
+
+    end
+  end
+end
+
+ActiveRecord::Base.send :include, GroupedScope::Arish::Base