v1.15.1

UPDATED:
* Dep/go ver bumps
* gated some WIP stuff

.pdsh.wip/types.go

@@ -0,0 +1,60 @@
+package pdsh
+
+type (
+	/*
+		Generator is one of the PDSH host generators/iterators offered by this module.
+
+		Note that these generators/iterators are *stateful*, which means they shouldn't
+		(probably; I'm not your dad) be used concurrently (unless you want some hard-to-debug results)
+		and all methods advance the generator - so you probably don't want to call both Generate() and
+		Next()/Host() on the same instance, for example.
+	*/
+	Generator interface {
+		/*
+			Generate provides a Go-native iterator (also called a "RangeFunc" or "range over function type")
+			as found in Go 1.23 onwards.
+
+			See the assocaied blog entry for details: https://go.dev/blog/range-functions
+
+			Essentially it allows for e.g.:
+
+				for host := range (Generator).Generate() {
+					// ...
+				}
+
+			which is the "new standard" approach for iteration.
+		*/
+		Generate() (yieldFunc func(yield func(host string) (done bool)))
+		/*
+			Reset is used to reset a Generator, allowing one to "restart" the generation at the beginning.
+
+			Generators in this module are generally single-use, but can be reset/reused with this method.
+		*/
+		Reset()
+		/*
+			Hosts returns a complete generated hostlist at once if you'd rather not iterate.
+
+			Hosts() *does* perform an iteration in runtime, so the recommendation against concurrency
+			stands, but it calls Reset() when done generating to allow other methods of a Generator to be used.
+		*/
+		Hosts() (hostList []string)
+		/*
+			Next and Host behave like more "traditional" iterators, e.g. like (database/sql).Row.Next().
+
+			Next advances the internal state to the next host, and Host() returns it.
+		*/
+		Next() (done bool)
+		/*
+			Host returns the current host string (or "" if done).
+
+			Be sure to e.g.:
+
+				for (Generator).Next() {
+					host := (Generator).Host()
+				}
+
+			otherwise the Host return value will not change.
+		*/
+		Host() (host string)
+	}
+)