paraphrase 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4f1f23ab1d7a4891efe1bc6159f0cc3a75b1191c
-  data.tar.gz: dc4755105aa6bdfbb4de5e68fe828470192c295a
+  metadata.gz: 495b5b3b50b22aed23b4b684084c4213dfa6648d
+  data.tar.gz: 25742c98d2fea7b1b65f64c0694a5b6fa2888005
 SHA512:
-  metadata.gz: 2782d593a807d6b26fa1cb370e4874e486533bdc15a35f375ae30488306da3b3ba4e531d74d0be90d51cf777d3a02efc96ab28fb3d7c7175fe48ee4440acbe0b
-  data.tar.gz: 45cc94e40cd091f11c4f7b4ee48b2e96c558b95bd20dd45d53cd6beb2db09d3e8fa6eaf249c3bbc3dca321e4e59d80cbebc7bff787cd633c8623321bf861c6ef
+  metadata.gz: 900028635ad15f53e571fc5af6f589886b4b814930a91f084ce8c387798a379b04d29c8876d373685e9434b33e207f948d87e3ced0e2f0f8f8ba7258f8fc7fce
+  data.tar.gz: 11deef4d8d8a299018766bd1f7d9ced8dea177594e9a549e0479b0035e1cbe1df9da1f8e82aaa554ceba33492d76371f5d0fe1c685deb6213f0949f4cd3c4472

data/.travis.yml

@@ -0,0 +1,12 @@
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.0
+  - jruby-19mode
+gemfile:
+  - gemfiles/3.0.gemfile
+  - gemfiles/3.1.gemfile
+  - gemfiles/3.2.gemfile
+  - gemfiles/4.0.gemfile
+install: 'bundle install -j 4'
+script: 'bundle exec rake'

data/Appraisals

@@ -1,19 +1,23 @@
 appraise '3.0' do
   gem 'activerecord', '~> 3.0'
   gem 'activesupport', '~> 3.0'
+  gem 'actionpack', '~> 3.0'
 end
 
 appraise '3.1' do
   gem 'activerecord', '~> 3.1'
   gem 'activesupport', '~> 3.1'
+  gem 'actionpack', '~> 3.1'
 end
 
 appraise '3.2' do
   gem 'activerecord', '~> 3.2'
   gem 'activesupport', '~> 3.2'
+  gem 'actionpack', '~> 3.2'
 end
 
 appraise '4.0' do
   gem 'activerecord', '~> 4.0'
   gem 'activesupport', '~> 4.0'
+  gem 'actionpack', '~> 4.0'
 end

data/CHANGELOG.md

@@ -0,0 +1,53 @@
+## 0.8.0 / 2-5-2014
+
+* Remove `ActiveSupport::Notifications`
+* Remove delegation to `Query#results`
+* Rename `Query#results` to `Query#result`
+* Add support for use with form builders
+* Remove `:require` option in `map`
+* Change method signature of `map`. Now accepts a list of keys followed by a
+  hash of options. the `:to` option points to the name of the scope that should
+  be called with the values of the supplied keys.
+* Determine the name of the source ActiveRecord::Base sublcass from the name of
+  the query class
+* Remove `register_mapping` method added to `ActiveRecord::Base`.
+
+## 0.7.0 / 1-25-2014
+
+* Add Rails 4 support
+
+## 0.5.0 / 8-7-2012
+
+* Cleanup `ScopeMapping` class
+* Add ability to query from an existing `ActiveRecord::Relation` instance
+  (typically an association).
+* Update syntax for generating mappings.
+
+## 0.4.0 / 7-6-2012
+
+* Setup `Query#params` to be `HashWithIndifferentAccess`.
+* Gut out `Paraphrase` module methods. These were for use cases I had planned
+  for but have yet to encounter.
+* Model's query class is now stored on the model itself.
+
+## 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.
+* Require/whitelist individual keys of a compound key.
+* Update `Paraphrase::Syntax.register_mapping` to update an existing mapping to
+avoid errors when a model class is reloaded during development.
+
+## 0.2.0 / 6-22-2012
+
+* Initial release
+

data/README.md

@@ -2,12 +2,8 @@
 
 [![Code Climate](https://codeclimate.com/github/ecbypi/paraphrase.png)](https://codeclimate.com/github/ecbypi/paraphrase)
 
-Paraphrase provides a way to map request params to model scopes and apply those
-scopes based on what params are supplied.  It adds a `.paraphrase` method to
-your model classes and `ActiveRecord::Relation` instances that, after setting
-up your scope => key mappings, will apply scopes if the parameters mapped to a
-scope are present. You can also require and whitelist certain parameters to
-provide more flexibility on complex scopes.
+Paraphrase provides a way to map query params to model scopes and
+only apply scopes when the mapped query params are present.
 
 ## Installation
 
@@ -25,41 +21,51 @@ $ gem install paraphrase
 
 ## Usage
 
-Create a subclass of `Paraphrase::Query` or call `register_mapping` from within
-your model to setup mappings.
+Subclass `Paraphrase::Query` and use `map` to define what query params should
+be applied to which scopes.
 
 ```ruby
 # app/queries/post_query.rb
 class PostQuery < Paraphrase::Query
-  map :by_user, :to => :author
-end
-
-# or
-
-# app/models/post.rb
-class Post < ActiveRecord::Base
-  belongs_to :user
+  map :author, to: :by_user
+  map :start_date, :end_date, to: :published_within
 
-  register_mapping do
-    map :by_user, :to => :author
+  def start_date
+    Time.zone.parse(params[:start_date])
   end
+end
+```
 
-  def self.by_user(author)
-    where(:user => { :name => author })
-  end
+By default, the `ActiveRecord` class is introspected from the demodulized class
+name of the `Paraphrase::Query` sublcass.  If the name of the query class is
+not `<model>Query`, the source can be manually specified by passing a string or
+symbol to the `source` method.
+
+```ruby
+# app/queries/admin_post_query.rb
+class AdminPostQuery < Paraphrase::Query
+  # This needs the source specific since it will look for an `AdminPost` model.
+  source :Post
 end
 ```
 
-In the controller, call `.paraphrase` on your model, passing in the hash
-containing the query params. This will filter out the registered parameters,
-calling the scopes whose inputs are supplied. If inputs for a scope are
-missing, it is skipped.
+In the controller, call `.paraphrase` on your model, passing a hash of query
+params.  This will filter out the registered query params, calling the scopes
+whose inputs are supplied. If a query param for a scope is missing or empty,
+the scope is skipped.
+
+`Paraphrase::Query` will intelligently determine if the value of the query
+param is empty. If the value is an array containing empty strings, the empty
+strings will be removed before being passed to the scope. If the array is empty
+after removing empty strings, the scope will not be called since an empty array
+is considered a blank value.
 
 ```ruby
 class PostsController < ApplicationController
   respond_to :html, :json
 
   def index
+    # Will filter out keys such as `:action` and `:controller`
     @posts = Post.paraphrase(params)
     respond_with(@posts)
   end
@@ -68,7 +74,7 @@ end
 
 You can chain queries on an `ActiveRecord::Relation`. This avoids adding scopes
 that replicate the functionality of an association like
-`Post.for_user(user_id)` or allows you to build a default scope.
+`Post.for_user(user_id)` or allow you to build a default scope.
 
 ```ruby
 class PostsController < ApplicationController
@@ -79,10 +85,13 @@ class PostsController < ApplicationController
     @user = User.find(params[:user_id])
 
     # This will scope the query to posts where `posts`.`user_id` = `users`.`id`
-    @posts = @users.posts.paraphrase(params)
+    @posts = @users.posts.paraphrase(params[:q])
 
     # Or you can build at a different point in a scope chain
-    # @posts = @user.posts.published.paraphrase(params)
+    # @posts = @user.posts.published.paraphrase(params[:q])
+    #
+    # Order is independent too
+    # @posts = @user.posts.paraphrase(params[:q]).published
 
     respond_with(@posts)
   end
@@ -96,103 +105,145 @@ Scopes are mapped to param keys using the `map` class method provided by
 
 ```ruby
 class PostQuery < Paraphrase::Query
-  map :by_user, :to => [:first_name, :last_name]
-  map :published_on, :to => :pub_date
+  map :first_name, :last_name, to: :by_user
+  map :pub_date, to: :pub_date
 end
 
 class Post < ActiveRecord::Base
   def self.by_user(first_name, last_name)
-    joins(:user).where(:user => { :first_name => first_name, :last_name => last_name })
+    joins(:user).where(user: { first_name: first_name, last_name: last_name })
   end
 
   def self.published_on(pub_date)
-    where(:published_on => pub_date)
+    where(published_on: pub_date)
   end
 end
 ```
 
-If a scope is required for a query to be considered valid, add `:require =>
-true` or `:require => [:array, :of, :keys]` in the options. If any values are
-missing, an empty result set will be returned. If the base key is an
-array, you can specify a subset of the key to be required. In this case, the rest of the
-attributes will be whitelisted.
+If multiple query params are mapped to a scope, but only a subset are required,
+use the `:whitelist` option to allow them to be missing. The `:whitelist`
+option can be set to `true`, an individual key or an array of keys.
 
 ```ruby
-class Post < ActiveRecord::Base
-  register_mapping do
-    # requires :pub_date to be supplied
-    map :published_on, :to => :pub_date, :require => true
-
-    # requires only :last_name to be passed in, :first_name can be nil
-    map :by_author, :to => [:first_name, :last_name], :require => :last_name
-  end
+class PostQuery < Paraphrase::Query
+  # requires only :last_name to be passed in, :first_name can be nil
+  map :first_name, :last_name, to: :by_author, whitelist: :last_name
+end
 
+class Post < ActiveRecord::Base
   def self.by_author(first_name, last_name)
-    query = where(:user => { :last_name => last_name })
+    query = where(user: { first_name: first_name })
 
-    if first_name
-      query.where(:user => { :first_name => first_name })
+    if last_name
+      query = query.where(user: { last_name: last_name })
     end
 
     query
   end
 end
 
-Post.paraphrase({}).results # => []
-```
-
-Alternatively, a scope or a subset of its keys can be whitelisted allowing nil
-values to be passed to the scope. This is intended for scopes that alter their
-behavior conditionally on a parameter being present. You should whitelist
-inputs if you still want other scopes to be applied as requiring them will halt
-execution of scopes and return an empty result set.
+Post.paraphrase(first_name: 'John').to_sql
+  # => SELECT "posts".* FROM "posts" WHERE "posts"."first_name" = 'John'
 
-```ruby
-class Post < ActiveRecord::Base
-  register_mapping do
-    # :first_name can be nil, :last_name is still required to apply the scope
-    map :by_author, :to => [:first_name, :last_name], :whitelist => :first_name
-  end
-end
+Post.paraphrase(first_name: 'John', last_name: 'Smith').to_sql
+  # => SELECT "posts".* FROM "posts" WHERE "posts"."first_name" = 'John' AND "posts"."last_name" = 'Smith'
 ```
 
 ### Boolean Scopes
 
-Some scopes take the form of a switch, filtering records based on a boolean
-column. It doesn't make sense for these methods to take any arguments and
-requirng them to would couple them to `Paraphrase::Query` classes in a
-complicated way.
+Some filter records based on a boolean column. It doesn't make sense for these
+methods to take any arguments.
 
 Paraphrase will detect if the method specified takes no arguments.  If not, it
 will call the method without any arguments, assuming the inputs are present and
 valid.
 
 ```ruby
-class Post < ActiveRecord::Base
-  register_mapping do
-    map :published, :to => :published
-  end
+class PostQuery < Paraphrase::Query
+  map :published, to: :published
+end
 
-  # If the params supplied include a non-nil value for :published,
-  # this method will be called.
+class Post < ActiveRecord::Base
+  # If the params supplied include a non-empty value for :published, this
+  # method will be called.
   def self.published
     where('published_at IS NOT NULL')
   end
 end
+
+Post.paraphrase(published: '1').to_sql
+  # => SELECT "posts".* FROM "posts" WHERE "posts"."published" = 't'
 ```
 
-### ActiveSupport::Notifications
+### Pre-processing Query Params
 
-You can subscribe to notifications when the query is built.
+By default, for each query param specified that maps to a model scope, a method
+is defined on the query class that fetches the value for that key. This is used
+internally to determine if model scopes need to be applied. To pre-process a
+query param, such as an ISO formatted date, override the method in the query
+class.
 
 ```ruby
-ActiveSupport::Notifications.subscribe('query.paraphrase') do |name, start, end, id, payload|
-  # ...
+class PostQuery < Paraphrase::Query
+  map :start_date, :end_date, to: :published_within
+
+  def start_date
+    @start_date ||= Time.zone.parse(params[:start_date]) rescue nil
+  end
+
+  def end_date
+    @start_date ||= Time.zone.parse(params[:end_date]) rescue nil
+  end
+end
+
+class Post < ActiveRecord::Base
+  def self.published_within(start_date, end_date)
+    where(published_at: start_date..end_date)
+  end
 end
+
+Post.parahrase(start_date: '201-03-21', end_date: '2013-03-25').to_sql
+  # => SELECT "posts".* FROM "posts"
 ```
 
-`payload` contains:
+In the above example, if either `:start_date` or `:end_date` are incorrectly
+formatted, the `pubished_within` scope will not be applied because the values
+are will be `nil`.
+
+### Using with `FormBuilder`
+
+The `Paraphrase::Query` class implements the `ActiveModel` API required for use with form builders.
+
+```ruby
+class PostQuery < Paraphrase::Query
+  map :author, to: :by_user
+end
+
+class PostsController < ApplicationController
+  def index
+    @query = PostQuery.new(params[:q])
+    @posts = query.result
+  end
+end
+```
+
+```erb
+<%= form_for @query, url: posts_url, method: :get do |f| %>
+  <%= f.label :author %>
+  <%= f.select :author, options_from_collection_for_select(User.authors, :id, :name) %>
+<% end %>
+
+<% @posts.each do |post| %>
+  ...
+<% end %>
+```
+
+## Contributing
+
+Contributions welcome. Be sure to include tests for any regressions or features.
 
-* `:params`: the params filtered
-* `:source_name`: name of the class being queried
-* `:source`: `ActiveRecord::Relation` being used as the base for the query
+1. Fork it ( http://github.com/[my-github-username]/paraphrase/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature with tests'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/gemfiles/3.0.gemfile

@@ -4,5 +4,6 @@ source "https://rubygems.org"
 
 gem "activerecord", "~> 3.0"
 gem "activesupport", "~> 3.0"
+gem "actionpack", "~> 3.0"
 
 gemspec :path=>"../"

data/gemfiles/3.0.gemfile.lock

@@ -1,13 +1,24 @@
 PATH
   remote: /Users/edd_d/Work/paraphrase
   specs:
-    paraphrase (0.6.1)
+    paraphrase (0.8.0)
+      activemodel (>= 3.0, < 4.1)
       activerecord (>= 3.0, < 4.1)
       activesupport (>= 3.0, < 4.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    actionpack (3.2.16)
+      activemodel (= 3.2.16)
+      activesupport (= 3.2.16)
+      builder (~> 3.0.0)
+      erubis (~> 2.7.0)
+      journey (~> 1.0.4)
+      rack (~> 1.4.5)
+      rack-cache (~> 1.2)
+      rack-test (~> 0.6.1)
+      sprockets (~> 2.2.1)
     activemodel (3.2.16)
       activesupport (= 3.2.16)
       builder (~> 3.0.0)
@@ -26,13 +37,21 @@ GEM
     builder (3.0.4)
     coderay (1.1.0)
     diff-lcs (1.2.5)
+    erubis (2.7.0)
+    hike (1.2.3)
     i18n (0.6.9)
+    journey (1.0.4)
     method_source (0.8.2)
     multi_json (1.8.4)
     pry (0.9.12.4)
       coderay (~> 1.0)
       method_source (~> 0.8)
       slop (~> 3.4)
+    rack (1.4.5)
+    rack-cache (1.2)
+      rack (>= 0.4)
+    rack-test (0.6.2)
+      rack (>= 1.0)
     rake (0.9.6)
     redcarpet (2.1.1)
     rspec (2.14.1)
@@ -44,7 +63,13 @@ GEM
       diff-lcs (>= 1.1.3, < 2.0)
     rspec-mocks (2.14.4)
     slop (3.4.7)
+    sprockets (2.2.2)
+      hike (~> 1.2)
+      multi_json (~> 1.0)
+      rack (~> 1.0)
+      tilt (~> 1.1, != 1.3.0)
     sqlite3 (1.3.8)
+    tilt (1.4.1)
     tzinfo (0.3.38)
     yard (0.8.7.3)
 
@@ -52,6 +77,7 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  actionpack (~> 3.0)
   activerecord (~> 3.0)
   activesupport (~> 3.0)
   appraisal (~> 0.4)
@@ -60,6 +86,6 @@ DEPENDENCIES
   pry (~> 0.9)
   rake (~> 0.9.2)
   redcarpet (~> 2.1.1)
-  rspec (~> 2.10)
+  rspec (~> 2.14)
   sqlite3 (~> 1.3.6)
   yard (~> 0.7)

data/gemfiles/3.1.gemfile

@@ -4,5 +4,6 @@ source "https://rubygems.org"
 
 gem "activerecord", "~> 3.1"
 gem "activesupport", "~> 3.1"
+gem "actionpack", "~> 3.1"
 
 gemspec :path=>"../"

data/gemfiles/3.1.gemfile.lock

@@ -1,13 +1,24 @@
 PATH
   remote: /Users/edd_d/Work/paraphrase
   specs:
-    paraphrase (0.6.1)
+    paraphrase (0.8.0)
+      activemodel (>= 3.0, < 4.1)
       activerecord (>= 3.0, < 4.1)
       activesupport (>= 3.0, < 4.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    actionpack (3.2.16)
+      activemodel (= 3.2.16)
+      activesupport (= 3.2.16)
+      builder (~> 3.0.0)
+      erubis (~> 2.7.0)
+      journey (~> 1.0.4)
+      rack (~> 1.4.5)
+      rack-cache (~> 1.2)
+      rack-test (~> 0.6.1)
+      sprockets (~> 2.2.1)
     activemodel (3.2.16)
       activesupport (= 3.2.16)
       builder (~> 3.0.0)
@@ -26,13 +37,21 @@ GEM
     builder (3.0.4)
     coderay (1.1.0)
     diff-lcs (1.2.5)
+    erubis (2.7.0)
+    hike (1.2.3)
     i18n (0.6.9)
+    journey (1.0.4)
     method_source (0.8.2)
     multi_json (1.8.4)
     pry (0.9.12.4)
       coderay (~> 1.0)
       method_source (~> 0.8)
       slop (~> 3.4)
+    rack (1.4.5)
+    rack-cache (1.2)
+      rack (>= 0.4)
+    rack-test (0.6.2)
+      rack (>= 1.0)
     rake (0.9.6)
     redcarpet (2.1.1)
     rspec (2.14.1)
@@ -44,7 +63,13 @@ GEM
       diff-lcs (>= 1.1.3, < 2.0)
     rspec-mocks (2.14.4)
     slop (3.4.7)
+    sprockets (2.2.2)
+      hike (~> 1.2)
+      multi_json (~> 1.0)
+      rack (~> 1.0)
+      tilt (~> 1.1, != 1.3.0)
     sqlite3 (1.3.8)
+    tilt (1.4.1)
     tzinfo (0.3.38)
     yard (0.8.7.3)
 
@@ -52,6 +77,7 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  actionpack (~> 3.1)
   activerecord (~> 3.1)
   activesupport (~> 3.1)
   appraisal (~> 0.4)
@@ -60,6 +86,6 @@ DEPENDENCIES
   pry (~> 0.9)
   rake (~> 0.9.2)
   redcarpet (~> 2.1.1)
-  rspec (~> 2.10)
+  rspec (~> 2.14)
   sqlite3 (~> 1.3.6)
   yard (~> 0.7)

data/gemfiles/3.2.gemfile

@@ -4,5 +4,6 @@ source "https://rubygems.org"
 
 gem "activerecord", "~> 3.2"
 gem "activesupport", "~> 3.2"
+gem "actionpack", "~> 3.2"
 
 gemspec :path=>"../"

data/gemfiles/3.2.gemfile.lock

@@ -1,13 +1,24 @@
 PATH
   remote: /Users/edd_d/Work/paraphrase
   specs:
-    paraphrase (0.6.1)
+    paraphrase (0.8.0)
+      activemodel (>= 3.0, < 4.1)
       activerecord (>= 3.0, < 4.1)
       activesupport (>= 3.0, < 4.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    actionpack (3.2.16)
+      activemodel (= 3.2.16)
+      activesupport (= 3.2.16)
+      builder (~> 3.0.0)
+      erubis (~> 2.7.0)
+      journey (~> 1.0.4)
+      rack (~> 1.4.5)
+      rack-cache (~> 1.2)
+      rack-test (~> 0.6.1)
+      sprockets (~> 2.2.1)
     activemodel (3.2.16)
       activesupport (= 3.2.16)
       builder (~> 3.0.0)
@@ -26,13 +37,21 @@ GEM
     builder (3.0.4)
     coderay (1.1.0)
     diff-lcs (1.2.5)
+    erubis (2.7.0)
+    hike (1.2.3)
     i18n (0.6.9)
+    journey (1.0.4)
     method_source (0.8.2)
     multi_json (1.8.4)
     pry (0.9.12.4)
       coderay (~> 1.0)
       method_source (~> 0.8)
       slop (~> 3.4)
+    rack (1.4.5)
+    rack-cache (1.2)
+      rack (>= 0.4)
+    rack-test (0.6.2)
+      rack (>= 1.0)
     rake (0.9.6)
     redcarpet (2.1.1)
     rspec (2.14.1)
@@ -44,7 +63,13 @@ GEM
       diff-lcs (>= 1.1.3, < 2.0)
     rspec-mocks (2.14.4)
     slop (3.4.7)
+    sprockets (2.2.2)
+      hike (~> 1.2)
+      multi_json (~> 1.0)
+      rack (~> 1.0)
+      tilt (~> 1.1, != 1.3.0)
     sqlite3 (1.3.8)
+    tilt (1.4.1)
     tzinfo (0.3.38)
     yard (0.8.7.3)
 
@@ -52,6 +77,7 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  actionpack (~> 3.2)
   activerecord (~> 3.2)
   activesupport (~> 3.2)
   appraisal (~> 0.4)
@@ -60,6 +86,6 @@ DEPENDENCIES
   pry (~> 0.9)
   rake (~> 0.9.2)
   redcarpet (~> 2.1.1)
-  rspec (~> 2.10)
+  rspec (~> 2.14)
   sqlite3 (~> 1.3.6)
   yard (~> 0.7)

data/gemfiles/4.0.gemfile

@@ -4,5 +4,6 @@ source "https://rubygems.org"
 
 gem "activerecord", "~> 4.0"
 gem "activesupport", "~> 4.0"
+gem "actionpack", "~> 4.0"
 
 gemspec :path=>"../"