has_finder 0.1.1 → 0.1.2

data/History.txt

@@ -1,4 +1,9 @@
-== 0.0.1 2007-08-26
+== 0.1.0 2007-08-26
 
 * 1 major enhancement:
   * Initial release
+
+== 0.1.2 2007-09-02
+
+* Fix for protected with_scope (using send)
+* README Documentation

data/README.txt

@@ -1 +1,98 @@
-README
+HasFinder is an extension to ActiveRecord that makes it easier than ever to create custom find and count queries.
+
+Let's start with an example. Suppose you have an Article model; some articles are published, some are popular. Let's declare finders for each of these notions. You may be tempted to write something like the following:
+
+    class Article < ActiveRecord::Base
+      def self.published
+        find(:all, :conditions => {:published => true})
+      end
+  
+      def self.popular
+        ...
+      end
+      ...
+    end
+
+But there are serious limitations to this approach. How do you find articles that are BOTH popular and published? How can you easily paginate published articles?
+
+# HasFinder Features
+
+Let's define the equivalent finders using my new plugin, has_finder:
+
+    class Article < ActiveRecord::Base
+      has_finder :published, :conditions => {:published => true}
+      has_finder :popular, :conditions => ...
+    end
+
+## Query Composition
+
+Now, you can elegantly compose queries:
+
+    Article.published.popular
+    
+This will return all articles that are both popular and published. 
+
+## Calculations and Nested Finds
+You can also easily paginate or call nested finders or do calculations:
+
+    Article.published.paginate(:page => 1)
+    Article.published.popular.count
+    Article.popular.find(:first)
+    Article.popular.find(:all, :conditions => {...})
+
+## Works with ActiveRecord `has_many` and `has_many :through` Associations
+Furthermore, without any additional work, these finders will work with ActiveRecord associations.
+
+    class User
+      has_many :articles
+    end
+
+    user.articles.popular.find(:first)
+    user.articles.published.popular.average(:view_count)
+
+## Finders are extendable just like ActiveRecord Associations
+
+    class Article
+      has_finder :unpublished :conditions => {:published => false} do
+        def published_all
+          find(:all).map(&:publish)
+        end
+      end
+    end
+
+Alternatively, you can use the :extend options:
+
+    class Article
+      has_finder :unpublished, :conditions => ..., :extend => MyExtensionModule
+    end
+
+## Finders behave just like ActiveRecord Associations
+
+For example, you can call #reload:
+
+    Article.published.popular.reload
+
+## Finders can take parameters
+
+    class Car
+      has_finder :colored, lambda {|color| { :conditions => {:color => color} } }
+    end
+
+    Car.colored('red').paginate(:page => 1)
+
+# What makes HasFinder better than alternatives like `scope_out` and `scoped_proxy`?
+
+There are already two plugins similar to HasFinder: [`scope_out`](http://code.google.com/p/scope-out-rails) and [`scoped_proxy`](http://www.neotrivium.com/blog/2007/4/4/out_of_the_scope_of_scope_out?language=en-US). Both of them are excellent. In fact, Scoped Proxy was the model for HasFinder. Unfortunately, neither plugin provided all of the features I desired. Scope-Out lacks on-the-fly composition, a nice way to call a nested find, or the ability to do arbitrary calculations. Scoped Proxy is great, but it doesn't work with regular ActiveRecord Associations, it is not extendable like ActiveRecord associations, and it doesn't behave exactly like a regular ActiveRecord Association. Neither of them work out of the box with will_paginate. For all of these reasons and more, I rolled my own. It's now available as a gem.
+
+# Installation
+
+    % gem install has_finder
+
+# Usage
+
+In environment.rb:
+
+    gem 'has_finder'
+    require 'has_finder'
+    
+See the examples above for usage.

data/lib/has_finder/has_finder.rb

@@ -25,7 +25,7 @@ module HasFinder
       elsif proxy_finder.finders.include?(method)
         finders[method].call(self, *args)
       else
-        proxy_finder.with_scope :find => proxy_scope do
+        proxy_finder.send(:with_scope, { :find => proxy_scope }) do
           proxy_finder.send(method, *args, &block)
         end
       end

data/lib/has_finder/version.rb

@@ -2,7 +2,7 @@ module HasFinder #:nodoc:
   module VERSION #:nodoc:
     MAJOR = 0
     MINOR = 1
-    TINY  = 1
+    TINY  = 2
 
     STRING = [MAJOR, MINOR, TINY].join('.')
   end

data/spec/rails/log/test.log

@@ -5818,3 +5818,97 @@ Spec::Rails::DSL::ViewExampleController: missing default helper path spec/rails/
   Property Load (0.000189)   SELECT * FROM properties WHERE (properties.being_id = 2) 
   Property Load (0.000211)   SELECT * FROM properties WHERE (( properties.being_id = 2 ) AND ( name LIKE 'r%' )) AND (properties.being_id = 2) 
   SQL (0.000097)   ROLLBACK
+Spec::Rails::DSL::HelperEvalContextController: missing default helper path spec/rails/dsl/helper_eval_context_helper
+Spec::Rails::DSL::ViewExampleController: missing default helper path spec/rails/dsl/view_example_helper
+  SQL (0.037990)   SET SQL_AUTO_IS_NULL=0
+  SQL (0.000119)   BEGIN
+  Being Load (0.004143)   SELECT * FROM beings 
+  Being Columns (0.013376)   SHOW FIELDS FROM beings
+  SQL (0.167181)   INSERT INTO beings (`country`, `race`) VALUES(NULL, NULL)
+  Being Load (0.000335)   SELECT * FROM beings 
+  Being Load (0.000250)   SELECT * FROM beings 
+  SQL (0.005772)   ROLLBACK
+  SQL (0.000080)   BEGIN
+  Being Load (0.000290)   SELECT * FROM beings 
+  Being Load (0.000245)   SELECT * FROM beings 
+  Being Load (0.000248)   SELECT * FROM beings LIMIT 1
+  Being Load (0.000225)   SELECT * FROM beings LIMIT 1
+  Being Load (0.000237)   SELECT * FROM beings 
+  SQL (0.033188)   SELECT count(*) AS count_all FROM beings 
+  SQL (0.000257)   SELECT count(*) AS count_all FROM beings 
+  Being Load (0.000259)   SELECT * FROM beings 
+  SQL (0.009529)   SELECT avg(id) AS avg_id FROM beings 
+  SQL (0.000269)   SELECT avg(id) AS avg_id FROM beings 
+  SQL (0.000165)   ROLLBACK
+  SQL (0.000415)   BEGIN
+  Being Load (0.000260)   SELECT * FROM beings 
+  Being Load (0.000217)   SELECT * FROM beings 
+  Being Load (0.000218)   SELECT * FROM beings 
+  Being Load (0.000220)   SELECT * FROM beings 
+  Being Load (0.000215)   SELECT * FROM beings 
+  Being Load (0.000213)   SELECT * FROM beings 
+  SQL (0.000145)   ROLLBACK
+  SQL (0.000084)   BEGIN
+  Being Load (0.001138)   SELECT * FROM beings WHERE (beings.`country` = 'greece') 
+  Being Load (0.000217)   SELECT * FROM beings WHERE (beings.`id` = 1) 
+  Being Load (0.000187)   SELECT * FROM beings WHERE (beings.`id` = 3) 
+  Being Load (0.000332)   SELECT * FROM beings WHERE (beings.`race` = 'mortal') 
+  Being Load (0.000200)   SELECT * FROM beings WHERE (beings.`id` = 2) 
+  SQL (0.000102)   ROLLBACK
+  SQL (0.000319)   BEGIN
+  Being Load (0.000223)   SELECT * FROM beings WHERE (beings.`country` = 'greece') LIMIT 1
+  Being Load (0.000192)   SELECT * FROM beings WHERE (beings.`id` = 1) 
+  SQL (0.000080)   ROLLBACK
+  SQL (0.000240)   BEGIN
+  Being Load (0.000213)   SELECT * FROM beings WHERE (beings.`country` = 'greece') 
+  Being Load (0.025420)   SELECT * FROM beings WHERE (( ( beings.`country` = 'greece' ) AND ( beings.`race` = 'mortal' ) ) AND ( beings.`country` = 'greece' )) 
+  Being Load (0.000303)   SELECT * FROM beings WHERE (beings.`id` = 1) 
+  SQL (0.000167)   ROLLBACK
+  SQL (0.000085)   BEGIN
+  Being Load (0.000283)   SELECT * FROM beings WHERE (beings.`country` = 'greece') 
+  Being Load (0.000189)   SELECT * FROM beings WHERE (beings.`id` = 1) 
+  Being Load (0.000168)   SELECT * FROM beings WHERE (beings.`id` = 3) 
+  Being Load (0.000197)   SELECT * FROM beings WHERE (beings.`country` = 'greece') LIMIT 1
+  SQL (0.000098)   ROLLBACK
+  SQL (0.000083)   BEGIN
+  SQL (0.000084)   ROLLBACK
+  SQL (0.000262)   BEGIN
+  SQL (0.000087)   ROLLBACK
+  SQL (0.000259)   BEGIN
+  SQL (0.000085)   ROLLBACK
+  SQL (0.000064)   BEGIN
+  Property Load (0.000361)   SELECT * FROM properties WHERE (name LIKE 'r%') 
+  Property Columns (0.001772)   SHOW FIELDS FROM properties
+  Property Load (0.000655)   SELECT * FROM properties WHERE (properties.`id` = 1) 
+  Property Load (0.000228)   SELECT * FROM properties WHERE (properties.`id` = 2) 
+  Property Load (0.000213)   SELECT * FROM properties WHERE (properties.`id` = 3) 
+  Being Load (0.000238)   SELECT * FROM beings WHERE (beings.`id` = 2) 
+  Property Load (0.000230)   SELECT * FROM properties WHERE (properties.`id` = 4) 
+  Property Load (0.000244)   SELECT * FROM properties WHERE (properties.being_id = 2) 
+  Property Load (0.000266)   SELECT * FROM properties WHERE (( properties.being_id = 2 ) AND ( name LIKE 'r%' )) AND (properties.being_id = 2) 
+  SQL (0.000145)   ROLLBACK
+Spec::Rails::DSL::HelperEvalContextController: missing default helper path spec/rails/dsl/helper_eval_context_helper
+Spec::Rails::DSL::ViewExampleController: missing default helper path spec/rails/dsl/view_example_helper
+  SQL (0.000138)   SET SQL_AUTO_IS_NULL=0
+  SQL (0.000109)   BEGIN
+  SQL (0.000169)   ROLLBACK
+  SQL (0.000179)   BEGIN
+  SQL (0.000168)   ROLLBACK
+  SQL (0.000319)   BEGIN
+  SQL (0.000166)   ROLLBACK
+  SQL (0.000179)   BEGIN
+  SQL (0.000163)   ROLLBACK
+  SQL (0.000299)   BEGIN
+  SQL (0.000187)   ROLLBACK
+  SQL (0.000328)   BEGIN
+  SQL (0.000173)   ROLLBACK
+  SQL (0.000124)   BEGIN
+  SQL (0.000191)   ROLLBACK
+  SQL (0.000179)   BEGIN
+  SQL (0.000071)   ROLLBACK
+  SQL (0.000246)   BEGIN
+  SQL (0.000073)   ROLLBACK
+  SQL (0.000201)   BEGIN
+  SQL (0.000072)   ROLLBACK
+  SQL (0.000146)   BEGIN
+  SQL (0.000179)   ROLLBACK

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.9.0
 specification_version: 1
 name: has_finder
 version: !ruby/object:Gem::Version 
-  version: 0.1.1
-date: 2007-08-26 00:00:00 -07:00
+  version: 0.1.2
+date: 2007-09-02 00:00:00 -07:00
 summary: description of gem
 require_paths: 
 - lib