<commit_before># Ransack

[![Build Status](https://travis-ci.org/activerecord-hackery/ransack.svg)]
(https://travis-ci.org/activerecord-hackery/ransack)
[![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)

Ransack is a rewrite of [MetaSearch]
(https://github.com/activerecord-hackery/meta_search)
created by [<NAME>](http://twitter.com/erniemiller)
and maintained by [<NAME>](http://twitter.com/ryanbigg),
[<NAME>](http://twitter.com/jonatack) and a great group of [contributors]
(https://github.com/activerecord-hackery/ransack/graphs/contributors).
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](http://ransack-demo.herokuapp.com/users/advanced_search)
search forms for your Ruby on Rails application (demo source code
[here](https://github.com/activerecord-hackery/ransack_demo)).
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](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 (1.6.6).]
(https://github.com/activerecord-hackery/ransack/tree/v1.6.6)

## Getting started

Ransack is compatible with Rails 3 and 4 on Ruby 1.9 and later (Ruby 2.2
recommended). JRuby 9 ought to work as well (see
[this](https://github.com/activerecord-hackery/polyamorous/issues/17)).
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 experimental
support for Mongoid 4.0 (without associations, further details below).

In your Gemfile, for the last officially released gem:

```ruby
gem 'ransack'
```

Or, if you would like to use the latest updates, use the `master` branch:

```ruby
gem 'ransack', github: 'activerecord-hackery/ransack'
```

## 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. 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`.

  4. If passed `distinct: true`, `result` will generate a `SELECT DISTINCT` to<commit_msg>[skip ci] Add issues guidelines to README<commit_after># Ransack

[![Build Status](https://travis-ci.org/activerecord-hackery/ransack.svg)]
(https://travis-ci.org/activerecord-hackery/ransack)
[![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)

Ransack is a rewrite of [MetaSearch]
(https://github.com/activerecord-hackery/meta_search)
created by [<NAME>](http://twitter.com/erniemiller)
and maintained by [<NAME>](http://twitter.com/ryanbigg),
[<NAME>](http://twitter.com/jonatack) and a great group of [contributors]
(https://github.com/activerecord-hackery/ransack/graphs/contributors).
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](http://ransack-demo.herokuapp.com/users/advanced_search)
search forms for your Ruby on Rails application (demo source code
[here](https://github.com/activerecord-hackery/ransack_demo)).
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](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 (1.6.6).]
(https://github.com/activerecord-hackery/ransack/tree/v1.6.6)

## Getting started

Ransack is compatible with Rails 3 and 4 on Ruby 1.9 and later (Ruby 2.2
recommended). JRuby 9 ought to work as well (see
[this](https://github.com/activerecord-hackery/polyamorous/issues/17)).
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 experimental
support for Mongoid 4.0 (without associations, further details below).

In your Gemfile, for the last officially released gem:

```ruby
gem 'ransack'
```

Or, if you would like to use the latest updates, use the `master` branch:

```ruby
gem 'ransack', github: 'activerecord-hackery/ransack'
```

## Issues tracker

* Before filing an issue, please read the [Contributing Guide](CONTRIBUTING.md).
* File an issue if a bug is caused by Ransack, is new (has not already been reported), and _can be reproduced from the information you provide_.
* Contributions are welcome, but please do not add "+1" comments to issues or pull requests :smiley:

## 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. 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`.

  4. If passed `distinct: true`, `result` will generate a `SELECT DISTINCT` to
{'fraction_non_alphanumeric': 0.10231112312474659, 'fraction_numerical': 0.007163130152723341, 'mean_word_length': 4.822187254130606, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 26, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5718977', 'n_tokens_mistral': 2378, 'n_tokens_neox': 2183, 'n_words': 840}