I would either just write "an iterator", or "a function assignable to iter.Seq or iter.Seq2". Assignability is a well-defined term that seems more precise than talking about a signature being "like" something.
Out of curiosity: From the documentation you quote, it seems that if I do `type MyString string`, that would not be allowed? Because that seems a strange restriction to me - but it also seems strange to me to go out of your way to include all the nuance when it comes to iter.Seq, but then not put that nuance into the documentation of any of the other types. Like, you say "or `slice`", but `slice` is not a type, so presumably that means "any slice type"? Or does it mean something like "`[]T`, where `T` is any type" (so in particular not defined types). Or does it mean "a slice of some further constrained type"? Clearly there is ambiguity in the existing docs. So just saying "it can also be an iterator" or "it can also be iter.Seq" should be acceptable? On Thu, 14 Nov 2024 at 20:20, 'TheDiveO' via golang-nuts < golang-nuts@googlegroups.com> wrote: > Background: I'm currently working on making the Gomega matcher library > <https://github.com/onsi/gomega> iterator-aware as first-class citizens. > That is, matchers working on "collection" types such as slice and map will > then accept iterator functions and act accordingly. As I also work on > updating the matcher documentation I'm struggling with terminology/wording. > Please keep in mind that the matcher documentation needs to be sweet and > short, as there are repetitive mentioning of iterator handling appearing in > multiple places. > > To use a concrete example, BeEmpty() <https://github.com/onsi/gomega> > currently > pre-iterator is described as follows: > > [...]* succeeds if *ACTUAL is, in fact, empty. ACTUAL must be of type > string, array, map, chan, or slice. It is an error for it to have any > other type. > > Here, I want now to add that *ACTUAL* additionally can be an iterator in > a hopefully concise, yet compact way. Please note that we don't want to > support any range-able value here, just iterators. > > Now, does the term "*iterator*" always refer to a function, and in > particular, to "*a function that passes successive elements of a sequence > to a callback function*"? [package iter, section Iterators > <https://pkg.go.dev/iter#hdr-Iterators>] > > How can I guide devs new to Go's iterator pattern to quickly grasp that > *ACTUAL* can be a function that is "assignable to" (i.e., "AssignableTo" > in reflect speak) iter.Seq and/or iter.Seq2 . Is the following phrasing > (bold to emphasize the new part) acceptable? Can this be improved (without > singing an opera)? > > [...]* succeeds if *ACTUAL is, in fact, empty. ACTUAL must be of type > string, array, map, chan, or slice. *Starting with Go 1.23,** ACTUAL can > be also an iterator function with an iter.Seq or iter.Seq2-like signature* > * .* It is an error for it to have any other type. > > > > -- > You received this message because you are subscribed to the Google Groups > "golang-nuts" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to golang-nuts+unsubscr...@googlegroups.com. > To view this discussion visit > https://groups.google.com/d/msgid/golang-nuts/d736f3a4-6a3d-4925-9f42-3e4189393cc1n%40googlegroups.com > <https://groups.google.com/d/msgid/golang-nuts/d736f3a4-6a3d-4925-9f42-3e4189393cc1n%40googlegroups.com?utm_medium=email&utm_source=footer> > . > -- You received this message because you are subscribed to the Google Groups "golang-nuts" group. To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts+unsubscr...@googlegroups.com. To view this discussion visit https://groups.google.com/d/msgid/golang-nuts/CAEkBMfFmt%2BeoFUPjmEe-m-SbiFHiSLvDdLackWgrKOtVK2Hv6A%40mail.gmail.com.
