v1.14.4

UPDATED:
* docs for sysutils/paths now link to references.

errs/errs_linux.go

@@ -0,0 +1,9 @@
+package errs
+
+import (
+	"errors"
+)
+
+var (
+	ErrInvalidNs error = errors.New("invalid namespace identifier")
+)

fsutils/funcs_linux.go

@@ -118,6 +118,7 @@ func unsetAttrs(f *os.File, attrs fsAttr) (err error) {
 	}
 	ab = bitmask.MaskBit(curAttrs)
 
+	// TODO: Should this be IsOneOf instad of HasFlag?
 	if !ab.HasFlag(bitmask.MaskBit(attrs)) {
 		return
 	}

funcs_linux.go

@@ -1,11 +1,14 @@
 package sysutils
 
 import (
-	`fmt`
+	"fmt"
-	`os`
+	"os"
+	"strconv"
+	"strings"
 
-	`golang.org/x/sys/unix`
+	"golang.org/x/sys/unix"
-	`r00t2.io/sysutils/envs`
+	"r00t2.io/sysutils/envs"
+	"r00t2.io/sysutils/errs"
 )
 
 // GetIDState returns current ID/elevation information. An IDState should *not* be explicitly created/defined.
@@ -48,3 +51,27 @@ func GetIDState() (ids IDState) {
 
 	return
 }
+
+// NsToFD splits a namespace identifier (e.g. `net:[12345]`) to its type (e.g. `net`) and FD (e.g. `12345`).
+func NsToFD(ns string) (typ string, fd uint64, err error) {
+
+	var fields []string
+
+	fields = strings.SplitN(ns, ":", 2)
+
+	if len(fields) != 2 {
+		err = errs.ErrInvalidNs
+		return
+	}
+
+	fields[1] = strings.TrimPrefix(fields[1], "[")
+	fields[1] = strings.TrimSuffix(fields[1], "]")
+
+	if fd, err = strconv.ParseUint(fields[1], 10, 64); err != nil {
+		return
+	}
+
+	typ = fields[0]
+
+	return
+}

go.mod

@@ -6,17 +6,17 @@ require (
 	github.com/davecgh/go-spew v1.1.1
 	github.com/djherbis/times v1.6.0
 	github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510
-	github.com/shirou/gopsutil/v4 v4.25.6
+	github.com/shirou/gopsutil/v4 v4.25.7
 	golang.org/x/sync v0.16.0
-	golang.org/x/sys v0.34.0
+	golang.org/x/sys v0.35.0
 	honnef.co/go/augeas v0.0.0-20161110001225-ca62e35ed6b8
-	r00t2.io/goutils v1.9.2
+	r00t2.io/goutils v1.9.6
 )
 
 require (
 	github.com/ebitengine/purego v0.8.4 // indirect
 	github.com/go-ole/go-ole v1.3.0 // indirect
-	github.com/lufia/plan9stats v0.0.0-20250317134145-8bc96cf8fc35 // indirect
+	github.com/lufia/plan9stats v0.0.0-20250827001030-24949be3fa54 // indirect
 	github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 // indirect
 	github.com/tklauser/go-sysconf v0.3.15 // indirect
 	github.com/tklauser/numcpus v0.10.0 // indirect

go.sum

@@ -13,12 +13,16 @@ github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510 h1:El6M4kTTCOh6aBiKaU
 github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510/go.mod h1:pupxD2MaaD3pAXIBCelhxNneeOaAeabZDe5s4K6zSpQ=
 github.com/lufia/plan9stats v0.0.0-20250317134145-8bc96cf8fc35 h1:PpXWgLPs+Fqr325bN2FD2ISlRRztXibcX6e8f5FR5Dc=
 github.com/lufia/plan9stats v0.0.0-20250317134145-8bc96cf8fc35/go.mod h1:autxFIvghDt3jPTLoqZ9OZ7s9qTGNAWmYCjVFWPX/zg=
+github.com/lufia/plan9stats v0.0.0-20250827001030-24949be3fa54 h1:mFWunSatvkQQDhpdyuFAYwyAan3hzCuma+Pz8sqvOfg=
+github.com/lufia/plan9stats v0.0.0-20250827001030-24949be3fa54/go.mod h1:autxFIvghDt3jPTLoqZ9OZ7s9qTGNAWmYCjVFWPX/zg=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 h1:o4JXh1EVt9k/+g42oCprj/FisM4qX9L3sZB3upGN2ZU=
 github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55/go.mod h1:OmDBASR4679mdNQnz2pUhc2G8CO2JrUAVFDRBDP/hJE=
 github.com/shirou/gopsutil/v4 v4.25.6 h1:kLysI2JsKorfaFPcYmcJqbzROzsBWEOAtw6A7dIfqXs=
 github.com/shirou/gopsutil/v4 v4.25.6/go.mod h1:PfybzyydfZcN+JMMjkF6Zb8Mq1A/VcogFFg7hj50W9c=
+github.com/shirou/gopsutil/v4 v4.25.7 h1:bNb2JuqKuAu3tRlPv5piSmBZyMfecwQ+t/ILq+1JqVM=
+github.com/shirou/gopsutil/v4 v4.25.7/go.mod h1:XV/egmwJtd3ZQjBpJVY5kndsiOO4IRqy9TQnmm6VP7U=
 github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
 github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 github.com/tklauser/go-sysconf v0.3.15 h1:VE89k0criAymJ/Os65CSn1IXaol+1wrsFHEB8Ol49K4=
@@ -35,9 +39,18 @@ golang.org/x/sys v0.0.0-20220615213510-4f61da869c0c/go.mod h1:oPkhp1MJrh7nUepCBc
 golang.org/x/sys v0.1.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.34.0 h1:H5Y5sJ2L2JRdyv7ROF1he/lPdvFsd0mJHFw2ThKHxLA=
 golang.org/x/sys v0.34.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
+golang.org/x/sys v0.35.0 h1:vz1N37gP5bs89s7He8XuIYXpyY0+QlsKmzipCbUtyxI=
+golang.org/x/sys v0.35.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 honnef.co/go/augeas v0.0.0-20161110001225-ca62e35ed6b8 h1:FW42yWB1sGClqswyHIB68wo0+oPrav1IuQ+Tdy8Qp8E=
 honnef.co/go/augeas v0.0.0-20161110001225-ca62e35ed6b8/go.mod h1:44w9OfBSQ9l3o59rc2w3AnABtE44bmtNnRMNC7z+oKE=
 r00t2.io/goutils v1.9.2 h1:1rcDgJ3MorWVBmZSvLpbAUNC+J+ctRfJQq5Wliucjww=
 r00t2.io/goutils v1.9.2/go.mod h1:76AxpXUeL10uFklxRB11kQsrtj2AKiNm8AwG1bNoBCA=
+r00t2.io/goutils v1.9.3 h1:pR9Ggu5JBpVjfrqNBrZg9bZpKan0TCcwt3MXrSdkhLo=
+r00t2.io/goutils v1.9.3/go.mod h1:76AxpXUeL10uFklxRB11kQsrtj2AKiNm8AwG1bNoBCA=
+r00t2.io/goutils v1.9.4 h1:+Bm72mKhgXs6DRtU3P4sBjqUNwAKAFfdF9lx5bomwQY=
+r00t2.io/goutils v1.9.4/go.mod h1:76AxpXUeL10uFklxRB11kQsrtj2AKiNm8AwG1bNoBCA=
+r00t2.io/goutils v1.9.5 h1:tIBtXKbGPLCkdhHZSESdTZ2QzC1e+8jDToNr/BauWe0=
+r00t2.io/goutils v1.9.5/go.mod h1:76AxpXUeL10uFklxRB11kQsrtj2AKiNm8AwG1bNoBCA=
+r00t2.io/goutils v1.9.6/go.mod h1:76AxpXUeL10uFklxRB11kQsrtj2AKiNm8AwG1bNoBCA=

paths/consts.go

@@ -10,7 +10,6 @@ const (
 
 // Mostly just for reference.
 const (
-	// ModeDir | ModeSymlink | ModeNamedPipe | ModeSocket | ModeDevice | ModeCharDevice | ModeIrregular
 	modeDir              pathMode = pathMode(fs.ModeDir)
 	modeSymlink          pathMode = pathMode(fs.ModeSymlink)
 	modePipe             pathMode = pathMode(fs.ModeNamedPipe)

paths/consts_windows.go

@@ -7,7 +7,7 @@ const (
 		MaxSymLinkLevel on Windows is weird; Microsoft calls them "reparse points".
 
 		And it changes on the Windows version you're on, but it's been 63 past Windows Server 2003/Windows XP.
-		They're *very* EOL, so I'm completely ignoring them.
+		They're *very* EOL, so I'm completely ignoring earlier cases.
 
 		https://learn.microsoft.com/en-us/windows/win32/fileio/symbolic-link-programming-consideration
 	*/

paths/funcs.go

@@ -93,7 +93,7 @@ func ExpandHome(p *string) (err error) {
 }
 
 /*
-GetFirst is the file equivalent of envs.GetFirst.
+GetFirst is the file equivalent of [r00t2.io/sysutils/envs.GetFirst].
 
 It iterates through paths, normalizing them along the way
 (so abstracted paths such as ~/foo/bar.txt and relative paths
@@ -107,7 +107,7 @@ If no path exists, ok will be false.
 As always, results are not guaranteed due to permissions, etc.
 potentially returning an inaccurate result.
 
-This is a thin wrapper around GetFirstWithRef.
+This is a thin wrapper around [GetFirstWithRef].
 */
 func GetFirst(p []string) (content []byte, isDir, ok bool) {
 
@@ -117,9 +117,9 @@ func GetFirst(p []string) (content []byte, isDir, ok bool) {
 }
 
 /*
-GetFirstWithRef is the file equivalent of envs.GetFirstWithRef.
+GetFirstWithRef is the file equivalent of [r00t2.io/sysutils/envs.GetFirstWithRef].
 
-It behaves exactly like GetFirst, but with an additional returned value, idx,
+It behaves exactly like [GetFirst], but with an additional returned value, idx,
 which specifies the index in p in which a path was found.
 
 As always, results are not guaranteed due to permissions, etc.
@@ -162,9 +162,9 @@ func GetFirstWithRef(p []string) (content []byte, isDir, ok bool, idx int) {
 }
 
 /*
-Len returns the number of path segments in p, as split with the same param signature to Segment.
+Len returns the number of path segments in p, as split with the same param signature to [Segment].
 
-See Segment for details on abs and strict.
+See [Segment] for details on abs and strict.
 */
 func Len(p string, abs, strict bool) (segments int) {
 
@@ -174,9 +174,9 @@ func Len(p string, abs, strict bool) (segments int) {
 }
 
 /*
-LenSys returns the number of path segments in p, as split with the same param signature to SegmentSys.
+LenSys returns the number of path segments in p, as split with the same param signature to [SegmentSys].
 
-See Segment for details on abs and strict.
+See [Segment] for details on abs and strict.
 */
 func LenSys(p string, abs, strict bool) (segments int) {
 
@@ -188,9 +188,9 @@ func LenSys(p string, abs, strict bool) (segments int) {
 /*
 MakeDirIfNotExist will create a directory at a given path if it doesn't exist.
 
-See also the documentation for RealPath.
+See also the documentation for [RealPath].
 
-This is a bit more sane option than os.MkdirAll as it will normalize paths a little better.
+This is a bit more sane option than [os.MkdirAll] as it will normalize paths a little better.
 */
 func MakeDirIfNotExist(p string) (err error) {
 
@@ -234,9 +234,9 @@ path syntax/string itself is not supported on the runtime OS. This can be done v
 
 	if errors.Is(err, fs.ErrInvalid) {...}
 
-RealPath is simply a wrapper around ExpandHome(path) and filepath.Abs(*path).
+RealPath is simply a wrapper around [ExpandHome] and [filepath.Abs].
 
-Note that RealPath does *not* resolve symlinks. Only RealPathExistsStatTarget does that.
+Note that RealPath does *not* resolve symlinks. Only [RealPathExistsStatTarget] does that.
 */
 func RealPath(p *string) (err error) {
 
@@ -252,7 +252,7 @@ func RealPath(p *string) (err error) {
 }
 
 /*
-RealPathJoin combines RealPath with (path).Join.
+RealPathJoin combines [RealPath] with [path.Join].
 
 If dst is nil, then p will be updated with the new value.
 You probably don't want that.
@@ -283,7 +283,7 @@ func RealPathJoin(p, dst *string, subPaths ...string) (err error) {
 }
 
 /*
-RealPathJoinSys combines RealPath with (path/filepath).Join.
+RealPathJoinSys combines [RealPath] with [path/filepath.Join].
 
 If dst is nil, then path will be updated with the new value.
 You probably don't want that.
@@ -314,10 +314,10 @@ func RealPathJoinSys(p, dst *string, subPaths ...string) (err error) {
 }
 
 /*
-RealPathExists is like RealPath, but will also return a boolean as to whether the path
+RealPathExists is like [RealPath], but will also return a boolean as to whether the path
 actually exists or not.
 
-Note that err *may* be os.ErrPermission/fs.ErrPermission, in which case the exists value
+Note that err *may* be [os.ErrPermission] / [fs.ErrPermission], in which case the exists value
 cannot be trusted as a permission error occurred when trying to stat the path - if the
 calling user/process does not have read permission on e.g. a parent directory, then
 exists may be false but the path may actually exist. This condition can be checked via
@@ -325,9 +325,9 @@ via:
 
 	if errors.Is(err, fs.ErrPermission) {...}
 
-See also the documentation for RealPath.
+See also the documentation for [RealPath].
 
-In those cases, it may be preferable to use RealPathExistsStat and checking stat for nil.
+In those cases, it may be preferable to use [RealPathExistsStat] and checking stat for nil.
 */
 func RealPathExists(p *string) (exists bool, err error) {
 
@@ -348,11 +348,11 @@ func RealPathExists(p *string) (exists bool, err error) {
 }
 
 /*
-RealPathExistsStat is like RealPathExists except it will also return the fs.FileInfo
+RealPathExistsStat is like [RealPathExists] except it will also return the [io/fs.FileInfo]
 for the path (assuming it exists).
 
 If stat is nil, it is highly recommended to check err via the methods suggested
-in the documentation for RealPath and RealPathExists.
+in the documentation for [RealPath] and [RealPathExists].
 */
 func RealPathExistsStat(p *string) (exists bool, stat fs.FileInfo, err error) {
 
@@ -376,7 +376,7 @@ RealPathExistsStatTarget is the only "RealPather" that will resolve p to the (fi
 
 If p is not a symlink but does exist, the tgt* will reflect the same as p*.
 
-See WalkLink for details on relRoot and other assorted rules/logic (RealPathExistsStatTarget wraps WalkLink).
+See [WalkLink] for details on relRoot and other assorted rules/logic (RealPathExistsStatTarget wraps [WalkLink]).
 */
 func RealPathExistsStatTarget(p *string, relRoot string) (pExists, tgtExists, wasLink bool, pStat fs.FileInfo, tgtStat fs.FileInfo, err error) {
 
@@ -413,7 +413,7 @@ func RealPathExistsStatTarget(p *string, relRoot string) (pExists, tgtExists, wa
 	return
 }
 
-// SearchFsPaths gets a file/directory/etc. path list based on the provided criteria.
+// SearchFsPaths gets a file/directory/etc. path list based on the provided [FsSearchCriteria].
 func SearchFsPaths(matcher FsSearchCriteria) (found, miss []*FsSearchResult, err error) {
 
 	var matched *FsSearchResult
@@ -465,11 +465,11 @@ func SearchFsPaths(matcher FsSearchCriteria) (found, miss []*FsSearchResult, err
 }
 
 /*
-SearchFsPathsAsync is exactly like SearchFsPaths, but dispatches off concurrent
+SearchFsPathsAsync is exactly like [SearchFsPaths], but dispatches off concurrent
 workers for the filtering logic instead of performing iteratively/recursively.
 It may, in some cases, be *slightly more* performant and *slightly less* in others.
-Note that unlike SearchFsPaths, the results written to the
+Note that unlike [SearchFsPaths], the results written to the
-FsSearchCriteriaAsync.ResChan are not guaranteed to be in any predictable order.
+[FsSearchCriteriaAsync].ResChan are not guaranteed to be in any predictable order.
 
 All channels are expected to have already been initialized by the caller.
 They will not be closed by this function.
@@ -574,7 +574,7 @@ func SearchFsPathsAsync(matcher FsSearchCriteriaAsync) {
 }
 
 /*
-Segment returns path p's segments as a slice of strings, using GenericSeparator as a separator.
+Segment returns path p's segments as a slice of strings, using [GenericSeparator] as a separator.
 
 If abs is true, the placeholder leading prefix(es) (if any) of GenericSeparator will be kept in-place;
 otherwise it/they will be trimmed out.
@@ -583,14 +583,14 @@ e.g.:
 	abs == true:  //foo/bar/baz => []string{"", "", "foo", "bar", "baz"}
 	abs == false: /foo/bar/baz => []string{"foo", "bar", "baz"}
 
-If strict is true, any trailing GenericSeparator will be kept in-place;
+If strict is true, any trailing [GenericSeparator] will be kept in-place;
 otherwise they will be trimmed out.
 e.g. (assuming abs == false):
 
 	strict == true:  /foo/bar/baz// => []string{"foo", "bar", "baz", "", ""}
 	strict == false: /foo/bar/baz/ => []string{"foo", "bar", "baz"}
 
-It is recommended to call RealPath for path's ptr first for normalization.
+It is recommended to call [RealPath] for path's ptr first for normalization.
 */
 func Segment(p string, abs, strict bool) (segments []string) {
 
@@ -606,7 +606,7 @@ func Segment(p string, abs, strict bool) (segments []string) {
 	return
 }
 
-// SegmentSys is exactly like Segment, except using os.PathSeparator instead of GenericSeparator.
+// SegmentSys is exactly like [Segment], except using [os.PathSeparator] instead of [GenericSeparator].
 func SegmentSys(p string, abs, strict bool) (segments []string) {
 
 	if !abs {
@@ -622,14 +622,17 @@ func SegmentSys(p string, abs, strict bool) (segments []string) {
 }
 
 /*
-Strip is like Segment but trims out the leading n number of segments and reassembles the path using path.Join.
+Strip is like [Segment] but trims out the leading n number of segments and reassembles the path using [path.Join].
 
 n may be negative, in which case the *trailing* n number of segments will be trimmed out.
 (i.e. n == -1, p == `foo/bar/baz/quux` would be `foo/bar/baz`, not `bar/baz/quux`)
 
 If you require more traditional slicing (e.g. with interval),
-you may want to use path.Join with a sliced result of Segment instead.
+you may want to use [path.Join] with a sliced result of [Segment] instead.
-e.g.: *only* the *last* n segments: path.Join(Segment(p, ...)[Len(p, ...)-n:]...)
+
+e.g.: *only* the *last* n segments:
+
+	path.Join(Segment(p, ...)[Len(p, ...)-n:]...)
 
 If n == 0 or int(math.Abs(float64(n))) >= len(Segment(p, ...)), no transformation will be done.
 
@@ -664,7 +667,7 @@ func Strip(p string, abs, strict bool, n int) (slicedPath string) {
 	return
 }
 
-// StripSys is exactly like Strip but using (path/filepath).Join and SegmentSys.
+// StripSys is exactly like [Strip] but using [path/filepath.Join] and [SegmentSys].
 func StripSys(p string, abs, strict bool, n int) (slicedPath string) {
 
 	var pLen int
@@ -692,19 +695,19 @@ func StripSys(p string, abs, strict bool, n int) (slicedPath string) {
 }
 
 /*
-WalkLink walks the recursive target(s) of lnk (unless/until MaxSymlinkLevel is hit, which will trigger ErrMaxSymlinkLevel)
+WalkLink walks the recursive target(s) of lnk (unless/until [MaxSymlinkLevel] is hit, which will trigger [ErrMaxSymlinkLevel])
 until it reaches a real (non-symlink) target.
 
 lnk will have RealPath called on it first.
 
 If lnk is not a symlink, then tgts == []string{lnk} and err = nil.
 
-A broken link will return fs.ErrNotExist, with tgts containing the targets up to and including the path that triggered the error.
+A broken link will return [io/fs.ErrNotExist], with tgts containing the targets up to and including the path that triggered the error.
 
-If lnk itself does not exist, tgts will be nil and err will be that of fs.ErrNotExist.
+If lnk itself does not exist, tgts will be nil and err will be that of [io/fs.ErrNotExist].
 
 relRoot is a root directory to resolve relative links to. If empty, relative link target `t` from link `l` will be treated
-as relative to `(path/filepath).Dir(l)` (that is to say, `t = filepath.Join(filepath.Dir(l), os.Readlink(l))`).
+as relative to [path/filepath.Dir] on l (that is to say, `t = filepath.Join(filepath.Dir(l), os.Readlink(l))`).
 */
 func WalkLink(lnk, relRoot string) (tgts []string, err error) {
 
@@ -766,7 +769,7 @@ func WalkLink(lnk, relRoot string) (tgts []string, err error) {
 }
 
 /*
-filterTimes checks a times.Timespec of a file using:
+filterTimes checks a [times.Timespec] of a file using:
   - an age specified by the caller
   - an ageType bitmask for types of times to compare
   - an olderThan bool (if false, the file must be younger than)

paths/funcs_fssearchcriteria.go

@@ -11,13 +11,15 @@ import (
 )
 
 /*
-	Match returns match (a  ptr to a FsSearchResult if the specified path matches, otherwise nil),
+	Match returns match (a ptr to a [FsSearchResult] if the specified path matches, otherwise nil),
-	miss (ptr the specified path does not match, otherwise nil), and an fs.DirEntry and fs.FileInfo
+	miss (ptr the specified path does not match, otherwise nil), and an [io/fs.DirEntry] and [io/fs.FileInfo]
-	for path. d and/or fi may be nil.
+	for path.
+
+	d and/or fi may be nil.
 
 	If err is not nil, it represents an unexpected error and as such, both match and miss should be nil.
 
-	Match, miss, and err will all be nil if the filesystem object/path does not exist.
+	match, miss, and err will all be nil if the filesystem object/path does not exist.
 */
 func (f *FsSearchCriteria) Match(path string, d fs.DirEntry, fi fs.FileInfo) (match, miss *FsSearchResult, err error) {
 
@@ -111,7 +113,7 @@ func (f *FsSearchCriteria) Match(path string, d fs.DirEntry, fi fs.FileInfo) (ma
 		miss = &m
 		return
 	} else if typeMode != 0 {
-		if !typeFilter.HasFlag(bitmask.MaskBit(typeMode)) {
+		if !typeFilter.IsOneOf(bitmask.MaskBit(typeMode)) {
 			m.MissReason = MissType
 			miss = &m
 			return

paths/funcs_pathtimetype.go

@@ -4,7 +4,7 @@ import (
 	`r00t2.io/goutils/bitmask`
 )
 
-// Mask returns a bitmask.MaskBit from a pathTimeType.
+// Mask returns a [r00t2.io/goutils/bitmask.MaskBit] from a pathTimeType.
 func (p *pathTimeType) Mask() (mask *bitmask.MaskBit) {
 
 	mask = bitmask.NewMaskBitExplicit(uint(*p))

paths/types.go

@@ -109,7 +109,7 @@ type FsSearchCriteriaAsync struct {
 	SemaphoreCtx context.Context
 }
 
-// FsSearchResult contains a match/miss result for FsSearchCriteria and FsSearchCriteriaAsync.
+// FsSearchResult contains a match/miss result for [FsSearchCriteria] and [FsSearchCriteriaAsync].
 type FsSearchResult struct {
 	/*
 		Path is the path to the object on the filesystem.

pdsh/docs.go

@@ -1,16 +1,27 @@
 /*
-Package pdsh (!! WIP !!) provides PDSH-compatible functionality for parsing group files.
+Package pdsh (!! WIP !!) provides PDSH-compatible functionality for parsing group/gender/etc. files/sources.
 
-Note that this library will *only* source and parse PDSH-compatible host/group files,
+Note that this library will *only* generate the host list/etc.,
 it will not actually connect to anything.
 It simply provides ways of returning lists of hosts using generation rules/patterns.
+Said another way, it does not implement any of PDSH's "rcmd" modules, only the "misc" modules.
 
-Currently, the only supported PDSH module is `misc/dshgroup` but additional/all other
+(As a hint, you can implement SSH connections via [golang.org/x/crypto/ssh] in goroutine'd functions
+using this package to generate the target addresses, etc.)
+
+Currently, the only supported PDSH module is misc/dshgroup (as [r00t2.io/sysutils/pdsh/dshgroup]) but additional/all other
 host list modules are planned.
 
-For details, see:
+This package deviates slightly from PDSH in some areas; allowing for more loose or more strict behavior occasionally.
+Whenever a deviation is offered, this package allows for configuring the generator to behave exactly like PDSH instead
+(if the deviating behavior is enabled by default).
 
-  - https://github.com/chaos/pdsh/
+For details, see the [chaos/pdsh GitHub], the associated [MAN page source], and/or the [rendered MAN page] (via ManKier).
-  - https://github.com/chaos/pdsh/blob/master/doc/pdsh.1.in
+You may also want to see the ManKier rendered MAN pages for the [pdsh package].
+
+[chaos/pdsh GitHub]: https://github.com/chaos/pdsh/
+[MAN page source]: https://github.com/chaos/pdsh/blob/master/doc/pdsh.1.in
+[rendered MAN page]: https://www.mankier.com/1/pdsh
+[pdsh package]: https://www.mankier.com/package/pdsh
 */
 package pdsh

pdsh/dshgroup/consts.go

@@ -1,4 +1,4 @@
-package pdsh
+package dshgroup
 
 import (
 	"regexp"
@@ -14,5 +14,5 @@ const (
 var (
 	dshGrpDefGrpDir    string       = "/etc/dsh/group"
 	dshGrpInclPtrn     *remap.ReMap = &remap.ReMap{Regexp: regexp.MustCompile(`^\s*#include\s+(?P<incl>.+)$`)}
-	dshGrpSubTokenPtrn *remap.ReMap = &remap.ReMap{Regexp: regexp.MustCompile(`^(?P<start_pad>0*)(?P<start>[1-9]+[0-9]*)?(?:-(?P<end_pad>0*)(?P<end>[1-9]+[0-9]*))?$`)}
+	dshGrpSubTokenPtrn *remap.ReMap = &remap.ReMap{Regexp: regexp.MustCompile(`^(?P<start_pad>0+)?(?P<start>[0-9]+)(-(?P<end_pad>0+)?(?P<end>[0-9]+))?$`)}
 )

pdsh/dshgroup/docs.go

@@ -0,0 +1,30 @@
+/*
+Package dshgroup implements so-called "DSH (Dancer's SHell) Group" files.
+
+It is equivalent to PDSH's [misc/dshgroup] module. ([source])
+
+Be sure to read the [HOSTLIST EXPRESSIONS] section in the MAN page.
+
+# Notable Differences
+
+  * This package allows for *never* reading the DSHGROUP_PATH env var (PDSH always reads it) via the "NoEnv" option.
+
+  * This package allows for not adding /etc/dsh/group/<group> files by default via the "NoDefault" option.
+
+  * This package allows for not adding ~/.dsh/group/<group> files by default via the "NoHome" option.
+
+  * This package allows for a "ForceLegacy" mode, disabled by default, that DISABLES the PDSH
+    extension for "#include <path/group>" extension.
+    If ForceLegacy is enabled, "#include ..." lines will be treated as comment lines (ignored) instead.
+
+  * This package allows for whitespace between group patterns. This can be disabled by the "StrictWhitespace" option.
+
+# TODO/WIP/Not Yet Implemented
+
+This package is not yet complete.
+
+[misc/dshgroup]: https://www.mankier.com/1/pdsh#dshgroup_module_options
+[source]: https://github.com/chaos/pdsh/blob/master/src/modules/dshgroup.c
+[HOSTLIST EXPRESSIONS]: https://www.mankier.com/1/pdsh#Hostlist_Expressions
+*/
+package dshgroup

pdsh/dshgroup/errs.go

@@ -1,10 +1,11 @@
-package pdsh
+package dshgroup
 
 import (
 	"errors"
 )
 
 var (
+	ErrEmptyDshGroupTok    error = errors.New("empty dsh group pattern token")
 	ErrInvalidDshGrpSyntax error = errors.New("invalid dsh group file syntax")
 	ErrInvalidDshGrpPtrn   error = errors.New("invalid dsh group pattern syntax")
 )

pdsh/dshgroup/funcs_dshgrouplister.go

@@ -1,4 +1,4 @@
-package pdsh
+package dshgroup
 
 import (
 	"io/fs"
@@ -170,5 +170,7 @@ For example, assuming the group name `<GROUP>`, the following files will be chec
 */
 func (d *DshGroupLister) GroupedHosts(dedupe bool, searchPaths ...string) (groupedHosts map[string][]string, err error) {
 
+	// TODO
+
 	return
 }

pdsh/dshgroup/funcs_dshgrp.go

@@ -1,4 +1,4 @@
-package pdsh
+package dshgroup
 
 import (
 	"bufio"
@@ -13,8 +13,10 @@ import (
 /*
 ParseDshPtrn parses ptrn using the DSH group pattern ptrn as according to `HOSTLIST EXPRESSSIONS` in pdsh(1).
 `#include` directives are explicitly skipped; this only parses actual generation pattern strings.
+
+The returning generator may either be iterated over with `range` or have `Hosts()` called explicitly. // TODO
 */
-func ParseDshPtrn(ptrn string) (hostList []string, err error) {
+func ParseDshPtrn(ptrn string) (generator *DshGrpGenerator, err error) {
 
 	var r rune
 	var pos int
@@ -24,7 +26,10 @@ func ParseDshPtrn(ptrn string) (hostList []string, err error) {
 	var tok dshGrpToken
 	var strBuf *bytes.Buffer = new(bytes.Buffer)
 	var tokBuf *bytes.Buffer = new(bytes.Buffer)
-	var parser *dshGrpGenerator = &dshGrpGenerator{
+
+	// TODO: users can be specified per-pattern.
+
+	generator = &DshGrpGenerator{
 		tokens:    make([]dshGrpToken, 0),
 		tokenized: make([]string, 0),
 		text:      ptrn,
@@ -54,10 +59,11 @@ func ParseDshPtrn(ptrn string) (hostList []string, err error) {
 					ptrn:    ptrn,
 					r:       r,
 					err:     ErrInvalidDshGrpSyntax,
+					inToken: inToken,
 				}
 				return
 			}
-			parser.tokenized = append(parser.tokenized, strBuf.String())
+			generator.tokenized = append(generator.tokenized, strBuf.String())
 			strBuf.Reset()
 			inToken = true
 		case ']':
@@ -68,6 +74,7 @@ func ParseDshPtrn(ptrn string) (hostList []string, err error) {
 					ptrn:    ptrn,
 					r:       r,
 					err:     ErrInvalidDshGrpSyntax,
+					inToken: inToken,
 				}
 				return
 			}
@@ -78,11 +85,14 @@ func ParseDshPtrn(ptrn string) (hostList []string, err error) {
 					ptrn:    ptrn,
 					r:       r,
 					err:     err,
+					inToken: inToken,
 				}
 				return
 			}
-			parser.tokens = append(parser.tokens, tok)
+			generator.tokens = append(generator.tokens, tok)
 			tokBuf.Reset()
+			// Don't forget the empty element placeholder.
+			generator.tokenized = append(generator.tokenized, "")
 			inToken = false
 		default:
 			if inToken {
@@ -94,11 +104,13 @@ func ParseDshPtrn(ptrn string) (hostList []string, err error) {
 						ptrn:    ptrn,
 						r:       r,
 						err:     ErrInvalidDshGrpSyntax,
+						inToken: inToken,
 					}
 					return
 				}
 				tokBuf.WriteRune(r)
 			} else {
+				// TODO: confirm if inline comments and/or trailing/leading whitespace are handled by pdsh?
 				if strings.TrimSpace(string(r)) == "" || r == '#' {
 					// Whitespace is "invalid" (treat it as the end of the pattern).
 					// Same for end-of-line octothorpes.
@@ -109,11 +121,12 @@ func ParseDshPtrn(ptrn string) (hostList []string, err error) {
 							ptrn:    ptrn,
 							r:       r,
 							err:     ErrInvalidDshGrpSyntax,
+							inToken: inToken,
 						}
 						return
 					}
 					if strBuf.Len() > 0 {
-						parser.tokenized = append(parser.tokenized, strBuf.String())
+						generator.tokenized = append(generator.tokenized, strBuf.String())
 					}
 					break
 				}
@@ -122,12 +135,13 @@ func ParseDshPtrn(ptrn string) (hostList []string, err error) {
 					(r != 0x2d) && // '-'
 					(r != 0x2e) && // '.'
 					!(0x41 <= r && r <= 0x5a) && // 'A' through 'Z' (inclusive)
-					!(0x6a <= r && r <= 0x7a) { // 'a' through 'z' (inclusive)
+					!(0x61 <= r && r <= 0x7a) { // 'a' through 'z' (inclusive)
 					err = &PtrnParseErr{
 						pos:     uint(pos),
 						ptrn:    ptrn,
 						r:       r,
 						err:     ErrInvalidDshGrpPtrn,
+						inToken: inToken,
 					}
 					return
 				}
@@ -154,6 +168,10 @@ func parseDshGrpToken(tokenStr string) (token dshGrpToken, err error) {
 	var sub dshGrpSubtoken
 
 	s = strings.TrimSpace(tokenStr)
+	if s == "" {
+		err = ErrEmptyDshGroupTok
+		return
+	}
 	st = strings.Split(s, ",")
 	token = dshGrpToken{
 		token:     tokenStr,
@@ -190,21 +208,14 @@ func parseDshGrpSubtoken(subTokenStr string) (subtoken dshGrpSubtoken, err error
 	if vals = matches["start_pad"]; vals != nil && len(vals) == 1 {
 		startPad = vals[0]
 	}
-	/*
+
-		Due to a... particular quirk in the regex that I'm too tired to fix,
-		the start_pad may be e.g. "0" (or "00", etc.) and start may be "" if the range starts *at* 0
-		(or 00, 000, etc.).
-	*/
 	if vals = matches["start"]; vals != nil && len(vals) == 1 {
 		if u64, err = strconv.ParseUint(vals[0], 10, 64); err != nil {
 			return
 		}
 		st.start = uint(u64)
-	} else if startPad != "" {
-		// Yeah, regex bug. So we remove one 0 from startPad, and set st.start to 0.
-		st.start = 0 // This is implicit, though.
-		startPad = startPad[:len(startPad)-1]
 	}
+
 	if vals = matches["end_pad"]; vals != nil && len(vals) == 1 {
 		endPad = vals[0]
 	}

pdsh/dshgroup/funcs_dshgrp_test.go

@@ -0,0 +1,59 @@
+package dshgroup
+
+import (
+	`log`
+	`testing`
+
+	`github.com/davecgh/go-spew/spew`
+)
+
+func TestParseDshPtrn(t *testing.T) {
+
+	var err error
+	var idx int
+	var s string
+	var generator *DshGrpGenerator
+	var hostList []string
+	var tgtList []string = []string{
+		"0foo1bar46004quux", "0foo1bar46005quux", "0foo1bar46006quux", "0foo1bar46007quux", "0foo1bar46008quux", "0foo1bar46009quux",
+		"0foo1bar4615quux", "0foo1bar47004quux", "0foo1bar47005quux", "0foo1bar47006quux", "0foo1bar47007quux", "0foo1bar47008quux",
+		"0foo1bar47009quux", "0foo1bar4715quux", "0foo2bar46004quux", "0foo2bar46005quux", "0foo2bar46006quux", "0foo2bar46007quux",
+		"0foo2bar46008quux", "0foo2bar46009quux", "0foo2bar4615quux", "0foo2bar47004quux", "0foo2bar47005quux", "0foo2bar47006quux",
+		"0foo2bar47007quux", "0foo2bar47008quux", "0foo2bar47009quux", "0foo2bar4715quux", "0foo3bar46004quux", "0foo3bar46005quux",
+		"0foo3bar46006quux", "0foo3bar46007quux", "0foo3bar46008quux", "0foo3bar46009quux", "0foo3bar4615quux", "0foo3bar47004quux",
+		"0foo3bar47005quux", "0foo3bar47006quux", "0foo3bar47007quux", "0foo3bar47008quux", "0foo3bar47009quux", "0foo3bar4715quux",
+		"1foo1bar46004quux", "1foo1bar46005quux", "1foo1bar46006quux", "1foo1bar46007quux", "1foo1bar46008quux", "1foo1bar46009quux",
+		"1foo1bar4615quux", "1foo1bar47004quux", "1foo1bar47005quux", "1foo1bar47006quux", "1foo1bar47007quux", "1foo1bar47008quux",
+		"1foo1bar47009quux", "1foo1bar4715quux", "1foo2bar46004quux", "1foo2bar46005quux", "1foo2bar46006quux", "1foo2bar46007quux",
+		"1foo2bar46008quux", "1foo2bar46009quux", "1foo2bar4615quux", "1foo2bar47004quux", "1foo2bar47005quux", "1foo2bar47006quux",
+		"1foo2bar47007quux", "1foo2bar47008quux", "1foo2bar47009quux", "1foo2bar4715quux", "1foo3bar46004quux", "1foo3bar46005quux",
+		"1foo3bar46006quux", "1foo3bar46007quux", "1foo3bar46008quux", "1foo3bar46009quux", "1foo3bar4615quux", "1foo3bar47004quux",
+		"1foo3bar47005quux", "1foo3bar47006quux", "1foo3bar47007quux", "1foo3bar47008quux", "1foo3bar47009quux", "1foo3bar4715quux",
+		"2foo1bar46004quux", "2foo1bar46005quux", "2foo1bar46006quux", "2foo1bar46007quux", "2foo1bar46008quux", "2foo1bar46009quux",
+		"2foo1bar4615quux", "2foo1bar47004quux", "2foo1bar47005quux", "2foo1bar47006quux", "2foo1bar47007quux", "2foo1bar47008quux",
+		"2foo1bar47009quux", "2foo1bar4715quux", "2foo2bar46004quux", "2foo2bar46005quux", "2foo2bar46006quux", "2foo2bar46007quux",
+		"2foo2bar46008quux", "2foo2bar46009quux", "2foo2bar4615quux", "2foo2bar47004quux", "2foo2bar47005quux", "2foo2bar47006quux",
+		"2foo2bar47007quux", "2foo2bar47008quux", "2foo2bar47009quux", "2foo2bar4715quux", "2foo3bar46004quux", "2foo3bar46005quux",
+		"2foo3bar46006quux", "2foo3bar46007quux", "2foo3bar46008quux", "2foo3bar46009quux", "2foo3bar4615quux", "2foo3bar47004quux",
+		"2foo3bar47005quux", "2foo3bar47006quux", "2foo3bar47007quux", "2foo3bar47008quux", "2foo3bar47009quux", "2foo3bar4715quux",
+	}
+
+	if generator, err = ParseDshPtrn("[0-2]foo[1-3]bar[4][6-7]baz[004-009,15]quux"); err != nil {
+		t.Fatal(err)
+	}
+
+	_ = spew.Sdump(generator)
+
+	hostList = generator.Hosts()
+	t.Log(hostList)
+
+	if len(hostList) != len(tgtList) {
+		t.Fatalf("Generated list length (%d) does not match target (%d)", len(hostList), len(tgtList))
+	}
+
+	for idx, s = range hostList {
+		if s != tgtList[idx] {
+			log.Fatalf("Test vector %d ('%s') does not match generated value '%s'", idx+1, tgtList[idx], s)
+		}
+	}
+}

pdsh/dshgroup/funcs_dshgrpgenerator.go

@@ -0,0 +1,36 @@
+package dshgroup
+
+func (d *DshGrpGenerator) Generate() (yieldFunc func(yield func(host string) (done bool))) {
+
+	// TODO
+
+	return
+}
+
+func (d *DshGrpGenerator) Hosts() (hostList []string) {
+
+	// TODO
+
+	return
+}
+
+func (d *DshGrpGenerator) Host() (host string) {
+
+	// TODO
+
+	return
+}
+
+func (d *DshGrpGenerator) Next() (done bool) {
+
+	// TODO
+
+	return
+}
+
+func (d *DshGrpGenerator) Reset() {
+
+	// TODO
+
+	return
+}

pdsh/dshgroup/funcs_ptrnparseerr.go

@@ -1,4 +1,4 @@
-package pdsh
+package dshgroup
 
 import (
 	"fmt"
@@ -8,8 +8,8 @@ import (
 func (p *PtrnParseErr) Error() (errStr string) {
 
 	errStr = fmt.Sprintf(
-		"Parse error in pattern '%s', position %d rune '%s': %v",
+		"Parse error in pattern '%s', position %d rune '%s' (%#x) (in token: %v): %v",
-		p.ptrn, p.pos, string(p.r), p.err,
+		p.ptrn, p.pos, string(p.r), p.r, p.inToken, p.err,
 	)
 
 	return

pdsh/dshgroup/types.go

@@ -0,0 +1,90 @@
+package dshgroup
+
+// TODO: This... doesn't really have much usefulness, does it?
+/*
+type (
+	HostLister interface {
+		// Hosts returns ALL hsots (where applicable) that are considered/generated for a Lister.
+		Hosts() (hosts []string, err error)
+	}
+)
+*/
+
+type (
+	/*
+		DshGroupLister behaves like the host list generator
+		for pdsh(1)'s "dshgroup module options" (the `misc/dshgroup`
+		module for pdsh).
+	*/
+	DshGroupLister struct {
+		/*
+			NoEnv, if true, will *not* use DSHGROUP_PATH (force-defaulting to /etc/dsh/group/,
+			but see NoDefault).
+		*/
+		NoEnv bool
+		/*
+			NoDefault, if true, will *not* add the default path `/etc/dsh/group/`
+			to the search paths.
+
+			If NoDefault is false, this path is only added if DSHGROUP_PATH is not defined
+			(or, if it IS defined, if NoEnv is true).
+		*/
+		NoDefault bool
+		// NoHome, if true, will *not* add the `~/.dsh/group/` path to the search paths.
+		NoHome bool
+		/*
+			ForceLegacy, if true, will disable the PDSH `#include <PATH|GROUP>` modification --
+			treating the source as a traditional DSH group file instead (e.g. `#include ...`
+			is treated as just a comment).
+		*/
+		ForceLegacy bool
+		// StrictWhitespace follows the same behavior as PDSH regarding no whitespace between patterns.
+		StrictWhitespace bool
+	}
+)
+
+type (
+	// DshGrpGenerator generates a list of hosts according to the pdsh "dshgroup" module.
+	DshGrpGenerator struct {
+		/*
+			tokens are interleaved with tokenized and indexed *after*;
+			in other words,	str = <substr0><token0><substr1><token1>...
+		*/
+		tokens []dshGrpToken
+		// tokenized holds the split original text with tokens removed and split where the tokens occur.
+		tokenized []string
+		// text holds the original pattern.
+		text string
+	}
+	dshGrpToken struct {
+		/*
+			token contains the original range specifier.
+			Tokens may be e.g.:
+
+				* 3: str3
+				* 3-5: str3, str4, str5
+				* 3,5: str3, str5
+		*/
+		token string
+		// subtokens hold a split of the individual range specifiers.
+		subtokens []dshGrpSubtoken
+	}
+	dshGrpSubtoken struct {
+		// start indicates either the single value or the start of the range.
+		start uint
+		// end, if 0 or less than start, indicates a single-value range.
+		end uint
+		// pad, if non-empty, is a string to add to the beginning of each of the generated substrings for this subtoken.
+		pad string
+	}
+)
+
+type (
+	PtrnParseErr struct {
+		pos     uint
+		ptrn    string
+		r       rune
+		err     error
+		inToken bool
+	}
+)

pdsh/genders/docs.go

@@ -0,0 +1,11 @@
+/*
+Package genders implements the [misc/genders] PDSH module. ([source])
+
+# TODO/WIP/Not Yet Implemented
+
+This package is not yet complete.
+
+[misc/genders]: https://www.mankier.com/1/pdsh#genders_module_options
+[source]: https://github.com/chaos/pdsh/blob/master/src/modules/genders.c
+*/
+package genders

pdsh/machines/docs.go

@@ -0,0 +1,11 @@
+/*
+Package machines implements the [misc/machines] PDSH module. ([source])
+
+# TODO/WIP/Not Yet Implemented
+
+This package is not yet complete.
+
+[misc/machines]: https://www.mankier.com/1/pdsh#machines_module_options
+[source]: https://github.com/chaos/pdsh/blob/master/src/modules/machines.c
+*/
+package machines

pdsh/netgroup/docs.go

@@ -0,0 +1,11 @@
+/*
+Package netgroup implements the [misc/netgroup] PDSH module. ([source])
+
+# TODO/WIP/Not Yet Implemented
+
+This package is not yet complete.
+
+[misc/netgroup]: https://www.mankier.com/1/pdsh#netgroup_module_options
+[source]: https://github.com/chaos/pdsh/blob/master/src/modules/netgroup.c
+*/
+package netgroup

pdsh/nodeupdown/docs.go

@@ -0,0 +1,11 @@
+/*
+Package nodeupdown implements the [misc/nodeupdown] PDSH module. ([source])
+
+# TODO/WIP/Not Yet Implemented
+
+This package is not yet complete.
+
+[misc/nodeupdown]: https://www.mankier.com/1/pdsh#nodeupdown_module_options
+[source]: https://github.com/chaos/pdsh/blob/master/src/modules/nodeupdown.c
+*/
+package nodeupdown

pdsh/slurm/docs.go

@@ -0,0 +1,11 @@
+/*
+Package slurm implements the [misc/slurm] PDSH module. ([source])
+
+# TODO/WIP/Not Yet Implemented
+
+This package is not yet complete.
+
+[misc/slurm]: https://www.mankier.com/1/pdsh#slurm_module_options
+[source]: https://github.com/chaos/pdsh/blob/master/src/modules/slurm.c
+*/
+package slurm

pdsh/torque/docs.go

@@ -0,0 +1,11 @@
+/*
+Package torque implements the [misc/torque] PDSH module. ([source])
+
+# TODO/WIP/Not Yet Implemented
+
+This package is not yet complete.
+
+[misc/torque]: https://www.mankier.com/1/pdsh#torque_module_options
+[source]: https://github.com/chaos/pdsh/blob/master/src/modules/torque.c
+*/
+package torque

pdsh/types.go

@@ -1,86 +1,60 @@
 package pdsh
 
-// TODO: This... doesn't really have much usefulness, does it?
-/*
-type (
-	HostLister interface {
-		// Hosts returns ALL hsots (where applicable) that are considered/generated for a Lister.
-		Hosts() (hosts []string, err error)
-	}
-)
-*/
-
 type (
 	/*
-		DshGroupLister behaves like the host list generator
+		Generator is one of the PDSH host generators/iterators offered by this module.
-		for pdsh(1)'s "dshgroup module options" (the `misc/dshgroup`
-		module for pdsh).
-	*/
-	DshGroupLister struct {
-		/*
-			NoEnv, if true, will *not* use DSHGROUP_PATH (force-defaulting to /etc/dsh/group/,
-			but see NoDefault).
-		*/
-		NoEnv bool
-		/*
-			NoDefault, if true, will *not* add the default path `/etc/dsh/group/`
-			to the search paths.
 
-			If NoDefault is false, this path is only added if DSHGROUP_PATH is not defined
+		Note that these generators/iterators are *stateful*, which means they shouldn't
-			(or, if it IS defined, if NoEnv is true).
+		(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.
 	*/
-		NoDefault bool
+	Generator interface {
-		// NoHome, if true, will *not* add the `~/.dsh/group/` path to the search paths.
-		NoHome bool
 		/*
-			ForceLegacy, if true, will disable the PDSH `#include <PATH|GROUP>` modification --
+			Generate provides a Go-native iterator (also called a "RangeFunc" or "range over function type")
-			treating the source as a traditional DSH group file instead (e.g. `#include ...`
+			as found in Go 1.23 onwards.
-			is treated as just a comment).
+
+			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.
 		*/
-		ForceLegacy bool
+		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.
-
+
-type (
+			Generators in this module are generally single-use, but can be reset/reused with this method.
-	dshGrpGenerator struct {
+		*/
-		/*
+		Reset()
-			tokens are interleaved with tokenized and indexed *after*;
+		/*
-			in other words,	str = <substr0><token0><substr1><token1>...
+			Hosts returns a complete generated hostlist at once if you'd rather not iterate.
-		*/
+
-		tokens []dshGrpToken
+			Hosts() *does* perform an iteration in runtime, so the recommendation against concurrency
-		// tokenized holds the split original text with tokens removed and split where the tokens occur.
+			stands, but it calls Reset() when done generating to allow other methods of a Generator to be used.
-		tokenized []string
+		*/
-		// text holds the original pattern.
+		Hosts() (hostList []string)
-		text string
+		/*
-	}
+			Next and Host behave like more "traditional" iterators, e.g. like (database/sql).Row.Next().
-	dshGrpToken struct {
+
-		/*
+			Next advances the internal state to the next host, and Host() returns it.
-			token contains the original range specifier.
+		*/
-			Tokens may be e.g.:
+		Next() (done bool)
-
+		/*
-				* 3: str3
+			Host returns the current host string (or "" if done).
-				* 3-5: str3, str4, str5
+
-				* 3,5: str3, str5
+			Be sure to e.g.:
-		*/
+
-		token string
+				for (Generator).Next() {
-		// subtokens hold a split of the individual range specifiers.
+					host := (Generator).Host()
-		subtokens []dshGrpSubtoken
+				}
-	}
+
-	dshGrpSubtoken struct {
+			otherwise the Host return value will not change.
-		// start indicates either the single value or the start of the range.
+		*/
-		start uint
+		Host() (host string)
-		// end, if 0 or less than start, indicates a single-value range.
-		end uint
-		// pad, if non-empty, is a string to add to the beginning of each of the generated substrings for this subtoken.
-		pad string
-	}
-)
-
-type (
-	PtrnParseErr struct {
-		pos  uint
-		ptrn string
-		r    rune
-		err  error
 	}
 )

pdsh/wcoll/docs.go

@@ -0,0 +1,14 @@
+/*
+Package wcoll implements the "default" [WCOLL] method for PDSH. ([source])
+
+Be sure to read the [HOSTLIST EXPRESSIONS] section in the MAN page.
+
+# TODO/WIP/Not Yet Implemented
+
+This package is not yet complete.
+
+[WCOLL]: https://www.mankier.com/1/pdsh#Environment_Variables
+[source]: https://github.com/chaos/pdsh/blob/master/src/pdsh/wcoll.c
+[HOSTLIST EXPRESSIONS]: https://www.mankier.com/1/pdsh#Hostlist_Expressions
+*/
+package wcoll