new: make collection-related matchers Go 1.23 iterator aware, resolves onsi/gomega#795

[thediveo]

• new internal helper package for dealing with Go 1.23 iterators via reflection; for Go versions before 1.23 this package provides the same helper functions as stubs instead, shielding both the matchers code base as well as their tests from any code that otherwise would not build on pre-iterator versions. This allows to keep new iterator-related matcher code and associated tests inline, hopefully ensuring good maintainability.
• with the exception of ContainElements and ConsistOf, the other iterator-aware matchers do not need to go through producing all collection elements first in order to work on a slice of these elements. Instead, they directly work on the collection elements individually as their iterator produces them.
• BeEmpty: iter.Seq, iter.Seq2 w/ tests
• HaveLen: iter.Seq, iter.Seq2 w/ tests
• HaveEach: iter.Seq, iter.Seq2 w/ tests
• ContainElement: iter.Seq, iter.Seq2 w/ tests
• HaveExactElements: iter.Seq, iter.Seq2 w/ tests
• ContainElements: iter.Seq, iter.Seq2 w/ tests
• ConsistOf: iter.Seq, iter.Seq2 w/ test
• HaveKey: iter.Seq2 only w/ test
• HaveKeyWithValue: iter.Seq2 only w/ test
• updated documentation.

[onsi]

wonderful :) will take a close look today/tomorrow. thanks for this!

[onsi]

hey this is fantastic - thank you. it's clear a lot of care, time, and thought when into both the code and the documentation and I really appreciate that! 🤩

i've merged it in. The only thought I had, looking through it, is around output when the matchers fail. For example, if you pass ContainElement a slice Gomega will spit out the whole slice along with the message "to contain X". My sense is that seeing the whole slice is often helpful for understanding the failure.

I believe the new code would emit the iterator function instead of the returned elements. In part this is a good thing: no need to collect all the elements to make an assertion, especially when you don't need them all to succeed/fail. But I wonder how it'll play out as folks start using it in anger.

None of that needs to be changed today. I say we ship this and get it out there. If folks start opening issues and/or we start to bump into this pain signal we can consider subsequent improvements. Sound good? You good with me cutting a release soon?

[thediveo]

Yes on all your points!

There are different ways to alleviate:

• Go's "make it explicit" attitude
  • either standard (x) lib helpers to reduce iters to slices or maps before passing the latter as actual,
  • Gomera giter convenience package using generics
• doing the slice/map under the hood, either partial or completely
• keeping the already iterated elements to provide better details up to the point of failure.

[thediveo]

and yes, please cut a release if you please 😀

[onsi]

done! and makes sense on the ways to alleviate. Thanks for this super valuable contribution!