Consider renaming (or aliasing) match_array to contain_exactly

[myronmarston]

In #119 when we added the new expect syntax and chose to not support the operator matchers for that syntax, we had to come up with a name for array.should =~ other_array, and decided on match_array as the name after a rather lengthy discussion. (See #119 (comment) and following for the full conversation).

Working on #393 and seeing how well the matcher name matches the description output for almost all matchers, I realized that match_array's description hints at a better name. The description is contain exactly <pretty printed array>. During a skype call with @xaviershay about #393 he mentioned some confusion about what the exact semantics of match_array are (since match is such a generic term) and I'm thinking that contain_exactly is a better name, e.g.:

expect(results).to contain_exactly(1, 2, 3)

Compare to:

expect(results).to match_array([1, 2, 3])

The fact that with match_array you have to wrap the elements in [ ] has always bugged me a bit (as it makes it more syntactically noisy), but I've always felt like that since match_array has the word "array" in it, the argument should be an array. With contain_exactly it doesn't give that connotation and I think it reads better w/o the array square brackets.

If we do move in this direction, there's a few open questions:

• Do we deprecate match_array and keep only contain_exactly? I'm on the fence about this. On the one had, there's no significant maintenance cost to keeping both. On the other hand, it'll probably never be less painful than it is now to deprecate match_array: we have 2.99 for the migration and transpec will likely support the conversion out of the box. However, I've gotten some feedback on twitter that some users feel like we are renaming/deprecating things too quickly (although, that was more about 2.14 than 2.99, and I think 2.99's deprecation support is significantly more user-friendly)
• If we do keep match_array, will it be confusing that match_array accepts a single array arg where as contain_exactly accepts them splatted out?

/cc @xaviershay @JonRowe @samphippen @soulcutter @alindeman

[JonRowe]

I like contain_exactly, but I'm on the fence about deprecating it, some people might prefer match_array, especially if you're passing in a variable. e.g. expect(something.result).to match_array of_things

[myronmarston]

some people might prefer match_array, especially if you're passing in a variable. e.g. expect(something.result).to match_array of_things

This works pretty OK:

expect(something.result).to contain_exactly(*things)

But I'm on the fence about the deprecation, too.

[JonRowe]

My concern is that requiring people use expect(something.result).to contain_exactly(*things) will alienate people...

[soulcutter]

Newer rubyists aren't as comfortable with the splat operator. I like contains_exactly but I would keep the old syntax around, and probably just document that it's identical.

[JonRowe]

Specifying the splat difference of course ;)

[soulcutter]

Indeed

[myronmarston]

OK, I've implemented this in 1f3ab8d, which I've pushed to #393 since I don't want to deal with merge conflicts. I'll close this here to concentrate discussion over there.