xerrors: adds IsOneOf

[lsiv568]

After reading Proposal: Go 2 Error Inspection I absolutely loved the introduction of the Is API. I looked around some of my go codebases and immediately realized how it could improve readability by removing verbose equality checking. After this exercise, I saw how the introduction of an IsOneOf API would further remove verbosity by allowing for the following change:

Before

...
err := test.DoSomething()
if err == test.ErrExpected1 || err == test.ErrExpected2 || err == test.ErrExpected3 {
    return
}
...

After

var expectedErrors = []errors{test.ErrExpected1, test.ErrExpected2,  test.ErrExpected3}
...
err := test.DoSomething()
if xerrors.IsOneOf(expectedErrors, err) {
    return
}
...

I believe the After is both more terse and readable. To that end, I have created this pull request.

[googlebot]

Thanks for your pull request. It looks like this may be your first contribution to a Google open source project (if not, look below for help). Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please visit https://cla.developers.google.com/ to sign.

Once you've signed (or fixed any issues), please reply here (e.g. I signed it!) and we'll verify it.

---

What to do if you already signed the CLA

Individual signers

• It's possible we don't have your GitHub username or you're using a different email address on your commit. Check your existing CLA data and verify that your email is set on your git commits.

Corporate signers

• Your company has a Point of Contact who decides which employees are authorized to participate. Ask your POC to be added to the group of authorized contributors. If you don't know who your Point of Contact is, direct the Google project maintainer to go/cla#troubleshoot (Public version).
• The email used to register you as an authorized contributor must be the email used for the Git commit. Check your existing CLA data and verify that your email is set on your git commits.
• The email used to register you as an authorized contributor must also be attached to your GitHub account.

[lsiv568]

I signed it!

[googlebot]

CLAs look good, thanks!

[jba]

Thanks so much for your contribution. Unfortunately, we can't accept it in this form.

First, Go development is done with Gerrit (see https://go-review.googlesource.com). We don't accept GitHub PRs.

Second, the xerrors repo is part of a pending proposal. You should first get your suggestion added to the proposal before sending a PR.

Although you're welcome to make your case on the issue, we think it's unlikely that IsOneOf would be accepted. We try to keep our APIs small, and IsOneOf provides too little benefit on top if Is.

Of course, you are free to use it in your own code.

[dmitshur]

First, Go development is done with Gerrit (see https://go-review.googlesource.com). We don't accept GitHub PRs.

To clarify, we do accept GitHub PRs (they get imported into Gerrit via GerritBot) in other repositories that are not a part of a pending proposal.

[lsiv568]

@jba Thanks for the reply! I was under the impression that there was a bridge from GitHub to Gerrit which is why I submitted this PR. This was confirmed by dmitshur above. However, I was not aware that the xerrors package was still under proposal. My apologies for the premature PR!!

While I understand the intent is to keep go core APIs small, I also believe IsOneOf functionality is an extremely valid use case that would be widely used/adopted. In an effort to limit the surface area of the API, one possibility could be to change the signature of the Is API to Is(target error, errTypes ...error). An example of prior art can be see in gorilla/websocket. While this does introduce a different order of precedence with other function signatures, it meets both the objective of a small API surface area and broadens the use cases for the API. Thoughts?

[jba]

Thanks for your suggestion. Please make it on the issue.