lupa 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 83dad7fde61871e8d0333b609958b6eadaccc23c
-  data.tar.gz: 1a1eb1e14ede2f72d5f7eb029c38b2511e9182f6
+  metadata.gz: 46daf9ac53354ecc21016d968c78de4d322a1bb5
+  data.tar.gz: 62c8cde8889723041b1d622ed2bc1bec5f784ff6
 SHA512:
-  metadata.gz: e6f6127f879df5ec3bcee9e4c0c479df20aa53c17389fedf7a10d1403900da7920372a6bf2dab44ddad82843465c71834fe3343e515f506d63f331b4feec23b3
-  data.tar.gz: 84e3f845e779bdb383410f32509b99b4f7ae5fcda658dbb5e3dd49e8110b735c66b47c49ff583a2942822df800fc656fe8315c2f52bdb3b6807e476a5c7b06e0
+  metadata.gz: 010ba896da1a30da488d2726646616ca4e1c7091dd5907ae20150756af248b8173266e4b68f501470c35cbf12d933f0f6f530b8943920b2b0f874bff9a782599
+  data.tar.gz: 36a3ac1ee305f13318d990f250a40b97ab5f6cb90661c1e546ca4f0b0218e746a05d321d7069944ba100c484e8343125ccb2a8123cc2b15b46e9539e918168e1

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.5
+  - 2.2.1

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+## 1.0.1
+
+* enhancements
+    * A **Lupa::DefaultSearchAttributesError** exception will be raised if `default_search_attributes` does not return a hash.

data/Gemfile

@@ -2,3 +2,5 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in lupa.gemspec
 gemspec
+
+gem 'coveralls', require: false

data/README.md

@@ -2,53 +2,65 @@
 
 Lupa means *Magnifier* in spanish.
 
-Lupa lets you create simple, robust and scaleable search filters with ease using regular Ruby classes and object oriented design patterns. It's Framework and ORM agnostic.
+[![Build Status](https://travis-ci.org/edelpero/lupa.svg?branch=master)](https://travis-ci.org/edelpero/lupa) [![Coverage Status](https://coveralls.io/repos/edelpero/lupa/badge.svg?branch=master)](https://coveralls.io/r/edelpero/lupa?branch=master) [![Code Climate](https://codeclimate.com/github/edelpero/lupa/badges/gpa.svg)](https://codeclimate.com/github/edelpero/lupa) [![Inline docs](http://inch-ci.org/github/edelpero/lupa.svg?branch=master)](http://inch-ci.org/github/edelpero/lupa)
 
-## Search Class
+Lupa lets you create simple, robust and scaleable search filters with ease using regular Ruby classes and object oriented design patterns.
 
-### Usage
+Lupa it's Framework and ORM agnostic. It will work with any ORM or Object that can build a query using **chained method calls**, like ActiveRecord: `
+Product.where(name: 'Digital').where(category: '23').limit(2)`.
 
-The example will explain how to use the class on a Rails application:
+**Table of Contents:**
 
-- Define a custom form:
+* [Search Class](https://github.com/edelpero/lupa#search-class)
+    * [Overview](https://github.com/edelpero/lupa#overview)
+    * [Definition](https://github.com/edelpero/lupa#definition)
+    * [Public Methods](https://github.com/edelpero/lupa#public-methods)
+    * [Default Search Scope](https://github.com/edelpero/lupa#default-search-scope)
+    * [Default Search Attributes](https://github.com/edelpero/lupa#default-search-attributes)
+    * [Combining Search Classes](https://github.com/edelpero/lupa#combining-search-classes)
+* [Usage with Rails](https://github.com/edelpero/lupa#usage-with-rails)
+* [Testing](https://github.com/edelpero/lupa#testing)
+    * [Testing Default Scope](https://github.com/edelpero/lupa#testing-default-scope)
+    * [Testing Default Search Attributes](https://github.com/edelpero/lupa#testing-default-search-attributes)
+    * [Testing Each Scope Method Individually](https://github.com/edelpero/lupa#testing-each-scope-method-individually)
+* [Installation](https://github.com/edelpero/lupa#installation)
 
-```haml
-# app/views/products/_search.html.haml
 
-= form_tag products_path, method: :get do
-  = text_field_tag 'name'
-  = select_tag 'category', options_from_collection_for_select(@categories, 'id', 'name')
-  = date_field_tag 'created_between[start_date]'
-  = date_field_tag 'created_between[end_date]'
-  = submit_tag :search
-```
-- Create a new instance of your search class and pass a collection to which all search conditions will be applied and specify the search params you want to apply:
+## Search Class
+
+### Overview
 
 ```ruby
-# app/controllers/products_controller.rb
+products = ProductSearch.new(current_user.products).search(name: 'digital', category: '23')
 
-class ProductsController < ApplicationController
-  def index
-    @products = ProductSearch.new(current_user.products).search(search_params)
-  end
-  
-  protected
-    def search_params
-      params.permit(:name, :category, created_between: [:start_date, :end_date])
-    end
+# Iterate over the search results
+products.each do |product|
+  # Your logic goes here
 end
 ```
-- Loop through the search results on your view.
+Calling **.each** on the instance will build a search by chaining calls to **name** and **category** methods defined in our **ProductSearch::Scope** class.
 
-```haml
-# app/views/products/index.html.haml
+```ruby
+# app/searches/product_search.rb
 
-%h1 Products
+class ProductSearch < Lupa::Search
+  # Scope class holds all your search methods.
+  class Scope
 
-%ul
-  - @products.each do |product|
-    %li
-      = "#{product.name} - #{product.price} - #{product.category}"
+    # Search method
+    def name
+      if search_attributes[:name].present?
+        scope.where('name iLIKE ?', "%#{search_attributes[:name]}%")
+      end
+    end
+
+    # Search method
+    def category
+      scope.where(category_id: search_attributes[:category])
+    end
+
+  end
+end
 ```
 
 ### Definition
@@ -65,7 +77,7 @@ end
 Inside your **Scope** class you must define your scope methods. You'll also be able to access to the following methods inside your scope class: **scope** and **search_attributes**.
 
 * **`scope:`** returns the current scope when the scope method is called.
-* **`search_attributes:`** returns a hash containing the all search attributes specified.
+* **`search_attributes:`** returns a hash containing the all search attributes specified including the default ones.
 
 <u>**Note:**</u> All keys of **`search_attributes`** are symbolized.
 
@@ -75,32 +87,32 @@ Inside your **Scope** class you must define your scope methods. You'll also be a
 class ProductSearch < Lupa::Search
   # Scope class holds all your search methods.
   class Scope
-  
+
     # Search method
     def name
       if search_attributes[:name].present?
         scope.where('name LIKE ?', "%#{search_attributes[:name]}%")
       end
     end
-    
+
     # Search method
     def created_between
       if created_start_date && created_end_date
         scope.where(created_at: created_start_date..created_end_date)
       end
     end
-    
+
     # Search method
     def category
-      scope.where(category_id: search_attributes[:category])    
+      scope.where(category_id: search_attributes[:category])
     end
-    
+
     private
       # Parses search_attributes[:created_between][:start_date]
       def created_start_date
         search_attributes[:created_between] && search_attributes[:created_between][:start_date].try(:to_date)
       end
-      
+
       # Parses search_attributes[:created_between][:end_date]
       def created_end_date
         search_attributes[:created_between] && search_attributes[:created_between][:end_date].try(:to_date)
@@ -154,7 +166,7 @@ search.unexisting_method
 # => Lupa::ResultMethodNotImplementedError: The resulting scope does not respond to unexisting_method method.
 ```
 
-## Default Search Scope
+### Default Search Scope
 
 You can define a default search scope if you want to use a search class with an specific resource by overriding the initialize method as follows:
 
@@ -165,7 +177,7 @@ class ProductSearch < Lupa::Search
   class Scope
     ...
   end
-  
+
   # Be careful not to change the scope variable name,
   # otherwise you will experiment some issues.
   def initialize(scope = Product.all)
@@ -183,7 +195,7 @@ search.first
 # => #<Product id: 1, name: 'Eames Chair', category_id: 23, created_at: "2015-04-06 18:54:13", updated_at: "2015-04-06 18:54:13" >
 ```
 
-## Default Search Attributes
+### Default Search Attributes
 
 Defining default search attributes will cause the scope method to be invoked always.
 
@@ -194,7 +206,7 @@ class ProductSearch < Lupa::Search
   class Scope
     ...
   end
-  
+
   # This should always return a hash
   def default_search_attributes
     { category: 23 }
@@ -210,7 +222,7 @@ search.search_attributes
 # => { name: 'chair', category: 42 }
 ```
 
-## Combining Search Classes
+### Combining Search Classes
 
 You can reuse your search class in order to keep them DRY.
 
@@ -221,27 +233,27 @@ A common example is searching records created between two dates. So lets create
 
 class CreatedAtSearch < Lupa::Search
   class Scope
-  
+
     def created_before
       ...
     end
-    
+
     def created_after
       ...
     end
- 
+
     def created_between
       if created_start_date && created_end_date
         scope.where(created_at: created_start_date..created_end_date)
       end
     end
-  
+
     private
 
       def created_start_date
         search_attributes[:created_between] && search_attributes[:created_between][:start_date].try(:to_date)
       end
-      
+
       def created_end_date
         search_attributes[:created_between] && search_attributes[:created_between][:end_date].try(:to_date)
       end
@@ -256,26 +268,74 @@ Now we can use it in our **ProductSearch** class:
 
 class ProductSearch < Lupa::Search
   class Scope
-  
+
     def name
       ...
     end
-    
+
     # We use CreatedAtSearch class to perform the search
     def created_between
       if search_attributes[:created_between]
         CreadtedAtSearch.new(scope).search(created_between: search_attributes[:created_between])
       end
     end
-    
+
     def category
       ...
     end
-    
+
   end
 end
 ```
 
+## Usage with Rails
+
+### Forms
+
+Define a custom form:
+
+```haml
+# app/views/products/_search.html.haml
+
+= form_tag products_path, method: :get do
+  = text_field_tag 'name'
+  = select_tag 'category', options_from_collection_for_select(@categories, 'id', 'name')
+  = date_field_tag 'created_between[start_date]'
+  = date_field_tag 'created_between[end_date]'
+  = submit_tag :search
+```
+
+### Controllers
+
+Create a new instance of your search class and pass a collection to which all search conditions will be applied and specify the search params you want to apply:
+
+```ruby
+# app/controllers/products_controller.rb
+
+class ProductsController < ApplicationController
+  def index
+    @products = ProductSearch.new(current_user.products).search(search_params)
+  end
+
+  protected
+    def search_params
+      params.permit(:name, :category, created_between: [:start_date, :end_date])
+    end
+end
+```
+- Loop through the search results on your view.
+
+```haml
+# app/views/products/index.html.haml
+
+%h1 Products
+
+%ul
+  - @products.each do |product|
+    %li
+      = "#{product.name} - #{product.price} - #{product.category}"
+```
+
 ## Testing
 
 This is a list of things you should test when creating a search class:

data/Rakefile

@@ -8,4 +8,4 @@ Rake::TestTask.new do |t|
   t.verbose = true
 end
 
-
+task :default => :test

data/lib/lupa.rb

@@ -2,6 +2,7 @@ require "lupa/version"
 
 module Lupa
   DefaultScopeError               = Class.new(StandardError)
+  DefaultSearchAttributesError    = Class.new(StandardError)
   ScopeMethodNotImplementedError  = Class.new(NotImplementedError)
   ResultMethodNotImplementedError = Class.new(NotImplementedError)
   SearchAttributesError           = Class.new(StandardError)

data/lib/lupa/search.rb

@@ -314,9 +314,18 @@ module Lupa
       #
       # Sets @search_attributes by merging default search attributes with the ones passed to search method.
       def set_search_attributes(attributes)
+        attributes = merge_search_attributes(attributes)
         attributes = symbolize_keys(attributes)
         attributes = remove_blank_attributes(attributes)
-        @search_attributes = default_search_attributes.merge(attributes)
+
+        @search_attributes = attributes
+      end
+
+      # Internal: Merge search attributes with default search attributes
+      def merge_search_attributes(attributes)
+        return default_search_attributes.merge(attributes) if default_search_attributes.kind_of?(Hash)
+
+        raise Lupa::DefaultSearchAttributesError, "default_search_attributes doesn't return a Hash."
       end
 
       # Internal: Symbolizes all keys passed to the search attributes.

data/lib/lupa/version.rb

@@ -1,3 +1,3 @@
 module Lupa
-  VERSION = "1.0.0"
+  VERSION = "1.0.1"
 end

data/test/default_search_attributes_search_test.rb

@@ -32,6 +32,22 @@ class ClassWithoutDefaultSearchAttributesSearch < Lupa::Search
 
 end
 
+class ClassWithInvalidDefaultSearchAttributesSearch < Lupa::Search
+
+  class Scope
+    def reverse; end
+  end
+
+  def initialize(scope = [1, 2, 3, 4])
+    @scope = scope
+  end
+
+  def default_search_attributes
+    1
+  end
+
+end
+
 
 describe Lupa::Search do
   before do
@@ -61,6 +77,12 @@ describe Lupa::Search do
         search.default_search_attributes.must_equal params
       end
     end
+
+    context 'when default_search_attributes does not return a Hash' do
+      it 'raises a Lupa::DefaultSearchAttributesError exception' do
+        proc { ClassWithInvalidDefaultSearchAttributesSearch.search({}).results }.must_raise Lupa::DefaultSearchAttributesError
+      end
+    end
   end
 
   describe '#results' do

data/test/test_helper.rb

@@ -1,3 +1,6 @@
+require 'coveralls'
+Coveralls.wear!
+
 require 'minitest/autorun'
 
 def context(*args, &block)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lupa
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Ezequiel Delpero
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-04-08 00:00:00.000000000 Z
+date: 2015-04-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -61,6 +61,8 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .travis.yml
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md