# Suggest

tells you which method does the thing you want to do

## Disclaimer

I don't recommend you ship this in your Gemfile. Keep it in your system's gems (e.g. `gem install`) and load it as needed (e.g. `irb -rsuggest`, `RUBY_OPT=-rsuggest irb`, etc)

## Installation

```
gem install suggest_rb
```

## Usage

```rb
require 'suggest'

# Object#what_returns? tells you which method returns the value
[1,2,3].what_returns? 1
=> [:first, :min]

# You can also specify the args you want that method to take
[1,2,3].what_returns? [1], args: [1]
=> [:first, :take, :grep, :min]

# By default, it only returns methods that don't mutate the object
[1,2,3].what_returns? [1], args: [1], allow_mutation: true
=> [:first, :take, :shift, :grep, :min]

# It works on several core modules including String
"HELLO".what_returns? "hello"
=> [:downcase, :swapcase]

# You can also specify a block that you want the method to accept
[1,2,3,4].what_returns?({true => [2,4], false => [1,3]}) { |n| n % 2 == 0 }
=> [:group_by]

# Object#what_mutates? tells you which method changes the object to the desired state
[1,2,3].what_mutates? [2, 3]
=> [:shift]

# You can also match on the return value
[1,2,3].what_mutates? [2, 3], returns: 1
=> [:shift]

[1,2,3].what_mutates? [2, 3], returns: 2
=> []

# You can specify which args to pass to the method
[1,2,3].what_mutates? [3], args: [2]
=> [:shift]

# It also works on a bunch of core modules
"HELLO".what_mutates? "hello"
=> [:swapcase!, :downcase!]

# And you can give it a block as well
[1,2,3,4].what_mutates? [2,4] { |n| n % 2 == 0 }
=> [:select!, :keep_if]

# You can use a lambda as an expected
[1,2,3,4].what_returns? -> (something_that) { something_that.to_i == 4 }
=> [:count, :length, :size, :last, :max]

# It respects the ruby version
# ruby 2.4.3
{a: 1, b: 2}.what_returns?({})
=> []
# ruby 2.5.0
{a: 1, b: 2}.what_returns?({})
=> [:slice]
```

## Note to Self

Snippet to use in `bin/console` for finding methods for blacklisting:

```
Suggest::SUGGEST_MODS.flat_map { |k| [k].product(k.instance_methods) }.select { |k, v| v == :rand }.map { |k, v| k.instance_method(v).owner }.uniq
```