ransack 2.3.0 → 2.4.2

data/Gemfile

@@ -5,16 +5,28 @@ gem 'rake'
 
 rails = ENV['RAILS'] || '6-0-stable'
 
-gem 'pry'
+rails_version = case rails
+                when /\// # A path
+                  File.read(File.join(rails, "RAILS_VERSION"))
+                when /^v/ # A tagged version
+                  rails.gsub(/^v/, '')
+                else
+                  rails
+                end
 
-# Provide timezone information on Windows
-gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw]
+gem 'faker', '~> 2.0'
+gem 'sqlite3', ::Gem::Version.new(rails_version == 'main' ? '6.2.0.alpha' : rails_version) >= ::Gem::Version.new('6-0-stable') ? '~> 1.4.1' : '~> 1.3.3'
+gem 'pg', '~> 1.0'
+gem 'pry', '~> 0.12.2'
+gem 'byebug'
 
 case rails
 when /\// # A path
   gem 'activesupport', path: "#{rails}/activesupport"
+  gem 'activemodel', path: "#{rails}/activemodel"
   gem 'activerecord', path: "#{rails}/activerecord", require: false
   gem 'actionpack', path: "#{rails}/actionpack"
+  gem 'actionview', path: "#{rails}/actionview"
 when /^v/ # A tagged version
   git 'https://github.com/rails/rails.git', :tag => rails do
     gem 'activesupport'
@@ -33,7 +45,9 @@ end
 gem 'mysql2', '~> 0.5.2'
 
 group :test do
-  # TestUnit was removed from Ruby 2.2 but still needed for testing Rails 3.x.
-  gem 'test-unit', '~> 3.0' if RUBY_VERSION >= '2.2'
+  gem 'machinist', '~> 1.0.6'
+  gem 'rspec', '~> 3'
   gem 'simplecov', :require => false
 end
+
+gem 'rubocop', require: false

data/README.md

@@ -1,19 +1,9 @@
 # ![Ransack](./logo/ransack-h.png "Ransack")
 
-[![Build Status](https://travis-ci.org/activerecord-hackery/ransack.svg)](https://travis-ci.org/activerecord-hackery/ransack)
+[![Build Status](https://github.com/activerecord-hackery/ransack/workflows/test/badge.svg)](https://github.com/activerecord-hackery/ransack/actions)
 [![Gem Version](https://badge.fury.io/rb/ransack.svg)](http://badge.fury.io/rb/ransack)
 [![Code Climate](https://codeclimate.com/github/activerecord-hackery/ransack/badges/gpa.svg)](https://codeclimate.com/github/activerecord-hackery/ransack)
-[![Backers on Open Collective](https://opencollective.com/ransack/backers/badge.svg)](#backers) [![Sponsors on Open Collective](https://opencollective.com/ransack/sponsors/badge.svg)](#sponsors) 
-
-Ransack is a rewrite of [MetaSearch](https://github.com/activerecord-hackery/meta_search)
-created by [Ernie Miller](http://twitter.com/erniemiller)
-and developed/maintained for years by
-[Jon Atack](http://twitter.com/jonatack) and
-[Ryan Bigg](http://twitter.com/ryanbigg) with the help of a great group of
-[contributors](https://github.com/activerecord-hackery/ransack/graphs/contributors). Ransack's logo is designed by [Anıl Kılıç](https://github.com/anilkilic).
-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.
+[![Backers on Open Collective](https://opencollective.com/ransack/backers/badge.svg)](#backers) [![Sponsors on Open Collective](https://opencollective.com/ransack/sponsors/badge.svg)](#sponsors)
 
 Ransack enables the creation of both
 [simple](http://ransack-demo.herokuapp.com) and
@@ -25,25 +15,9 @@ or controller layer, you're probably not looking for Ransack (or MetaSearch,
 for that matter). Try [Squeel](https://github.com/activerecord-hackery/squeel)
 instead.
 
-If you're viewing this at
-[github.com/activerecord-hackery/ransack](https://github.com/activerecord-hackery/ransack),
-you're reading the documentation for the master branch with the latest features.
-[View documentation for the last release (2.0.0).](https://github.com/activerecord-hackery/ransack/tree/v2.0.0)
-
-## Rails 6 Support
-
-Rails 6 is right around the corner, but not yet released. Ransack master branch supports ```6.0.0.rc2```. Full Rails 6 support will be provided after the official Rails 6 release. See [this issue](https://github.com/activerecord-hackery/ransack/issues/1032) for details.
-
 ## Getting started
 
-Ransack is compatible with Rails 6.0.0.rc2, 5.0, 5.1 and 5.2 on Ruby 2.2 and later.
-If you are using Rails <5.0 use the 1.8 line of Ransack.
-If you are using Ruby 1.8 or an earlier JRuby and run into compatibility
-issues, you can use an earlier version of Ransack, say, up to 1.3.0.
-
-Ransack works out-of-the-box with Active Record and also features limited
-support for Mongoid 4 and 5 (without associations, further details
-[below](https://github.com/activerecord-hackery/ransack#mongoid)).
+Ransack is supported for Rails 6.1, 6.0, 5.2 on Ruby 2.6.6 and later.
 
 In your Gemfile, for the last officially released gem:
 
@@ -67,27 +41,14 @@ gem 'ransack', github: 'activerecord-hackery/ransack'
 
 ## Usage
 
-Ransack can be used in one of two modes, simple or advanced.
+Ransack can be used in one of two modes, simple or advanced. For
+searching/filtering not requiring complex boolean logic, Ransack's simple
+mode should meet your needs.
 
-### Simple Mode
+If you're coming from MetaSearch (Ransack's predecessor), refer to the
+[Updating From MetaSearch](#updating-from-metasearch) section
 
-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. This key is [configurable](https://github.com/activerecord-hackery/ransack/wiki/Configuration).
-
-  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
-  `Ransack#result`.
+### Simple Mode
 
 #### In your controller
 
@@ -110,6 +71,20 @@ def index
 end
 ```
 
+##### Default search parameter
+
+Ransack uses a default `:q` param key for search params. This may be changed by
+setting the `search_key` option in a Ransack initializer file (typically
+`config/initializers/ransack.rb`):
+
+```
+Ransack.configure do |c|
+  # Change default search parameter key name.
+  # Default key name is :q
+  c.search_key = :query
+end
+```
+
 #### In your view
 
 The two primary Ransack view helpers are `search_form_for` and `sort_link`,
@@ -276,6 +251,20 @@ the order indicator arrow by passing `hide_indicator: true` in the sort link:
   default_order: { last_name: 'asc', first_name: 'desc' }) %>
 ```
 
+#### PostgreSQL's sort option
+
+The `NULLS FIRST` and `NULLS LAST` options can be used to determine whether nulls appear before or after non-null values in the sort ordering.
+
+You may want to configure it like this:
+
+```rb
+Ransack.configure do |c|
+  c.postgres_fields_sort_option = :nulls_first # or :nulls_last
+end
+```
+
+See this feature: https://www.postgresql.org/docs/13/queries-order.html
+
 ### Advanced Mode
 
 "Advanced" searches (ab)use Rails' nested attributes functionality in order to
@@ -463,13 +452,10 @@ List of all possible predicates
 | `*_lteq_any` | Less than or equal to any | |
 | `*_gt_any` | Greater than any | |
 | `*_gteq_any` | Greater than or equal to any | |
-| `*_matches_any` | `*_does_not_match_any` | same as above but with `LIKE` |
 | `*_lt_all` | Less than all | SQL: `col < value1 AND col < value2` |
 | `*_lteq_all` | Less than or equal to all | |
 | `*_gt_all` | Greater than all | |
 | `*_gteq_all` | Greater than or equal to all | |
-| `*_matches_all` | Matches all | same as above but with `LIKE` |
-| `*_does_not_match_all` | Does not match all | |
 | `*_not_eq_all` | none of values in a set | |
 | `*_start` | Starts with | SQL: `col LIKE 'value%'` |
 | `*_not_start` | Does not start with | |
@@ -489,6 +475,12 @@ List of all possible predicates
 | `*_not_cont` | Does not contain |
 | `*_not_cont_any` | Does not contain any of | |
 | `*_not_cont_all` | Does not contain all of | |
+| `*_i_cont` | Contains value with case insensitive | uses `ILIKE` |
+| `*_i_cont_any` | Contains any of values with case insensitive | |
+| `*_i_cont_all` | Contains all of values with case insensitive | |
+| `*_not_i_cont` | Does not contain with case insensitive |
+| `*_not_i_cont_any` | Does not contain any of values with case insensitive | |
+| `*_not_i_cont_all` | Does not contain all of values with case insensitive | |
 | `*_true` | is true | |
 | `*_false` | is false | |
 
@@ -693,6 +685,43 @@ Trying it out in `rails console`:
 
 That's it! Now you know how to whitelist/blacklist various elements in Ransack.
 
+### Handling unknown predicates or attributes
+
+By default, Ransack will ignore any unknown predicates or attributes:
+
+```ruby
+Article.ransack(unknown_attr_eq: 'Ernie').result.to_sql
+=> SELECT "articles".* FROM "articles"
+```
+
+Ransack may be configured to raise an error if passed an unknown predicate or
+attributes, by setting the `ignore_unknown_conditions` option to `false` in your
+Ransack initializer file at `config/initializers/ransack.rb`:
+
+```ruby
+Ransack.configure do |c|
+  # Raise errors if a query contains an unknown predicate or attribute.
+  # Default is true (do not raise error on unknown conditions).
+  c.ignore_unknown_conditions = false
+end
+```
+
+```ruby
+Article.ransack(unknown_attr_eq: 'Ernie')
+# ArgumentError (Invalid search term unknown_attr_eq)
+```
+
+As an alternative to setting a global configuration option, the `.ransack!`
+class method also raises an error if passed an unknown condition:
+
+```ruby
+Article.ransack!(unknown_attr_eq: 'Ernie')
+# ArgumentError: Invalid search term unknown_attr_eq
+```
+
+This is equivilent to the `ignore_unknown_conditions` configuration option,
+except it may be applied on a case-by-case basis.
+
 ### Using Scopes/Class Methods
 
 Continuing on from the preceding section, searching by scopes requires defining
@@ -755,7 +784,7 @@ To turn this off on a per-scope basis Ransack adds the following method to
 Add the scope you wish to bypass this behavior to ransackable_scopes_skip_sanitize_args:
 
 ```ruby
-def ransackable_scopes_skip_sanitize_args
+def self.ransackable_scopes_skip_sanitize_args
   [:scope_to_skip_sanitize_args]
 end
 ```
@@ -889,6 +918,28 @@ en:
         title: Old Ransack Namespaced Title
 ```
 
+### Updating From MetaSearch
+
+Ransack 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. This key is
+  [configurable](default-search-parameter) via setting the `search_key` option
+  in your Ransack intitializer file.
+
+  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
+  `Ransack#result`.
+
 ## Mongoid
 
 Mongoid support has been moved to its own gem at [ransack-mongoid](https://github.com/activerecord-hackery/ransack-mongoid).
@@ -926,6 +977,7 @@ In other words: `Major.Minor.Patch`.
 
 To support the project:
 
+* Consider supporting via [Open Collective](https://opencollective.com/ransack/backers/badge.svg)
 * Use Ransack in your apps, and let us know if you encounter anything that's
 broken or missing. A failing spec to demonstrate the issue is awesome. A pull
 request with passing tests is even better!
@@ -941,6 +993,21 @@ fix bugs!
 
 This project exists thanks to all the people who contribute. <img src="https://opencollective.com/ransack/contributors.svg?width=890&button=false" />
 
+Ransack is a rewrite of [MetaSearch](https://github.com/activerecord-hackery/meta_search)
+created by [Ernie Miller](http://twitter.com/erniemiller)
+and developed/maintained by:
+
+- [Greg Molnar](https://github.com/gregmolnar)
+- [Deivid Rodriguez](https://github.com/deivid-rodriguez)
+- [Sean Carroll](https://github.com/seanfcarroll)
+- [Jon Atack](http://twitter.com/jonatack)
+- [Ryan Bigg](http://twitter.com/ryanbigg)
+- a great group of [contributors](https://github.com/activerecord-hackery/ransack/graphs/contributors).
+- Ransack's logo is designed by [Anıl Kılıç](https://github.com/anilkilic).
+
+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.
+
+
 
 ## Backers
 
@@ -963,5 +1030,3 @@ Support this project by becoming a sponsor. Your logo will show up here with a l
 <a href="https://opencollective.com/ransack/sponsor/7/website" target="_blank"><img src="https://opencollective.com/ransack/sponsor/7/avatar.svg"></a>
 <a href="https://opencollective.com/ransack/sponsor/8/website" target="_blank"><img src="https://opencollective.com/ransack/sponsor/8/avatar.svg"></a>
 <a href="https://opencollective.com/ransack/sponsor/9/website" target="_blank"><img src="https://opencollective.com/ransack/sponsor/9/avatar.svg"></a>
-
-

data/bug_report_templates/test-ransack-scope-and-column-same-name.rb

@@ -0,0 +1,78 @@
+# test-ransack-scope-and-column-same-name.rb
+
+# This is a stand-alone test case.
+
+# Run it in your console with: `ruby test-ransack-scope-and-column-same-name.rb`
+
+# If you change the gem dependencies, run it with:
+# `rm gemfile* && ruby test-ransack-scope-and-column-same-name.rb`
+
+unless File.exist?('Gemfile')
+  File.write('Gemfile', <<-GEMFILE)
+    source 'https://rubygems.org'
+
+    # Rails master
+    gem 'rails', github: 'rails/rails', branch: '6-1-stable'
+
+    # Rails last release
+    # gem 'rails'
+
+    gem 'sqlite3'
+    gem 'ransack', github: 'activerecord-hackery/ransack'
+  GEMFILE
+
+  system 'bundle install'
+end
+
+require 'bundler'
+Bundler.setup(:default)
+
+require 'active_record'
+require 'minitest/autorun'
+require 'logger'
+require 'ransack'
+
+# This connection will do for database-independent bug reports.
+ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: ':memory:')
+ActiveRecord::Base.logger = Logger.new(STDOUT)
+
+# Display versions.
+message = "Running test case with Ruby #{RUBY_VERSION}, Active Record #{
+  ::ActiveRecord::VERSION::STRING}, Arel #{Arel::VERSION} and #{
+  ::ActiveRecord::Base.connection.adapter_name}"
+line = '=' * message.length
+puts line, message, line
+
+ActiveRecord::Schema.define do
+  create_table :users, force: true do |t|
+    t.boolean :active, null: false, default: true
+  end
+end
+
+class User < ActiveRecord::Base
+  scope :activated, -> (boolean = true) { where(active: boolean) }
+
+  private
+
+  def self.ransackable_scopes(auth_object = nil)
+    %i(activated)
+  end
+end
+
+class BugTest < Minitest::Test
+  def test_activated_scope_equals_true
+    sql = User.ransack({ activated: true }).result.to_sql
+    puts sql
+    assert_equal(
+      "SELECT \"users\".* FROM \"users\" WHERE \"users\".\"active\" = 1", sql
+      )
+  end
+
+  def test_activated_scope_equals_false
+    sql = User.ransack({ activated: false }).result.to_sql
+    puts sql
+    assert_equal(
+      "SELECT \"users\".* FROM \"users\"", sql
+      )
+  end
+end

data/bug_report_templates/test-ransacker-arel-present-predicate.rb

@@ -0,0 +1,71 @@
+# test-ransacker-arel-present-predicate.rb
+
+# Run it in your console with: `ruby test-ransacker-arel-present-predicate.rb`
+
+# If you change the gem dependencies, run it with:
+# `rm gemfile* && ruby test-ransacker-arel-present-predicate.rb`
+
+unless File.exist?('Gemfile')
+  File.write('Gemfile', <<-GEMFILE)
+    source 'https://rubygems.org'
+
+    # Rails master
+    gem 'rails', github: 'rails/rails', branch: '6-1-stable'
+
+    # Rails last release
+    # gem 'rails'
+
+    gem 'sqlite3'
+    gem 'ransack', github: 'activerecord-hackery/ransack'
+  GEMFILE
+
+  system 'bundle install'
+end
+
+require 'bundler'
+Bundler.setup(:default)
+
+require 'active_record'
+require 'minitest/autorun'
+require 'logger'
+require 'ransack'
+
+# This connection will do for database-independent bug reports.
+ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: ':memory:')
+ActiveRecord::Base.logger = Logger.new(STDOUT)
+
+# Display versions.
+message = "Running test case with Ruby #{RUBY_VERSION}, Active Record #{
+  ::ActiveRecord::VERSION::STRING}, Arel #{Arel::VERSION} and #{
+  ::ActiveRecord::Base.connection.adapter_name}"
+line = '=' * message.length
+puts line, message, line
+
+ActiveRecord::Schema.define do
+  create_table :projects, force: true do |t|
+    t.string :name
+    t.string :number
+  end
+end
+
+class Project < ActiveRecord::Base
+  ransacker :name do
+    Arel.sql('projects.name')
+  end
+
+  ransacker :number do |parent|
+    parent.table[:number]
+  end
+end
+
+class BugTest < Minitest::Test
+  def test_ransackers
+    sql = Project.ransack({ number_present: 1 }).result.to_sql
+    puts sql
+    assert_equal "SELECT \"projects\".* FROM \"projects\" WHERE (\"projects\".\"number\" IS NOT NULL AND \"projects\".\"number\" != '')", sql
+
+    sql = Project.ransack({ name_present: 1 }).result.to_sql
+    puts sql
+    assert_equal "SELECT \"projects\".* FROM \"projects\" WHERE (projects.name IS NOT NULL AND projects.name != '')", sql
+  end
+end