queryable 2.0.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d8c4dc189756585db85f2f5b335744291f4df89c
-  data.tar.gz: b23cb30e1e3030e1c3690110c44bb43372c97495
+  metadata.gz: 137ea28c0dc8498a7dcb8044dfe22916e852e058
+  data.tar.gz: 50a904195d630da9e2286397ac90ebd8d9ff0171
 SHA512:
-  metadata.gz: 2d9965e1bdeb3f9b542813a7f87c50cd45651c27ee0317e39940fddf780c4c355eba91bab4c69171c3e174564b538b4fbc55978ebcb4ca52536cabfae656e3fd
-  data.tar.gz: 69bc201f009943a2b2864a62bdfb37d30be70e64385b1f4e118d5a09b096e0920ef71a4ef6f3c05cbef817813896b12d81e2ac94cbc349fa69885c25e24f8870
+  metadata.gz: 0a71dee62ef6250e7e285935baa14b8bcfb336e5c862dab8a7528e12bbe486fd69a5f34e22abfb9bb6db2689710077d242d60e810b45f2b7c95400ce2cf6af33
+  data.tar.gz: d2ae50700d887071e93623387906cc62c36087918d45d64c1091999bea13621da380f9c1f047cb24e4fdf02f1d436ba62cb8ed94686dfe439ef0de2f7c1f1d1b

data/README.md

@@ -14,16 +14,6 @@ Queryable is a mixin that allows you to easily define query objects with chainab
 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
@@ -54,22 +44,10 @@ class CustomersQuery
   def miller_fans
     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)
-    search(field_values).current
-  end
-
-  scope :search_in_current
 end
 
 
-CustomerQuery.new(shop.customers).miller_fans.search_in_current(last_name: 'M')
+CustomerQuery.new(shop.customers).miller_fans
 ```
 
 ## Advantages
@@ -85,7 +63,7 @@ to check how to test query objects without even having to require the ORM/ODM, o
 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
+Besides Queryable, there are three 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).
 
@@ -152,6 +130,46 @@ BigCustomersQuery.new.queryable ==
 Customer.where(:last_purchase.gt => 7.days.ago, :total_expense.gt => 9999999)
 ```
 
+### Chainable 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 `chain` it. Chainable
+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.
+
+```ruby
+class CustomersQuery
+  include Queryable
+  include Queryable::Chainable
+
+  chain :active, :recent
+
+  def active
+    where(status: 'active')
+  end
+
+  def recent
+    queryable.desc(:logged_in_at)
+  end
+
+  chain def search(field_values)
+    field_values.inject(queryable) { |query, (field, value)|
+      query.where(field => /#{value}/i)
+    }
+  end
+
+  def search_in_active(field_values)
+    search(field_values).active
+  end
+end
+
+
+CustomerQuery.new(shop.customers).miller_fans.search_in_current(last_name: 'M')
+```
+
 ### 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.
@@ -162,9 +180,13 @@ require 'queryable/default_scope'
 
 def BaseQuery
   include Queryable
+  include Queryable::Chainable
   include Queryable::DefaultScope
   include Queryable::DefaultQuery
 
+  # If you want to be concise:
+  include Queryable::DefaultQuery, Queryable::DefaultScope, Queryable::Chainable, Queryable
+
   queryable false
 
   scope :recent, ->{ where(:created_at.gt => 1.week.ago) }

data/lib/queryable.rb

@@ -41,7 +41,8 @@ module Queryable
       methods.last.is_a?(Hash) ? super : def_delegators(:queryable, *methods)
     end
 
-    # Public: Defines a new scope method, or makes an existing method chainable.
+    # Public: Defines a new method that executes the passed proc or block in
+    # the context of the internal query object, and returns self.
     #
     # name - Name of the scope to define for this Queryable.
     #
@@ -63,51 +64,13 @@ module Queryable
     #     where(_type: "#{brand}ExtremelyFastRacingCar")
     #   end
     #
-    #   scope def search(field_values)
-    #     field_values.inject(query) { |query, (field, value)|
-    #       query.where(field => /#{value}/i)
-    #     }
-    #   end
-    #
     # Returns nothing.
     def scope(name, proc=nil, &block)
-      if method_defined?(name)
-        scope_method(name)
-      else
-        define_scope(name, proc || block)
-      end
-    end
-
-    private
-
-    # Internal: Defines a new method that executes the passed proc or block in
-    # the context of the internal query object, and returns self.
-    def define_scope(name, proc)
       define_method(name) do |*args|
-        @queryable = queryable.instance_exec *args, &proc
+        @queryable = queryable.instance_exec *args, &(proc || block)
         self
       end
     end
-
-    # Public: Makes an existing method chainable by intercepting the call, and
-    # storing the result as the internal query, and returning self.
-    def scope_method(name)
-      prepend Module.new.tap { |s| s.module_eval Queryable.scope_method(name) }
-    end
-  end
-
-  # Internal: Generates the scope interceptor method.
-  #
-  # name - Name of the method to convert to a scope.
-  #
-  # Returns a String with the code of the scope method.
-  def self.scope_method(name)
-    <<-SCOPE
-      def #{name}(*args)
-        @queryable = super
-        self
-      end
-    SCOPE
   end
 
   # Internal: Default methods to be delegated to the internal query.

data/lib/queryable/chainable.rb

@@ -0,0 +1,59 @@
+# Public: Provides a class method that allows a method to be chained.
+module Queryable
+  module Chainable
+
+    # Internal: Adds class methods, and default initialization.
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    # Internal: Contains the Chainable class methods.
+    module ClassMethods
+
+      # Public: Makes an existing method chainable by storing its return value
+      # as the internal query, and returning the query object itself.
+      #
+      # Examples:
+      #
+      #   chain :order_by_name
+      #
+      #   chain def search(field_values)
+      #     field_values.inject(query) { |query, (field, value)|
+      #       query.where(field => /#{value}/i)
+      #     }
+      #   end
+      def chain(*names)
+        prepend Module.new.tap { |m| Chainable.add_scope_methods(m, names) }
+      end
+
+    end
+
+    private
+
+    # Internal: Defines a scope method in the module per each name in the Array.
+    #
+    # mod - The Module where the scope methods will be added.
+    # names - Names of the methods to chain.
+    #
+    # Returns nothing.
+    def self.add_scope_methods(mod, names)
+      names.each do |name|
+        mod.module_eval Chainable.scope_method(name)
+      end
+    end
+
+    # Internal: Generates the scope interceptor method.
+    #
+    # name - Name of the method to convert to a scope.
+    #
+    # Returns a String with the code of the scope method.
+    def self.scope_method(name)
+      <<-SCOPE
+        def #{name}(*args)
+          @queryable = super
+          self
+        end
+      SCOPE
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: queryable
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.1.0
 platform: ruby
 authors:
 - Máximo Mussini
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-16 00:00:00.000000000 Z
+date: 2014-10-20 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.
@@ -21,6 +21,7 @@ extra_rdoc_files:
 files:
 - README.md
 - lib/queryable.rb
+- lib/queryable/chainable.rb
 - lib/queryable/default_query.rb
 - lib/queryable/default_scope.rb
 homepage: https://github.com/ElMassimo/queryable