paraphrase 0.3.1 → 0.3.2

data/CHANGELOG

@@ -1,3 +1,13 @@
+0.3.2 / 7-5-2012
+
+* Cache Query#results
+* Setup Query#method_missing to proxy to Query#results
+* Setup Query#respond_to? to check Query#results
+
+0.3.1 / 7-5-2012
+
+* Fix for rails 3.0
+
 0.3.0 / 7-5-2012
 
 * Allow nil values to be passed to scoped using :allow_nil option.

data/README.md

@@ -3,10 +3,9 @@
 paraphrase provides a way to map one or multiple request params to model
 scopes.
 
-paraphrase was designed and geared towards building a query-based public API
-where you may want to require certain parameters to prevent consumers from
-scraping all your information or to mitigate the possibility of large,
-performance-intensive data-dumps.
+paraphrase is geared towards building a query-based public API where you may
+want to require certain parameters to prevent consumers from scraping all your
+information or to mitigate large, performance-intensive database queries.
 
 ## Installation
 
@@ -28,8 +27,12 @@ $ gem install paraphrase
 
 ## Usage
 
-paraphrase aims to be as flexible as possible for your needs.
-* From within an `ActiveRecord::Base` subclass:
+### Setup
+
+paraphrase aims to be as flexible as possible. `Query` classes can be created
+in the following ways:
+
+* Calling `register_mapping` in an `ActiveRecord::Base` subclass:
 
 ```ruby
 class Post < ActiveRecord::Base
@@ -43,7 +46,7 @@ class Post < ActiveRecord::Base
 end
 ```
 
-* In an initializer to register multiple mappings in one place:
+* A configuration block through `Paraphrase.configure`:
 
 ```ruby
 # config/initializers/paraphrase.rb
@@ -56,7 +59,7 @@ Paraphrase.configure do |mappings|
 end
 ```
 
-* By creating a subclass of `Paraphrase::Query`:
+* Subclassing `Paraphrase::Query`:
 
 ```ruby
 class PostQuery < Paraphrase::Query
@@ -66,16 +69,15 @@ class PostQuery < Paraphrase::Query
 end
 ```
 
-Then in a controller you can use it in any of the following ways:
+### Making a Query
+
+In your controller, call the relevant method based on your setup:
 
 ```ruby
 class PostsController < ApplicationController
   respond_to :html, :json
 
   def index
-    # Filters out relevant attributes
-    # and applies scopes relevant to each
-    # parameter
     @posts = Post.paraphrase(params)
 
     # Or
@@ -89,44 +91,58 @@ class PostsController < ApplicationController
 end
 ```
 
+### Configuring Scopes
+
 In any of these contexts, the `:key` option of the `:scope` method registers
-attribute(s) to extract from the params supplied and what scope to pass them
-to. An array of keys can be supplied to pass multiple attributes to a scope.
+attribute(s) to extract from the params supplied and what method to pass them
+to. An array of keys can be supplied to pass multiple arguments to a scope.
 
 ```ruby
 class Post < ActiveRecord::Base
   register_mapping do
     scope :by_user, :key => [:first_name, :last_name]
+    scope :published_on, :key => :pub_date
+  end
+
+  def self.by_user(first_name, last_name)
+    joins(:user).where(:user => { :first_name => first_name, :last_name => last_name })
   end
 
-  def self.by_user(name)
-    joins(:user).where(:user => { :name => name })
+  def self.published_on(pub_date)
+    where(:published_on => pub_date)
   end
 end
 ```
 
-If a key is required, pass `:require => true` to the options. This will
-return an empty results set if value for that key is missing.
+If a scope is required for a query to be considered valid, pass `:require =>
+true` or `:require => [:array, :of, :keys]` to the options. If any values are
+missing for the scope, an empty result set will be returned. If a key is an
+array of attributes, you can specify a subset of the key to be required. The
+rest of the attributes will be allowed to be nil.
 
 ```ruby
 class Post < ActiveRecord::Base
   register_mapping do
-    scope :by_author, :key => :author, :require => true
-    scope :published_after, :key => :pub_date
+    scope :published_on, :key => :pub_date, :require => true
+    scope :by_author, :key => [:first_name, :last_name], :require => :last_name # requires :last_name, whitelists :first_name
   end
 end
 
-Post.paraphrase(:pub_date => '2010-10-30') # => []
+Post.paraphrase.results # => []
 ```
 
-## Plans
-
-* Enable requiring a subset of a compound key.
+Alternatively, a scope can be whitelisted allowing nil values to be passed to the scope.
 
 ```ruby
-scope :by_author, :key => [:first_name, :last_name], :require => :first_name
+class Post < ActiveRecord::Base
+  register_mapping do
+    scope :by_author, :key => [:first_name, :last_name], :allow_nil => :first_name # :first_name does not need to be specified
+  end
+end
 ```
 
+## Plans / Thoughts for the Future
+
 * Support nested hashes in params.
 
 ```ruby

data/gemfiles/3.0.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: /Users/edd_d/src/paraphrase
   specs:
-    paraphrase (0.3.0)
+    paraphrase (0.3.2)
       activemodel (~> 3.0)
       activerecord (~> 3.0)
       activesupport (~> 3.0)

data/gemfiles/3.1.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: /Users/edd_d/src/paraphrase
   specs:
-    paraphrase (0.3.0)
+    paraphrase (0.3.2)
       activemodel (~> 3.0)
       activerecord (~> 3.0)
       activesupport (~> 3.0)

data/gemfiles/3.2.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: /Users/edd_d/src/paraphrase
   specs:
-    paraphrase (0.3.0)
+    paraphrase (0.3.2)
       activemodel (~> 3.0)
       activerecord (~> 3.0)
       activesupport (~> 3.0)

data/lib/paraphrase/query.rb

@@ -73,11 +73,29 @@ module Paraphrase
     #
     # @return [ActiveRecord::Relation, Array]
     def results
-      results ||= scopes.inject(source) do |query, scope|
-        scope.chain(self, @params, query)
-      end
+      @results ||= begin
+                     results = scopes.inject(source) do |query, scope|
+                       scope.chain(self, @params, query)
+                     end
+
+                     @errors.any? ? [] : results
+                   end
+    end
+
 
-      @results = @errors.any? ? [] : results
+    def respond_to?(name)
+      super || results.respond_to?(name)
+    end
+
+    protected
+
+    def method_missing(name, *args, &block)
+      if results.respond_to?(name)
+        self.class.delegate name, :to => :results
+        results.send(name, *args, &block)
+      else
+        super
+      end
     end
   end
 end

data/lib/paraphrase/version.rb

@@ -1,3 +1,3 @@
 module Paraphrase
-  VERSION = "0.3.1"
+  VERSION = "0.3.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paraphrase
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ date: 2012-07-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
-  requirement: &70300799182120 !ruby/object:Gem::Requirement
+  requirement: &70289301081080 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: '3.0'
   type: :runtime
   prerelease: false
-  version_requirements: *70300799182120
+  version_requirements: *70289301081080
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &70300799180260 !ruby/object:Gem::Requirement
+  requirement: &70289301078480 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +32,10 @@ dependencies:
         version: '3.0'
   type: :runtime
   prerelease: false
-  version_requirements: *70300799180260
+  version_requirements: *70289301078480
 - !ruby/object:Gem::Dependency
   name: activemodel
-  requirement: &70300799177960 !ruby/object:Gem::Requirement
+  requirement: &70289301077280 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -43,10 +43,10 @@ dependencies:
         version: '3.0'
   type: :runtime
   prerelease: false
-  version_requirements: *70300799177960
+  version_requirements: *70289301077280
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &70300799176700 !ruby/object:Gem::Requirement
+  requirement: &70289301067840 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -54,10 +54,10 @@ dependencies:
         version: '1.0'
   type: :development
   prerelease: false
-  version_requirements: *70300799176700
+  version_requirements: *70289301067840
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &70300799167400 !ruby/object:Gem::Requirement
+  requirement: &70289301066540 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -65,10 +65,10 @@ dependencies:
         version: '0.7'
   type: :development
   prerelease: false
-  version_requirements: *70300799167400
+  version_requirements: *70289301066540
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70300799166180 !ruby/object:Gem::Requirement
+  requirement: &70289301064900 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -76,10 +76,10 @@ dependencies:
         version: '2.10'
   type: :development
   prerelease: false
-  version_requirements: *70300799166180
+  version_requirements: *70289301064900
 - !ruby/object:Gem::Dependency
   name: redcarpet
-  requirement: &70300799164540 !ruby/object:Gem::Requirement
+  requirement: &70289301064000 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -87,10 +87,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70300799164540
+  version_requirements: *70289301064000
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70300799163600 !ruby/object:Gem::Requirement
+  requirement: &70289301063120 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -98,10 +98,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70300799163600
+  version_requirements: *70289301063120
 - !ruby/object:Gem::Dependency
   name: sqlite3
-  requirement: &70300799162540 !ruby/object:Gem::Requirement
+  requirement: &70289301061980 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -109,10 +109,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70300799162540
+  version_requirements: *70289301061980
 - !ruby/object:Gem::Dependency
   name: appraisal
-  requirement: &70300799161860 !ruby/object:Gem::Requirement
+  requirement: &70289301061200 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -120,7 +120,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70300799161860
+  version_requirements: *70289301061200
 description: ! "\n                        Build customizable classes to determine
   which scope\n                        methods to call based on supplied parameters.\n
   \                     "