queryable 2.0.0 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 28570cfafe1680583b92ea618a85cbca197f5c4b
-  data.tar.gz: 981e0042933205c1bf4c10daa8db4dcecec540f0
+  metadata.gz: d8c4dc189756585db85f2f5b335744291f4df89c
+  data.tar.gz: b23cb30e1e3030e1c3690110c44bb43372c97495
 SHA512:
-  metadata.gz: ecfd3bb32c31a300bd768cbf82d5f42628e1012259de2df4c174d68ad2ba368d2db4a0666dfb482ff7a94391dedbef9c6e658c3fba19a62c14ee2ff9fd2119ae
-  data.tar.gz: 318dea62093ecd3e8defe4e3b87bbf0b0a5169980164d5597e1ed51bfe06193a731d577bcf05a029b96fecd3939c518ac910e970e0606258ea44c31627831d91
+  metadata.gz: 2d9965e1bdeb3f9b542813a7f87c50cd45651c27ee0317e39940fddf780c4c355eba91bab4c69171c3e174564b538b4fbc55978ebcb4ca52536cabfae656e3fd
+  data.tar.gz: 69bc201f009943a2b2864a62bdfb37d30be70e64385b1f4e118d5a09b096e0920ef71a4ef6f3c05cbef817813896b12d81e2ac94cbc349fa69885c25e24f8870

data/README.md

@@ -2,15 +2,41 @@ Queryable
 =====================
 [![Gem Version](https://badge.fury.io/rb/queryable.svg)](http://badge.fury.io/rb/queryable)
 [![Build Status](https://travis-ci.org/ElMassimo/queryable.svg)](https://travis-ci.org/ElMassimo/queryable)
-[![Coverage Status](https://coveralls.io/repos/ElMassimo/queryable/badge.png)](https://coveralls.io/r/ElMassimo/queryable)
+[![Code Climate](https://codeclimate.com/github/ElMassimo/queryable.png)](https://codeclimate.com/github/ElMassimo/queryable)
 [![Inline docs](http://inch-ci.org/github/ElMassimo/queryable.svg)](http://inch-ci.org/github/ElMassimo/queryable)
-<!-- [![Code Climate](https://codeclimate.com/github/ElMassimo/queryable.png)](https://codeclimate.com/github/ElMassimo/queryable) -->
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/ElMassimo/queryable/blob/master/LICENSE.txt)
+<!-- [![Coverage Status](https://coveralls.io/repos/ElMassimo/queryable/badge.png)](https://coveralls.io/r/ElMassimo/queryable) -->
 
 Queryable is a mixin that allows you to easily define query objects with chainable scopes.
 
+### Scopes
+
+Scopes serve to encapsulate reusable business rules, a method is defined with
+the selected name and block (or proc)
+
+### Scopeable Methods
+
+While scopes are great because of their terseness, they can be limiting because
+the block executes in the context of the internal query, so methods, constants,
+and variables of the Queryable are not accessible.
+
+For those cases, you can use a normal method, and then `scope` it. Queryable
+will take care of setting the return value of the method as the internal query,
+and return `self` at the end to make the method chainable.
+
+### Delegation
+
+By default most Array methods are delegated to the internal query. It's possible
+to delegate extra methods to the query by calling `delegate`.
+```ruby
+def CustomersQuery
+  delegate :update_all, :destroy_all
+end
+```
+
 ## Usage
 ```ruby
-class CustomerQuery
+class CustomersQuery
   include Queryable
 
   scope(:recent) { desc(:logged_in_at) }
@@ -29,34 +55,23 @@ class CustomerQuery
     favourite_brand(:beer, :Miller)
   end
 
+  scope def search(field_values)
+    field_values.inject(customers) { |customers, (field, value)|
+      customers.where(field => /#{value}/i)
+    }
+  end
+
   def search_in_current(field_values)
-    define_query do |customers|
-      field_values.inject(customers) { |customers, (field, value)|
-        customers.where(field => /#{value}/i)
-      }
-    end.current
+    search(field_values).current
   end
+
+  scope :search_in_current
 end
 
 
 CustomerQuery.new(shop.customers).miller_fans.search_in_current(last_name: 'M')
 ```
 
-### Scopes
-
-Scopes serve to encapsulate reusable business rules, a method is defined with
-the selected name and block (or proc)
-
-### Define Query
-
-While scopes are great because of their terseness, they can be limiting because
-the block executes in the context of the internal query, so methods, constants,
-and variables of the Queryable are not accessible.
-
-For those cases, you can use `define_query`, which is a convenience setter for
-the internal query, that also takes care of returning `self` at the end of the
-call to make the methods chainable.
-
 ## Advantages
 
 * Query objects are easy to understand.
@@ -69,6 +84,97 @@ You can check the [specs](https://github.com/ElMassimo/queryable/tree/master/spe
 to check how to test query objects without even having to require the ORM/ODM, or
 you can test by requiring your ORM/ODM and executing queries as usual.
 
+## Optional Modules
+Besides Queryable, there are two opt-in modules that can help you when creating
+query objects. These modules would need to be manually required during app
+initialization or wherever necessary (in Rails, config/initializers).
+
+### DefaultQuery
+Provides default initialization for query objects, by attempting to infer the
+class name of the default collection for the query, and it also provides a
+`queryable` method to specify it.
+
+```ruby
+require 'queryable/default_query'
+
+def CustomersQuery
+  include Queryable
+  include Queryable::DefaultQuery
+end
+
+def OldCustomersQuery < CustomersQuery
+  queryable ArchivedCustomers
+end
+
+CustomersQuery.new.queryable == Customer.all
+OldCustomersQuery.new.queryable == ArchivedCustomers.all
+```
+If you want to use common base objects for your queries, you may want want to
+delay the automatic inference:
+```ruby
+class BaseQuery
+  include Queryable
+  include Queryable::DefaultQuery
+
+  queryable false
+end
+
+class CustomersQuery < BaseQuery
+end
+
+CustomersQuery.new.queryable == Customer.all
+```
+
+### DefaultScope
+Allows to define default scopes in query objects, and inherit them in query
+object subclasses.
+
+```ruby
+require 'queryable/default_scope'
+
+def CustomersQuery
+  include Queryable
+  include Queryable::DefaultScope
+  include Queryable::DefaultQuery
+
+  default_scope :active
+  scope :active, -> { where(:last_purchase.gt => 7.days.ago) }
+end
+
+def BigCustomersQuery < CustomersQuery
+  default_scope :big_spender
+  scope :big_spender, -> { where(:total_expense.gt => 9999999) }
+end
+
+CustomersQuery.new.queryable == Customer.where(:last_purchase.gt => 7.days.ago)
+
+BigCustomersQuery.new.queryable ==
+Customer.where(:last_purchase.gt => 7.days.ago, :total_expense.gt => 9999999)
+```
+
+### Notes
+To avoid repetition, it's a good idea to create a `BaseQuery` object
+to contain both the modules inclusion, and common scopes you may reuse.
+
+```ruby
+require 'queryable/default_query'
+require 'queryable/default_scope'
+
+def BaseQuery
+  include Queryable
+  include Queryable::DefaultScope
+  include Queryable::DefaultQuery
+
+  queryable false
+
+  scope :recent, ->{ where(:created_at.gt => 1.week.ago) }
+end
+
+def CustomersQuery < BaseQuery
+...
+end
+```
+
 ## RDocs
 
 You can view the **Queryable** documentation in RDoc format here:

data/lib/queryable.rb

@@ -18,7 +18,8 @@ module Queryable
     base.extend ClassMethods
     base.class_eval do
       # Public: Gets/Sets the internal query.
-      attr_accessor :query
+      attr_accessor :queryable
+      alias_method :query, :queryable
 
       # Internal: Delegates Array and Criteria methods to the internal query.
       delegate *Queryable.default_delegated_methods
@@ -29,7 +30,7 @@ module Queryable
   #
   # query - The internal query to build upon.
   def initialize(query)
-    @query = query.all
+    @queryable = query.all
   end
 
   # Internal: Contains the Queryable class methods.
@@ -37,7 +38,7 @@ module Queryable
 
     # Public: Delegates the specified methods to the internal query.
     def delegate(*methods)
-      methods.last.is_a?(Hash) ? super : def_delegators(:query, *methods)
+      methods.last.is_a?(Hash) ? super : def_delegators(:queryable, *methods)
     end
 
     # Public: Defines a new scope method, or makes an existing method chainable.
@@ -83,7 +84,7 @@ module Queryable
     # the context of the internal query object, and returns self.
     def define_scope(name, proc)
       define_method(name) do |*args|
-        @query = query.instance_exec *args, &proc
+        @queryable = queryable.instance_exec *args, &proc
         self
       end
     end
@@ -103,7 +104,7 @@ module Queryable
   def self.scope_method(name)
     <<-SCOPE
       def #{name}(*args)
-        @query = super
+        @queryable = super
         self
       end
     SCOPE

data/lib/queryable/default_query.rb

@@ -28,12 +28,14 @@ module Queryable
         queryable_class.all
       end
 
-      # Internal: The default table or collection for this query object.
-      # Provides a default based on a convention of the query object name.
+      # Internal: Attempts to use the parent query collection (if any), and
+      # provides a default based on a convention of the query object name.
       def queryable_class
-        @queryable_class ||= if superclass.respond_to?(:queryable_class)
+        unless defined?(@queryable_class)
+          @queryable_class = superclass.respond_to?(:queryable_class) &&
           superclass.queryable_class || Object.const_get(name.gsub('sQuery', ''))
         end
+        @queryable_class
       end
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: queryable
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.0.1
 platform: ruby
 authors:
 - Máximo Mussini
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-12 00:00:00.000000000 Z
+date: 2014-08-16 00:00:00.000000000 Z
 dependencies: []
 description: Queryable is a module that encapsulates query building so you don't have
   to tuck scopes inside your models.
@@ -49,3 +49,4 @@ signing_key:
 specification_version: 4
 summary: Keep your scopes and queries flexible by using Ruby
 test_files: []
+has_rdoc: