ransack 0.4.1 → 0.4.2

data/README.md

@@ -0,0 +1,129 @@
+# Ransack
+
+Ransack is a rewrite of [MetaSearch](http://metautonomo.us/projects/metasearch). While it
+supports many of the same features as MetaSearch, its underlying implementation differs
+greatly from MetaSearch, and _backwards compatibility is not a design goal._
+
+Ransack enables the creation of both simple and advanced search forms against your
+application's models. If you're looking for something that simplifies query generation
+at the model or controller layer, you're probably not looking for Ransack (or MetaSearch,
+for that matter). Try [Squeel](http://metautonomo.us/projects/squeel) instead.
+
+## Getting started
+
+In your Gemfile:
+
+    gem "ransack"  # Last officially released gem
+    # gem "ransack", :git => "git://github.com/ernie/ransack.git" # Track git repo
+
+If you'd like to add your own custom Ransack predicates:
+
+    Ransack.configure do |config|
+      config.add_predicate 'equals_diddly', # Name your predicate
+                           # What non-compound ARel predicate will it use? (eq, matches, etc)
+                           :arel_predicate => 'eq',
+                           # Format incoming values as you see fit. (Default: Don't do formatting)
+                           :formatter => proc {|v| "#{v}-diddly"},
+                           # Validate a value. An "invalid" value won't be used in a search.
+                           # Below is default.
+                           :validator => proc {|v| v.present?},
+                           # Should compounds be created? Will use the compound (any/all) version
+                           # of the arel_predicate to create a corresponding any/all version of
+                           # your predicate. (Default: true)
+                           :compounds => true,
+                           # Force a specific column type for type-casting of supplied values.
+                           # (Default: use type from DB column)
+                           :type => :string
+    end
+
+## Usage
+
+Ransack can be used in one of two modes, simple or advanced.
+
+### Simple Mode
+
+This mode works much like MetaSearch, for those of you who are familiar with it, and
+requires very little setup effort.
+
+If you're coming from MetaSearch, things to note:
+
+  1. The default param key for search params is now `:q`, instead of `:search`. This is
+     primarily to shorten query strings, though advanced queries (below) will still 
+     run afoul of URL length limits in most browsers and require a switch to HTTP 
+     POST requests.
+  2. `form_for` is now `search_form_for`, and validates that a Ransack::Search object
+     is passed to it.
+  3. Common ActiveRecord::Relation methods are no longer delegated by the search object.
+     Instead, you will get your search results (an ActiveRecord::Relation in the case of
+     the ActiveRecord adapter) via a call to `Search#result`. If passed `:distinct => true`,
+     `result` will generate a `SELECT DISTINCT` to avoid returning duplicate rows, even if
+     conditions on a join would otherwise result in some.
+
+In your controller:
+
+    def index
+      @q = Person.search(params[:q])
+      @people = @q.result(:distinct => true)
+    end
+
+In your view:
+
+    <%= search_form_for @q do |f| %>
+      <%= f.label :name_cont %>
+      <%= f.text_field :name_cont %>
+      <%= f.label :articles_title_start %>
+      <%= f.text_field :articles_title_start %>
+      <%= f.submit %>
+    <% end %>
+
+`cont` (contains) and `start` (starts with) are just two of the available search predicates.
+See Constants for a full list.
+    
+### Advanced Mode
+
+"Advanced" searches (ab)use Rails' nested attributes functionality in order to generate
+complex queries with nested AND/OR groupings, etc. This takes a bit more work but can
+generate some pretty cool search interfaces that put a lot of power in the hands of
+your users. A notable drawback with these searches is that the increased size of the
+parameter string will typically force you to use the HTTP POST method instead of GET. :(
+
+This means you'll need to tweak your routes...
+
+    resources :people do
+      collection do
+        match 'search' => 'people#search', :via => [:get, :post], :as => :search
+      end
+    end
+
+... and add another controller action ...
+
+    def search
+      index
+      render :index
+    end
+    
+... and update your `search_form_for` line in the view ...
+
+    <%= search_form_for @q, :url => search_people_path, 
+                            :html => {:method => :post} do |f| %>
+
+Once you've done so, you can make use of the helpers in Ransack::Helpers::FormBuilder to
+construct much more complex search forms.
+
+**more docs to come**
+
+## Contributions
+
+If you'd like to support the continued development of Ransack, please consider
+[making a donation](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=48Q9HY64L3TWA).
+
+To support the project in other ways:
+
+* Use Ransack in your apps, and let me know if you encounter anything that's broken or missing.
+  A failing spec is awesome. A pull request is even better!
+* Spread the word on Twitter, Facebook, and elsewhere if Ransack's been useful to you. The more
+  people who are using the project, the quicker we can find and fix bugs!
+
+## Copyright
+
+Copyright &copy; 2011 [Ernie Miller](http://twitter.com/erniemiller)

data/lib/ransack/configuration.rb

@@ -7,10 +7,6 @@ module Ransack
     mattr_accessor :predicates
     self.predicates = {}
 
-    def predicate_keys
-      predicates.keys.sort {|a,b| b.length <=> a.length}
-    end
-
     def configure
       yield self
     end

data/lib/ransack/helpers/form_builder.rb

@@ -111,7 +111,7 @@ module Ransack
 
       def predicate_select(options = {}, html_options = {})
         options[:compounds] = true if options[:compounds].nil?
-        keys = options[:compounds] ? Ransack.predicate_keys : Ransack.predicate_keys.reject {|k| k.match(/_(any|all)$/)}
+        keys = options[:compounds] ? Predicate.names : Predicate.names.reject {|k| k.match(/_(any|all)$/)}
         if only = options[:only]
           if only.respond_to? :call
             keys = keys.select {|k| only.call(k)}

data/lib/ransack/nodes/condition.rb

@@ -28,7 +28,7 @@ module Ransack
 
         def extract_attributes_and_predicate(key)
           str = key.dup
-          name = Ransack.predicate_keys.detect {|p| str.sub!(/_#{p}$/, '')}
+          name = Predicate.detect_and_strip_from_string!(str)
           predicate = Predicate.named(name)
           raise ArgumentError, "No valid predicate for #{key}" unless predicate
           attributes = str.split(/_and_|_or_/)
@@ -194,7 +194,7 @@ module Ransack
       def formatted_values_for_attribute(attr)
         casted_values_for_attribute(attr).map do |val|
           val = attr.ransacker.formatter.call(val) if attr.ransacker && attr.ransacker.formatter
-          val = predicate.formatter.call(val) if predicate.formatter
+          val = predicate.format(val)
           val
         end
       end

data/lib/ransack/nodes/grouping.rb

@@ -173,7 +173,7 @@ module Ransack
 
       def strip_predicate_and_index(str)
         string = str.split(/\(/).first
-        Ransack.predicate_keys.detect {|p| string.sub!(/_#{p}$/, '')}
+        Predicate.detect_and_strip_from_string!(string)
         string
       end
 

data/lib/ransack/predicate.rb

@@ -3,13 +3,35 @@ module Ransack
     attr_reader :name, :arel_predicate, :type, :formatter, :validator, :compound
 
     class << self
+
+      def names
+        Ransack.predicates.keys
+      end
+
+      def names_by_decreasing_length
+        names.sort {|a,b| b.length <=> a.length}
+      end
+
       def named(name)
         Ransack.predicates[name.to_s]
       end
 
+      def detect_and_strip_from_string!(str)
+        names_by_decreasing_length.detect {|p| str.sub!(/_#{p}$/, '')}
+      end
+
+      def detect_from_string(str)
+        names_by_decreasing_length.detect {|p| str.match(/_#{p}$/)}
+      end
+
+      def name_from_attribute_name(attribute_name)
+        names_by_decreasing_length.detect {|p| attribute_name.to_s.match(/_#{p}$/)}
+      end
+
       def for_attribute_name(attribute_name)
-        self.named(Ransack.predicate_keys.detect {|p| attribute_name.to_s.match(/_#{p}$/)})
+        self.named(detect_from_string(attribute_name.to_s))
       end
+
     end
 
     def initialize(opts = {})
@@ -31,11 +53,19 @@ module Ransack
       name.hash
     end
 
+    def format(val)
+      if formatter
+        formatter.call(val)
+      else
+        val
+      end
+    end
+
     def validate(vals)
       if validator
         vals.select {|v| validator.call(v.value)}.any?
       else
-        vals.select {|v| !v.blank?}.any?
+        vals.select {|v| v.present?}.any?
       end
     end
 

data/lib/ransack/translate.rb

@@ -18,7 +18,7 @@ module Ransack
       original_name = key.to_s
       base_class = context.klass
       base_ancestors = base_class.ancestors.select { |x| x.respond_to?(:model_name) }
-      predicate = Ransack.predicate_keys.detect {|p| original_name.match(/_#{p}$/)}
+      predicate = Predicate.detect_from_string(original_name)
       attributes_str = original_name.sub(/_#{predicate}$/, '')
       attribute_names = attributes_str.split(/_and_|_or_/)
       combinator = attributes_str.match(/_and_/) ? :and : :or

data/lib/ransack/version.rb

@@ -1,3 +1,3 @@
 module Ransack
-  VERSION = "0.4.1"
+  VERSION = "0.4.2"
 end

data/ransack.gemspec

@@ -9,8 +9,8 @@ Gem::Specification.new do |s|
   s.authors     = ["Ernie Miller"]
   s.email       = ["ernie@metautonomo.us"]
   s.homepage    = "http://metautonomo.us/projects/ransack"
-  s.summary     = %q{Object-based searching. Like MetaSearch, but this time, with a better name.}
-  s.description = %q{Not yet ready for public consumption.}
+  s.summary     = %q{Object-based searching for ActiveRecord (currently).}
+  s.description = %q{Ransack is the successor to the MetaSearch gem. It improves and expands upon MetaSearch's functionality, but does not have a 100%-compatible API.}
 
   s.rubyforge_project = "ransack"
 

data/spec/ransack/helpers/form_builder_spec.rb

@@ -88,28 +88,28 @@ module Ransack
 
         it 'returns predicates with predicate_select' do
           html = @f.predicate_select
-          Ransack.predicate_keys.each do |key|
+          Predicate.names.each do |key|
             html.should match /<option value="#{key}">/
           end
         end
 
         it 'filters predicates with single-value :only' do
           html = @f.predicate_select :only => 'eq'
-          Ransack.predicate_keys.reject {|k| k =~ /^eq/}.each do |key|
+          Predicate.names.reject {|k| k =~ /^eq/}.each do |key|
             html.should_not match /<option value="#{key}">/
           end
         end
 
         it 'filters predicates with multi-value :only' do
           html = @f.predicate_select :only => [:eq, :lt]
-          Ransack.predicate_keys.reject {|k| k =~ /^(eq|lt)/}.each do |key|
+          Predicate.names.reject {|k| k =~ /^(eq|lt)/}.each do |key|
             html.should_not match /<option value="#{key}">/
           end
         end
 
         it 'excludes compounds when :compounds => false' do
           html = @f.predicate_select :compounds => false
-          Ransack.predicate_keys.select {|k| k =~ /_(any|all)$/}.each do |key|
+          Predicate.names.select {|k| k =~ /_(any|all)$/}.each do |key|
             html.should_not match /<option value="#{key}">/
           end
         end

metadata

@@ -1,108 +1,106 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: ransack
-version: !ruby/object:Gem::Version 
+version: !ruby/object:Gem::Version
+  version: 0.4.2
   prerelease: 
-  version: 0.4.1
 platform: ruby
-authors: 
+authors:
 - Ernie Miller
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-06-05 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2011-06-09 00:00:00.000000000 -04:00
+default_executable: 
+dependencies:
+- !ruby/object:Gem::Dependency
   name: activerecord
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: &2161553440 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        version: "3.0"
+      - !ruby/object:Gem::Version
+        version: '3.0'
   type: :runtime
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: activesupport
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: *2161553440
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: &2161552940 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        version: "3.0"
+      - !ruby/object:Gem::Version
+        version: '3.0'
   type: :runtime
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: actionpack
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  version_requirements: *2161552940
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: &2161552460 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        version: "3.0"
+      - !ruby/object:Gem::Version
+        version: '3.0'
   type: :runtime
-  version_requirements: *id003
-- !ruby/object:Gem::Dependency 
-  name: rspec
   prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  version_requirements: *2161552460
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &2161552000 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
+      - !ruby/object:Gem::Version
         version: 2.5.0
   type: :development
-  version_requirements: *id004
-- !ruby/object:Gem::Dependency 
-  name: machinist
   prerelease: false
-  requirement: &id005 !ruby/object:Gem::Requirement 
+  version_requirements: *2161552000
+- !ruby/object:Gem::Dependency
+  name: machinist
+  requirement: &2161551540 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
+      - !ruby/object:Gem::Version
         version: 1.0.6
   type: :development
-  version_requirements: *id005
-- !ruby/object:Gem::Dependency 
-  name: faker
   prerelease: false
-  requirement: &id006 !ruby/object:Gem::Requirement 
+  version_requirements: *2161551540
+- !ruby/object:Gem::Dependency
+  name: faker
+  requirement: &2161551080 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
+      - !ruby/object:Gem::Version
         version: 0.9.5
   type: :development
-  version_requirements: *id006
-- !ruby/object:Gem::Dependency 
-  name: sqlite3
   prerelease: false
-  requirement: &id007 !ruby/object:Gem::Requirement 
+  version_requirements: *2161551080
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: &2161550620 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
+      - !ruby/object:Gem::Version
         version: 1.3.3
   type: :development
-  version_requirements: *id007
-description: Not yet ready for public consumption.
-email: 
+  prerelease: false
+  version_requirements: *2161550620
+description: Ransack is the successor to the MetaSearch gem. It improves and expands
+  upon MetaSearch's functionality, but does not have a 100%-compatible API.
+email:
 - ernie@metautonomo.us
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .gitignore
 - Gemfile
 - LICENSE
-- README.rdoc
+- README.md
 - Rakefile
 - lib/ransack.rb
 - lib/ransack/adapters/active_record.rb
@@ -156,34 +154,32 @@ files:
 - spec/spec_helper.rb
 - spec/support/en.yml
 - spec/support/schema.rb
+has_rdoc: true
 homepage: http://metautonomo.us/projects/ransack
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: ransack
-rubygems_version: 1.7.2
+rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
-summary: Object-based searching. Like MetaSearch, but this time, with a better name.
-test_files: 
+summary: Object-based searching for ActiveRecord (currently).
+test_files:
 - spec/blueprints/articles.rb
 - spec/blueprints/comments.rb
 - spec/blueprints/notes.rb

data/README.rdoc

@@ -1,5 +0,0 @@
-= Ransack
-
-Don't use me.
-
-Seriously, I'm not anywhere close to ready for public consumption, yet.