paraphrase 0.7.0 → 0.8.0

data/gemfiles/4.0.gemfile.lock

@@ -1,13 +1,20 @@
 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 (4.0.2)
+      activesupport (= 4.0.2)
+      builder (~> 3.1.0)
+      erubis (~> 2.7.0)
+      rack (~> 1.5.2)
+      rack-test (~> 0.6.2)
     activemodel (4.0.2)
       activesupport (= 4.0.2)
       builder (~> 3.1.0)
@@ -31,6 +38,7 @@ GEM
     builder (3.1.4)
     coderay (1.1.0)
     diff-lcs (1.2.5)
+    erubis (2.7.0)
     i18n (0.6.9)
     method_source (0.8.2)
     minitest (4.7.5)
@@ -39,6 +47,9 @@ GEM
       coderay (~> 1.0)
       method_source (~> 0.8)
       slop (~> 3.4)
+    rack (1.5.2)
+    rack-test (0.6.2)
+      rack (>= 1.0)
     rake (0.9.6)
     redcarpet (2.1.1)
     rspec (2.14.1)
@@ -60,6 +71,7 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  actionpack (~> 4.0)
   activerecord (~> 4.0)
   activesupport (~> 4.0)
   appraisal (~> 0.4)
@@ -68,6 +80,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/lib/paraphrase/active_model.rb

@@ -0,0 +1,30 @@
+require 'active_support/concern'
+require 'active_model/naming'
+
+module Paraphrase
+  module ActiveModel
+    extend ActiveSupport::Concern
+
+    def to_key
+      [:q]
+    end
+
+    def to_model
+      self
+    end
+
+    def to_param
+      params.to_param
+    end
+
+    def persisted?
+      true
+    end
+
+    module ClassMethods
+      def model_name
+        ::ActiveModel::Name.new(self, nil, 'Q')
+      end
+    end
+  end
+end

data/lib/paraphrase/query.rb

@@ -2,88 +2,105 @@ require 'active_support/core_ext/object/blank'
 require 'active_support/core_ext/class/attribute'
 require 'active_support/core_ext/module/delegation'
 require 'active_support/core_ext/string/inflections'
+require 'active_support/core_ext/array/extract_options'
 require 'active_support/hash_with_indifferent_access'
+require 'paraphrase/active_model'
 
 module Paraphrase
   class Query
-    # @!attribute [r] mappings
-    #   @return [Array<ScopeMapping>] mappings for query
-    class_attribute :mappings, :instance_writer => false
-
-    # Delegate enumerable methods to results
-    delegate :collect, :map, :each, :select, :to_a, :to_ary, :to => :results
+    include ActiveModel
+    # @!attribute [r] scopes
+    #   @return [Array<Scope>] scopes for query
+    class_attribute :scopes, :_source, instance_writer: false
 
     # @!attribute [r] params
-    #   @return [HashWithIndifferentAccess] filters parameters based on keys defined in mappings
+    #   @return [HashWithIndifferentAccess] filters parameters based on keys defined in scopes
     #
-    # @!attribute [r] source
+    # @!attribute [r] result
     #   @return [ActiveRecord::Relation]
-    attr_reader :params, :source
+    attr_reader :params, :result
 
-    # Set `mappings` on inheritance to ensure they're unique per subclass
+    # Set `scopes` on inheritance to ensure they're unique per subclass
     def self.inherited(klass)
-      klass.mappings = []
+      klass.scopes = []
+    end
+
+    # Specify the `ActiveRecord` source class if not determinable from the name
+    # of the `Paraphrase::Query` subclass.
+    #
+    # @param [String, Symbol] name name of the source class
+    def self.source(name)
+      self._source = name.to_s
     end
 
-    # Add a {ScopeMapping} instance to {@@mappings .mappings}
+    # Add a {Scope} instance to {Query#scopes}. Defines a reader for each key
+    # to read from {Query#params}.
     #
-    # @see ScopeMapping#initialize
-    def self.map(name, options)
-      if mappings.map(&:method_name).include?(name)
-        raise DuplicateScopeError, "scope :#{name} has already been added"
+    # @see Scope#initialize
+    def self.map(*keys)
+      options = keys.extract_options!
+      scope_name = options[:to]
+
+      if scopes.any? { |scope| scope.name == scope_name }
+        raise DuplicateScopeError, "scope :#{scope_name} has already been mapped"
       end
 
-      mappings << ScopeMapping.new(name, options)
+      scopes << Scope.new(keys, options)
+
+      keys.each do |key|
+        define_method(key) { params[key] } unless method_defined?(key)
+      end
     end
 
     # Filters out parameters irrelevant to the query and sets the base scope
     # for to begin the chain.
     #
     # @param [Hash] params query parameters
-    # @param [ActiveRecord::Base, ActiveRecord::Relation] source object to
-    #   apply methods to
-    def initialize(params, class_or_relation)
-      keys = mappings.map(&:keys).flatten.map(&:to_s)
+    # @param [ActiveRecord::Relation] relation object to apply methods to
+    def initialize(params = {}, relation = source)
+      keys = scopes.map(&:keys).flatten.map(&:to_s)
 
-      @params = HashWithIndifferentAccess.new(params)
-      @params.select! { |key, value| keys.include?(key) && value.present? }
-      @params.freeze
+      @params = params.with_indifferent_access.slice(*keys)
+      scrub_params!
 
-      @source = class_or_relation
+      @result = scopes.inject(relation) do |r, scope|
+        scope.chain(self, r)
+      end
     end
 
-    # Loops through {#mappings} and apply scope methods to {#source}. If values
-    # are missing for a required key, an empty array is returned.
-    #
-    # @return [ActiveRecord::Relation, Array]
-    def results
-      return @results if @results
-
-      ActiveSupport::Notifications.instrument('query.paraphrase', :params => params, :source_name => source.name, :source => source) do
-        @results = mappings.inject(source) do |query, scope|
-          query = scope.chain(params, query)
+    alias :[] :send
 
-          break [] if query.nil?
-          query
-        end
+    # Return an `ActiveRecord::Relation` corresponding to the source class
+    # determined from the `_source` class attribute or the name of the query
+    # class.
+    #
+    # @return [ActiveRecord::Relation]
+    def source
+      @source ||= begin
+        name = _source || self.class.to_s.sub(/Query$/, '')
+        name.constantize
       end
     end
 
-    def respond_to_missing?(name, include_private = false)
-      super || results.respond_to?(name, include_private)
-    end
+    private
 
-    protected
+    def scrub_params!
+      params.delete_if { |key, value| scrub(value) }
+    end
 
-    def method_missing(name, *args, &block)
-      if results.respond_to?(name)
-        self.class.delegate name, :to => :results
-        results.send(name, *args, &block)
+    def scrub(value)
+      value = case value
+      when Array
+        value.delete_if { |v| scrub(v) }
+      when Hash
+        value.delete_if { |k, v| scrub(v) }
+      when String
+        value.strip
       else
-        super
+        value
       end
+
+      value.blank?
     end
   end
 end
-
-require 'paraphrase/scope_mapping'

data/lib/paraphrase/rails.rb

@@ -4,8 +4,7 @@ module Paraphrase
   class Railtie < Rails::Railtie
     initializer 'paraphrase.extend_active_record' do
       ActiveSupport.on_load :active_record do
-        extend Paraphrase::Syntax::Base
-        ActiveRecord::Relation.send(:include, Paraphrase::Syntax::Relation)
+        extend Paraphrase::Syntax
       end
     end
   end

data/lib/paraphrase/scope.rb

@@ -0,0 +1,56 @@
+require 'active_support/core_ext/object/blank'
+require 'active_support/core_ext/array/wrap'
+
+module Paraphrase
+  class Scope
+    # @!attribute [r] keys
+    #   @return [Array<Symbol>] param keys to extract
+    #
+    # @!attribute [r] name
+    #   @return [Symbol] scope name
+    #
+    # @!attribute [r] required_keys
+    #   @return [Array<Symbol>] keys required for query
+    attr_reader :keys, :name, :required_keys
+
+    # @param [Symbol] name name of the scope
+    # @param [Hash] options options to configure {Scope Scope} instance
+    # @option options [Symbol, Array<Symbol>] :to param key(s) to extract values from
+    # @option options [true, Symbol, Array<Symbol>] :require lists all or a
+    #   subset of param keys as required
+    def initialize(keys, options)
+      @keys = keys
+      @name = options[:to]
+
+      @required_keys = if options[:whitelist] == true
+        []
+      else
+        @keys - Array.wrap(options[:whitelist])
+      end
+    end
+
+    # Sends {#name} to `relation` if `query` has a value for all the
+    # {Scope#required_keys}. Passes through `relation` if any
+    # values are missing.  Detects if the scope takes no arguments to determine
+    # if values should be passed to the scope.
+    #
+    # @param [Paraphrase::Query] query instance of {Query} class
+    # @param [ActiveRecord::Relation] relation scope chain
+    # @return [ActiveRecord::Relation]
+    def chain(query, relation)
+      if required_keys.all? { |key| query[key] }
+        klass = relation.respond_to?(:klass) ? relation.klass : relation
+        arity = klass.method(name).arity
+
+        if arity == 0
+          relation.send(name)
+        else
+          values = keys.map { |key| query[key] }
+          relation.send(name, *values)
+        end
+      else
+        relation
+      end
+    end
+  end
+end

data/lib/paraphrase/syntax.rb

@@ -1,68 +1,23 @@
 module Paraphrase
   module Syntax
-    module Base
-      def self.extended(klass)
-        klass.instance_eval do
-          class_attribute :_paraphraser, :instance_writer => false, :instance_reader => false
-        end
-      end
-
-      # Create a {Query} subclass from a block using the `Query` DSL to map
-      # scopes to param keys
-      #
-      # @param [Proc] &block block to to define scope mappings
-      def register_mapping(&block)
-        self._paraphraser = Class.new(Query, &block)
-      end
-
-      # Attempts to find paraphrase class based on class name.  Override if
-      # using a different naming convention.
-      def paraphraser
-        self._paraphraser || "#{self.name}Query".constantize
-      rescue
-        nil
-      end
-
-      # Instantiate the {Query} class that is mapped to `self`.
-      #
-      # @param [Hash] params query parameters
-      def paraphrase(params)
-        self.paraphraser.new(params, self)
+    # Attempts to find paraphrase class based on class name.  Override if
+    # using a different naming convention.
+    def paraphraser
+      name = "#{self.name}Query"
+      name.constantize
+    rescue NameError => e
+      if e.message =~ /uninitialized constant/
+        raise Paraphrase::NoQueryDefined.new("No query class found. #{name} must be defined as a subclass of Paraphrase::Query")
       end
     end
 
-    module Relation
-      # Creates a paraphrase {Query query}, supplying `self` as the base for the
-      # query. Intended for scoping a query from an association:
-      #
-      # Given the following models:
-      #
-      # ```ruby
-      # class User < ActiveRecord::Base
-      #   has_many :posts
-      # end
-      #
-      # class Post < ActiveRecord::Base
-      #   belongs_to :user
-      #
-      #   register_mapping
-      #     map :title_like, :to => :title
-      #   end
-      # end
-      # ```
-      #
-      # It is possible to do the following:
-      #
-      # ```ruby
-      # user.posts.paraphrase({ :title => 'Game of Thrones Finale' }).to_sql
-      # # => SELECT `posts`.* FROM `posts` INNER JOIN `users` ON `users`.`post_id` = `posts`.`id` WHERE `posts`.`title LIKE "%Game of Thrones Finale%";
-      # ```
-      #
-      # @param [Hash] params query parameters
-      # @return [Paraphrase::Query]
-      def paraphrase(params)
-        klass.paraphraser.new(params, self)
-      end
+    # Instantiate the {Query} class that is mapped to `self`.
+    #
+    # @param [Hash] params query parameters
+    def paraphrase(params = {})
+      paraphraser.new(params, self).result
     end
   end
+
+  class NoQueryDefined < StandardError; end
 end

data/lib/paraphrase/version.rb

@@ -1,3 +1,3 @@
 module Paraphrase
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

data/lib/paraphrase.rb

@@ -1,4 +1,5 @@
 require 'paraphrase/errors'
 require 'paraphrase/query'
+require 'paraphrase/scope'
 require 'paraphrase/syntax'
 require 'paraphrase/rails' if defined?(Rails)

data/paraphrase.gemspec

@@ -14,7 +14,7 @@ Gem::Specification.new do |gem|
                       }
   gem.license       = "MIT"
   gem.authors       = ["Eduardo Gutierrez"]
-  gem.email         = "edd_d@mit.edu"
+  gem.email         = "eduardo@vermonster.com"
   gem.homepage      = "https://github.com/ecbypi/paraphrase"
 
   gem.files         = `git ls-files`.split($/)
@@ -22,15 +22,28 @@ Gem::Specification.new do |gem|
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ['lib']
 
+  gem.required_ruby_version = '>= 1.9.3'
+
   gem.add_dependency 'activerecord', '>= 3.0', '< 4.1'
   gem.add_dependency 'activesupport', '>= 3.0', '< 4.1'
+  gem.add_dependency 'activemodel', '>= 3.0', '< 4.1'
 
+  gem.add_development_dependency 'actionpack', '>= 3.0', '< 4.1'
   gem.add_development_dependency 'bundler', '~> 1.0'
   gem.add_development_dependency 'yard', '~> 0.7'
-  gem.add_development_dependency 'rspec', '~> 2.10'
-  gem.add_development_dependency 'redcarpet', '~> 2.1.1'
+  gem.add_development_dependency 'rspec', '~> 2.14'
   gem.add_development_dependency 'rake', '~> 0.9.2'
-  gem.add_development_dependency 'sqlite3',  '~> 1.3.6'
   gem.add_development_dependency 'appraisal', '~> 0.4'
   gem.add_development_dependency 'pry', '~> 0.9'
+
+  if RUBY_PLATFORM != 'java'
+    gem.add_development_dependency 'redcarpet', '~> 2.1.1'
+  end
+
+  if RUBY_PLATFORM == 'java'
+    gem.add_development_dependency 'activerecord-jdbcsqlite3-adapter'
+    gem.add_development_dependency 'jdbc-sqlite3'
+  else
+    gem.add_development_dependency 'sqlite3',  '~> 1.3.6'
+  end
 end

data/spec/paraphrase/query_spec.rb

@@ -1,83 +1,151 @@
 require 'spec_helper'
+require 'action_view/test_case'
 
 module Paraphrase
   describe Query do
-    describe ".map" do
-      subject { Class.new(Query) }
+    class ::PostQuery < Paraphrase::Query
+      map :title, to: :titled
+      map :is_published, to: :published
+      map :authors, to: :by_users
+      map :start_date, :end_date, to: :published_between
+
+      def start_date
+        @start_date ||= Time.parse(params[:start_date]) rescue nil
+      end
 
-      it "adds information to Query.mappings" do
-        subject.map :name_like, :to => :name
+      def end_date
+        @end_date ||= Time.parse(params[:end_date]) rescue nil
+      end
+    end
 
-        subject.mappings.should_not be_empty
+    describe ".map" do
+      it "adds information to Query.scopes" do
+        expect(PostQuery.scopes).not_to be_empty
       end
 
       it "raises an error if a scope is added twice" do
-        subject.map :name_like, :to => :name
+        expect { PostQuery.map :name, to: :titled }.to raise_error Paraphrase::DuplicateScopeError
+      end
+
+      it 'defines readers for each key' do
+        query = PostQuery.new
 
-        expect { subject.map :name_like, :to => :name }.to raise_error Paraphrase::DuplicateScopeError
+        expect(query).to respond_to :title
+        expect(query).to respond_to :is_published
+        expect(query).to respond_to :authors
       end
     end
 
-    describe "on initialization" do
-      let(:query) do
+    after do
+      Post.delete_all
+      User.delete_all
+    end
+
+    describe '#source' do
+      it 'is determined via query class name' do
+        expect(PostQuery.new.result).to eq Post
+      end
+
+      it 'can be manually specified in the class' do
         klass = Class.new(Query) do
-          map :name_like, :to => :name
-          map :email_like, :to => :email
+          source :User
         end
 
-        klass.new({ :name => 'name', :nickname => '', :email => '' }, Account)
+        expect(klass.new.result).to eq User
+      end
+    end
+
+    describe '#[]' do
+      it 'retreives values from #params or uses custom reader if defined' do
+        query = PostQuery.new(title: 'Morning Joe', start_date: '2010-10-30', end_date: 'foo')
+
+        expect(query[:title]).to eq 'Morning Joe'
+        expect(query[:start_date]).to eq Time.local(2010, 10, 30)
+        expect(query[:end_date]).to be_nil
       end
+    end
 
-      it "filters out params not specified in mappings" do
-        query.params.should_not have_key :nickname
-        query.params.should have_key :name
+    describe "#params" do
+      it "filters out params not specified in scopes" do
+        query = PostQuery.new(nickname: 'bill', title: 'william')
+
+        expect(query.params).not_to have_key :nickname
+        expect(query.params).to have_key :title
       end
 
       it "sets up params with indifferent access" do
-        query.params.should have_key 'name'
+        query = PostQuery.new(title: 'D3 How-To')
+        expect(query.params).to have_key 'title'
       end
 
-      it 'filters out blank values' do
-        query.params.should_not have_key :email
+      it 'recursively filters out blank values' do
+        query = PostQuery.new(title: { key: ['', { key: [] }, []] }, authors: ['', 'kevin', ['', {}], { key: [' '] }])
+
+        expect(query.params[:authors]).to eq ['kevin']
+        expect(query.params).not_to have_key :title
       end
     end
 
-    describe "#results" do
-      let(:klass) do
-        Class.new(Query) do
-          map :name_like, :to => :name
-          map :title_like, :to => :title, :require => true
-        end
-      end
+    it 'skips scopes if query params are missing' do
+      expect(Post).not_to receive(:published_between)
+      expect(Post).not_to receive(:titled)
+      expect(Post).not_to receive(:by_users)
+      expect(Post).to receive(:published)
+
+      PostQuery.new(
+        start_date: Time.local(2010, 10, 30),
+        end_date: 'foo',
+        is_published: '1',
+        authors: [],
+        title: ['', {}]
+      )
+    end
 
-      it "loops through scope methods and applies them to source" do
-        Account.should_receive(:title_like).and_return(Account)
-        Account.should_receive(:name_like).and_return(Account)
+    it 'preserves the original scope used to initialize the query' do
+      user = User.create!
+      blue_post = Post.create!(user: user, title: 'Blue', published: false)
+      red_post = Post.create!(user: user, title: 'Red', published: true)
+      green_post = Post.create!(title: 'Red', published: true)
 
-        query = klass.new({ :name => 'Jon Snow', :title => 'Wall Watcher'}, Account)
-        query.results
-      end
+      result = PostQuery.new({ title: 'Red' }, user.posts.published).result
 
-      it "returns empty array if inputs were missing and required" do
-        query = klass.new({}, Account)
-        query.results.should eq []
-      end
+      expect(result).to include red_post
+      expect(result).not_to include blue_post
+      expect(result).not_to include green_post
     end
 
-    describe "preserves" do
-      it "the relation passed in during initialization" do
-        klass = Class.new(Query) do
-          map :name_like, :to => :name
+    describe 'is action view compliant' do
+      it 'by working with form builders' do
+        router = ActionDispatch::Routing::RouteSet.new
+        router.draw do
+          resources :posts
+        end
+
+        controller = ActionView::TestCase::TestController.new
+        controller.instance_variable_set(:@_routes, router)
+        controller.class_eval { include router.url_helpers }
+        controller.view_context.class_eval { include router.url_helpers }
+
+        query = PostQuery.new(title: 'Red', start_date: '2012-10-01')
+
+        markup = ""
+        controller.view_context.form_for query, url: router.url_helpers.posts_path do |f|
+          markup << f.text_field(:title)
+          markup << f.date_select(:start_date)
         end
 
-        user = User.create!
-        Account.create!(user: user)
-        Account.create!
+        expect(markup).to match(/<input.*type="text"/)
+        expect(markup).to match(/type="text"/)
+        expect(markup).to match(/name="q\[title\]"/)
+        expect(markup).to match(/value="Red"/)
 
-        query = klass.new({ :name => 'name' }, Account.where(user_id: user.id))
-        results = query.results
+        expect(markup).to match(/<select.*name="q\[start_date\(1i\)/)
+        expect(markup).to match(/<select.*name="q\[start_date\(2i\)/)
+        expect(markup).to match(/<select.*name="q\[start_date\(3i\)/)
 
-        results.to_a.should eq user.accounts.to_a
+        expect(markup).to match(/<option.*selected="selected" value="2012"/)
+        expect(markup).to match(/<option.*selected="selected" value="10"/)
+        expect(markup).to match(/<option.*selected="selected" value="1"/)
       end
     end
   end