checking in some WIP

* added some netx funcs
* added netx/dnsx
* currently updating docs and adding *x funcs to sprigx

.githooks/pre-commit/01-docgen

@@ -15,23 +15,67 @@ for f in $(find . -type f -iname "README.adoc"); do
         nosuffix="${filename%.*}"
 	pfx="${docsdir}/${nosuffix}"
 
+	# Render HTML, include in commit
 	newf="${pfx}.html"
         asciidoctor -a ROOTDIR="${orig}/" -o "${newf}" "${f}"
 	echo "Generated ${newf} from ${f}"
         git add "${newf}"
+
+	# If asciidoctor-pdf is installed, render as PDF for local use
+	# (Does not get added to commit, and *.pdf is in .gitignore for a reason)
+        if command -v asciidoctor-pdf &> /dev/null;
+	then
+		newf="${pfx}.pdf"
+
+        	asciidoctor-pdf -a ROOTDIR="${orig}/" -o "${newf}" "${f}"
+	fi
+
+	# If pandoc is installed, render to "GitHub-flavored Markdown" for better rendering on forks/mirrors
+	# and marginally better rendering on https://pkg.go.dev/ and add to commit.
+	#
+	# <rant>
+	# There is no such thing as "Markdown".
+	# The closest thing you have to any sort of standard is https://daringfireball.net/projects/markdown/
+	# but everybody and their mother adds their own "extensions"/"flavor", and sometimes even
+	# change how formatting works compared to the Daring Fireball/John Gruber spec (the original creator of the "syntax").
+	# Ergo "Markdown" inherently has no meaning.
+	# It's one of the worst formatting languages out there - just because it's popular doesn't mean it's good.
+	#
+	# If you're writing docs, you should stick to one of these which have defined, canonical, standardized
+	# syntax:
+	# 	* AsciiDoc/AsciiDoctor
+	# 		* Supports much more extensive formatting than any Markdown flavor I've seen
+	# 		* Source/raw/unrendered still *quite* readable by human eyes
+	# 		* Somewhat limited parsers/renderers
+	# 		* https://asciidoc.org/
+	# 		* https://asciidoctor.org/
+	# 	* DocBook
+	# 		* Supports even more extensive and flexible but exact formatting
+	# 		* Great for publishing, though - especially if you need control over formatting/layout
+	# 		* XML-based
+	# 		* Harder to read in plaintext, but fairly doable (XML lends to decent mental rendering)
+	# 		* Very wide support for parsing/rendering
+	# 		* https://docbook.org/
+	#	* LaTex
+	#		* Allows for *very* extensive domain-specific ligature/representation (very common in mathematic/scientific literature)
+	#		* But nigh unreadable by human eyes unless you've rather familiar with it
+	#		* Parsing/rendering support about on-par with DocBook
+	#		* https://www.latex-project.org/
+	# </rant>
         if command -v pandoc &> /dev/null;
         then
 		newf="${pfx}.md"
 
 		set +e
-                asciidoctor -a ROOTDIR="${orig}/" -b docbook -o - "${f}" | pandoc -f docbook -t markdown_strict -o "${newf}"
+                #asciidoctor -a ROOTDIR="${orig}/" -b docbook -o - "${f}" | pandoc -f docbook -t markdown_strict -o "${newf}"
+                asciidoctor -a ROOTDIR="${orig}/" -b html -o - "${f}" | pandoc -f html -t gfm -o "${newf}"
 		if [ $? -eq 0 ];
 		then
 			echo "Generated ${newf} from ${f}"
 	                git add "${newf}"
 		else
 			echo "Failed to generate ${newf} from ${f}"
-			git rm "${newf}"
+			git rm "${newf}" 2>/dev/null
 		fi
 		set -e
         fi

.gitignore

@@ -19,12 +19,13 @@
 .idea/
 
 # https://github.com/github/gitignore/blob/master/Go.gitignore
-# Binaries for programs and plugins
+# Binaries for programs and plugins and other data
 *.exe
 *.exe~
 *.dll
 *.so
 *.dylib
+*.pdf
 
 # Test binary, built with `go test -c`
 *.test

TODO

@@ -0,0 +1 @@
+- validx: validator functions for https://pkg.go.dev/github.com/go-playground/validator/v10

chkplat.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+
+# go tool dist list for all valid GOOS/GOARCH targets.
+
+for tgt in $(go tool dist list);
+do
+	o="$(echo ${tgt} | cut -f1 -d '/')"
+	a="$(echo ${tgt} | cut -f2 -d '/')"
+	out="$(env GOOS=${o} GOARCH=${a} go build ./... 2>&1)"
+	ret=${?}
+	if [ $ret -ne 0 ];
+	then
+		echo "OS:   ${o}"
+		echo "ARCH: ${a}"
+		echo "${out}"
+		echo
+		echo
+	fi
+done

go.mod

@@ -10,7 +10,7 @@ require (
 	github.com/shirou/gopsutil/v4 v4.25.12
 	go4.org/netipx v0.0.0-20231129151722-fdeea329fbba
 	golang.org/x/sys v0.40.0
-	r00t2.io/sysutils v1.16.0
+	r00t2.io/sysutils v1.16.2
 )
 
 require (

go.sum

@@ -69,3 +69,4 @@ golang.org/x/sys v0.40.0 h1:DBZZqJ2Rkml6QMQsZywtnjnnGvHza6BTfYFWY9kjEWQ=
 golang.org/x/sys v0.40.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+r00t2.io/sysutils v1.16.2/go.mod h1:iXK+ALOwIdRKjAJIE5USlkZ669SVDHBNNuYhunsznH8=

logging/consts_nix.go

@@ -1,5 +1,4 @@
 //go:build !(windows || plan9 || wasip1 || js || ios)
-// +build !windows,!plan9,!wasip1,!js,!ios
 
 // I mean maybe it works for plan9 and ios, I don't know.
 

logging/consts_oldnix.go

@@ -1,3 +1,5 @@
+//go:build !(windows || plan9 || wasip1 || js || ios || linux)
+
 package logging
 
 var (

logging/funcs_oldnix.go

@@ -1,5 +1,4 @@
 //go:build !(windows || plan9 || wasip1 || js || ios || linux)
-// +build !windows,!plan9,!wasip1,!js,!ios,!linux
 
 // Linux is excluded because it has its own.
 

netx/dnsx/errors.go

@@ -0,0 +1,12 @@
+package dnsx
+
+import (
+	`errors`
+)
+
+var (
+	ErrBadChars    error = errors.New("netx/dnsx: invalid characters/encoding were encountered")
+	ErrBadLabelLen error = errors.New("netx/dnsx: a label with invalid length was encountered")
+	ErrBadPtrLen   error = errors.New("netx/dnsx: a PTR record with invalid length was encountered")
+	ErrBadPtrRoot  error = errors.New("netx/dnsx: a PTR record with invalid root encountered")
+)

netx/dnsx/funcs.go

@@ -0,0 +1,571 @@
+package dnsx
+
+import (
+	`bytes`
+	`encoding/base32`
+	`fmt`
+	`math`
+	`net`
+	`net/netip`
+	`strings`
+
+	`go4.org/netipx`
+	`r00t2.io/goutils/stringsx`
+)
+
+/*
+AddrFromPtr returns a [net/netip.Addr] from a PTR record.
+
+It is the inverse of [AddrToPtr].
+
+See also [IpFromPtr].
+*/
+func AddrFromPtr(s string) (ip netip.Addr, err error) {
+
+	var idx int
+	var ipStr string
+	var tmpStr string
+	var spl []string = strings.Split(strings.TrimSuffix(s, "."), ".")
+
+	switch len(spl) {
+	case 6:
+		if strings.Join(spl[4:], ".") != "in-addr.arpa" {
+			err = ErrBadPtrRoot
+			return
+		}
+		ipStr = fmt.Sprintf("%s.%s.%s.%s", spl[3], spl[2], spl[1], spl[0])
+	case 34:
+		if strings.Join(spl[32:], ".") != "ip6.arpa" {
+			err = ErrBadPtrRoot
+			return
+		}
+		tmpStr = stringsx.Reverse(strings.ReplaceAll(strings.Join(spl[:32], ""), ".", ""))
+		for idx = 0; idx < len(tmpStr); idx++ {
+			if idx%4 == 0 && idx != 0 {
+				ipStr += ":"
+			}
+			ipStr += string(rune(tmpStr[idx]))
+		}
+	default:
+		err = ErrBadPtrLen
+		return
+	}
+
+	if ip, err = netip.ParseAddr(ipStr); err != nil {
+		return
+	}
+
+	return
+}
+
+/*
+AddrToPtr returns a PTR record from ip.
+
+It is the inverse of [AddrFromPtr].
+
+It includes the root label at the end (the trailing period).
+*/
+func AddrToPtr(ip netip.Addr) (s string) {
+
+	var idx int
+	var b []byte
+	var ipStr string
+
+	if ip.Is6() {
+		ipStr = stringsx.Reverse(strings.ReplaceAll(ip.StringExpanded(), ":", ""))
+		ipStr = strings.Join(
+			strings.Split(ipStr, ""),
+			".",
+		)
+		s = fmt.Sprintf("%s.ip6.arpa.", ipStr)
+	} else {
+		b = make([]byte, 4)
+		copy(b, ip.AsSlice())
+		for idx = len(b) - 1; idx >= 0; idx-- {
+			ipStr += fmt.Sprintf("%d.", b[idx])
+		}
+		s = fmt.Sprintf("%s.in-addr.arpa.", ipStr)
+	}
+
+	return
+}
+
+/*
+DnsStrToWire returns a wire-format of a DNS name.
+
+No validation or conversion (other than to wire format) is performed,
+and it is expected that any IDN(A)/Punycode translation has
+*already been performed* such that recordNm is in the ASCII form.
+(See [IsFqdn] for more information on IDN(A)/Punycode.)
+
+For encoding reasons, if any given label/segment has a length of 0 or greater than 255 ([math.MaxUint8]),
+[ErrBadLabelLen] will be returned.
+
+See [DnsWireToStr] for the inverse.
+*/
+func DnsStrToWire(recordNm string) (recordNmBytes []byte, err error) {
+
+	var cLen int
+	var c []byte
+	var cStr string
+	var spl []string
+	var buf *bytes.Buffer = new(bytes.Buffer)
+
+	spl = strings.Split(strings.TrimSuffix(recordNm, "."), ".")
+	for _, cStr = range spl {
+		c = []byte(cStr)
+		cLen = len(c)
+		if !(cLen > 0 && cLen <= math.MaxUint8) {
+			err = ErrBadLabelLen
+			return
+		}
+		buf.Write(append([]byte{uint8(cLen)}, c...))
+	}
+
+	recordNmBytes = append(buf.Bytes(), 0x00)
+
+	return
+}
+
+/*
+DnsWireToStr is the inverse of [DnsStrToWire]. A trailing . is not included.
+
+For decoding reasons, it will exit with [ErrBadLabelLen] if recordNmBytes is nil/empty or
+if no terminating nullbyte is found after 256 label characters have been encountered.
+*/
+func DnsWireToStr(recordNmBytes []byte) (recordNm string, err error) {
+
+	var c []byte
+	var cLen uint8
+	var arrLen int
+	var numChars int
+	var labels []string
+	var buf *bytes.Buffer
+
+	if recordNmBytes == nil || len(recordNmBytes) == 0 {
+		err = ErrBadLabelLen
+		return
+	}
+	buf = bytes.NewBuffer(recordNmBytes)
+	labels = make([]string, 0)
+
+	arrLen = len(recordNmBytes)
+	for {
+		if cLen, err = buf.ReadByte(); err != nil {
+			return
+		}
+		if cLen == 0x00 {
+			break
+		}
+		numChars += int(cLen)
+		if numChars > 255 {
+			err = ErrBadLabelLen
+			return
+		}
+		if numChars > arrLen {
+			err = ErrBadLabelLen
+			return
+		}
+		c = buf.Next(int(cLen))
+		labels = append(labels, string(c))
+	}
+
+	recordNm = strings.Join(labels, ".")
+
+	return
+}
+
+/*
+IpFromPtr is like [AddrFromPtr] but with a [net.IP] instead.
+
+It is the inverse of [IpToPtr].
+*/
+func IpFromPtr(s string) (ip net.IP, err error) {
+
+	var a netip.Addr
+
+	if a, err = AddrFromPtr(s); err != nil {
+		return
+	}
+	ip = net.IP(a.AsSlice())
+
+	return
+}
+
+/*
+IpToPtr is like [AddrToPtr] but with a [net.IP] instead.
+
+It is the inverse of [IpFromPtr].
+*/
+func IpToPtr(ip net.IP) (s string) {
+
+	var a netip.Addr
+
+	a, _ = netipx.FromStdIP(ip)
+	s = AddrToPtr(a)
+
+	return
+}
+
+/*
+IsFqdn returns a boolean indicating if s is an FQDN that strictly adheres to RFC format requirements.
+It performs no lookups/resolution attempts or network operations otherwise.
+
+It will return true for the "apex record" (e.g. the "naked domain"), as this is a valid assignable FQDN.
+
+It will return false for wildcard records (see [IsFqdnWildcard]).
+
+s may or may not end in a period (the root zone; "absolute" FQDNs) (0x00 in wire format).
+
+# TLDs
+
+Because valid TLDs are fairly dynamic and can change frequently,
+validation is *not* performed against the TLD itself.
+This only ensures that s has a TLD label conforming to the character rules in the referenced RFCs.
+See [golang.org/x/net/publicsuffix] if precise TLD validation is required (though true TLD validation generally
+requires fetching the current TLD lists from IANA at runtime like [github.com/bombsimon/tld-validator]).
+
+# Special RFC-Defined Accommodations
+
+RFC 2181 [§ 11] specifies that site-local DNS software may accommodate non-RFC-conforming rules.
+This function may and likely will return false for these site-local deviations.
+The Lookup* functions/mthods in [net] should be used to validate in these casts
+if that accommodation is necessary.
+
+Note that underscores are not valid for "true" FQDNs as they are only valid for e.g. SRV record names,
+TXT records, etc. - not A/AAAA/CNAME, etc. - see RFC 8553 for details.
+
+See the following functions for allowing additional syntax/rule validation
+that have record-type-specific accommodations made:
+
+	* [IsFqdnDefinedTxt]
+	* [IsFqdnNsec3]
+	* [IsFqdnSrv]
+	* [IsFqdnWildcard]
+
+# RFC Coverage
+
+This function should conform properly to:
+
+	* RFC 952
+	* RFC 1034 and RFC 1035
+	* RFC 1123
+	* RFC 2181 (selectively, see above)
+
+preferring the most up-to-date rules where relevant (e.g. labels may start with digits, as per RFC 1123).
+It enforces/checks label and overall length limits as defined by RFC.
+
+# IDN(A) and Punycode
+
+Note that it expects the ASCII-only/presentation form of a record name and
+will not perform any IDN/IDNA nor Punycode translation.
+If a caller anticipates FQDNs in their localized format,
+the caller must perform translation first
+(via e.g. [gitlab.com/golang-commonmark/puny], [golang.org/x/net/idna], etc.).
+
+To reiterate, IDN/IDNA:
+
+	* RFC 3490
+	* RFC 5890
+	* RFC 5891
+	* RFC 5892
+	* RFC 5893
+	* RFC 5894
+
+and Punycode (RFC 3492) *MUST* use their ASCII forms, NOT the localized/Unicode formats.
+
+[§ 11]: https://datatracker.ietf.org/doc/html/rfc2181#section-11
+*/
+func IsFqdn(s string) (fqdn bool) {
+
+	var lbl string
+	var lbls []string = strings.Split(strings.TrimSuffix(s, "."), ".")
+
+	if !commonFqdn(s) {
+		return
+	}
+	for _, lbl = range lbls {
+		if !IsLabel(lbl) {
+			return
+		}
+	}
+
+	fqdn = true
+
+	return
+}
+
+/*
+IsFqdnDefinedTxt is like [IsFqdn] but explicitly *only* allows fully-qualified
+RFC-defined TXT "subtypes":
+
+	* ACME DNS-01 (RFC 8555)
+	* BIMI (RFC draft [bimi])
+	* DKIM (RFC 6376,  RFC 8301, RFC 8463)
+	* DKIM ATPS (RFC 6541)
+	* DMARC (RFC 7489, RFC 9091, RFC 9616)
+	* MTA-STS (RFC 8461)
+	* TLSRPT (RFC 8460)
+
+Note that the following TXT "subtypes" do not have special formatting in labels/name,
+and thus are not covered by this function:
+
+	* SPF (RFC 4408, RFC 7208)
+
+[bimi]: https://datatracker.ietf.org/doc/html/draft-brand-indicators-for-message-identification
+*/
+func IsFqdnDefinedTxt(fqdn string) (isOk bool) {
+
+	var lbls []string = strings.Split(fqdn, ".")
+
+	if lbls == nil || len(lbls) < 2 {
+		return
+	}
+
+	switch lbls[0] {
+	case "_dmarc", "_mta-sts", "_acme-challenge":
+		if len(lbls) < 2 {
+			return
+		}
+		isOk = IsFqdn(strings.Join(lbls[1:], "."))
+	case "_smtp":
+		if len(lbls) <= 2 {
+			return
+		}
+		if lbls[1] != "_tls" {
+			return
+		}
+		isOk = IsFqdn(strings.Join(lbls[2:], "."))
+	default:
+		if !IsLabel(lbls[0]) {
+			return
+		}
+		switch lbls[1] {
+		case "_domainkey", "_atps", "_bimi":
+			isOk = IsFqdn(strings.Join(lbls[2:], "."))
+		}
+	}
+
+	// TODO
+
+	return
+}
+
+/*
+IsFqdnNsec3 confirms (partially) that s is a valid NSEC3 record name.
+
+Note that due to the record name being a base32 encoding of a *hash*, the validity
+can't be 100% confirmed with certainty - only basic checks can be done.
+
+NSEC3 can be found via:
+
+	* RFC 5155
+	* RFC 6840
+	* RFC 6944
+	* RFC 7129
+	* RFC 8198
+	* RFC 9077
+	* RFC 9157
+	* RFC 9276
+	* RFC 9905
+
+At the time of writing, only one hashing algorithm (SHA-1) has been specified.
+However, because this function does not check against the IANA registration at runtime,
+it's possible that this changes but the library may not immediately reflect this.
+*/
+func IsFqdnNsec3(s string) (maybeNsec3 bool) {
+
+	var h []byte
+	var err error
+	var isAscii bool
+	var lbls []string = strings.Split(strings.TrimSuffix(s, "."), ".")
+
+	if !commonFqdn(s) {
+		return
+	}
+	if len(lbls) <= 2 {
+		return
+	}
+	if len(lbls[0]) != 32 { // SHA1 is 160 bits/20 bytes digest, which is always 32 chars in base32(hex)
+		return
+	}
+	if h, err = base32.StdEncoding.DecodeString(strings.ToUpper(lbls[0])); err != nil {
+		return
+	}
+	if isAscii, err = stringsx.IsAsciiSpecial(
+		strings.ToLower(lbls[0]),
+		false, false, false, false,
+		[]byte{
+			// Normally, Base32 goes A-Z, 2-7
+			// but NSEC3 uses Base32Hex (RFC 4648 § 7),
+			// which is 0-9A-V
+			'0', '1', '2', '3', '4', '5',
+			'6', '7', '8', '9', 'a', 'b',
+			'c', 'd', 'e', 'f', 'g', 'h',
+			'j', 'k', 'm', 'n', 'p', 'q',
+			'r', 's', 't', 'u', 'v',
+		},
+		nil,
+	); err != nil {
+		return
+	}
+	if isAscii {
+		return
+	}
+	if len(h) != 20 {
+		return
+	}
+	maybeNsec3 = IsFqdn(strings.Join(lbls[1:], "."))
+
+	return
+}
+
+/*
+IsFqdnSrv is like [IsFqdn], but explicitly *only* allows fully-qualified SRV records
+(i.e. underscores must start the first two labels, and there must be at least two additional
+labels after these labels).
+
+Note that the protocol is not checked for validity, as that would require runtime
+validation against a resource liable to change and would need to be fetched dynamically - see
+the [IANA Protocol Numbers registry].
+
+[IANA Protocol Numbers registry]: https://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml
+*/
+func IsFqdnSrv(s string) (srv bool) {
+
+	var lbls []string = strings.Split(strings.TrimSuffix(s, "."), ".")
+
+	if !commonFqdn(s) {
+		return
+	}
+	if len(lbls) <= 4 {
+		return
+	}
+
+	if !strings.HasPrefix(lbls[0], "_") {
+		return
+	}
+	if !strings.HasPrefix(lbls[1], "_") {
+		return
+	}
+	srv = IsFqdn(strings.Join(lbls[2:], "."))
+
+	return
+}
+
+// IsFqdnWildcard is like [IsFqdn] but explicitly *only* allows fully-qualified wildcard records.
+func IsFqdnWildcard(s string) (wildcard bool) {
+
+	var lbls []string = strings.Split(strings.TrimSuffix(s, "."), ".")
+
+	if len(lbls) < 2 {
+		return
+	}
+
+	if lbls[0] != "*" {
+		return
+	}
+	wildcard = IsFqdn(strings.Join(lbls[1:], "."))
+
+	return
+}
+
+// IsLabel returns true if s is a valid DNS label for standard records.
+func IsLabel(s string) (isLbl bool) {
+
+	var err error
+
+	if strings.HasPrefix(s, "-") {
+		return
+	}
+	if strings.HasSuffix(s, "-") {
+		return
+	}
+	if isLbl, err = stringsx.IsAsciiSpecial(
+		s,
+		false, false, false, false,
+		[]byte{
+			'a', 'b', 'c', 'd', 'e', 'f',
+			'g', 'h', 'i', 'j', 'k', 'l',
+			'm', 'n', 'o', 'p', 'q', 'r',
+			's', 't', 'u', 'v', 'w', 'x',
+			'y', 'z', '0', '1', '2', '3',
+			'4', '5', '6', '7', '8', '9',
+			'-',
+		},
+		nil,
+	); err != nil {
+		return
+	}
+
+	return
+}
+
+/*
+IsPtr returns true if s is a PTR (also called an "rDNS" or "reverse DNS" record) name.
+
+If true, the IP is returned as well (otherwise it will be nil).
+*/
+func IsPtr(s string) (isPtr bool, addr net.IP) {
+
+	var err error
+	var lbls []string = strings.Split(strings.TrimSuffix(s, "."), ".")
+
+	if len(lbls) < 6 {
+		return
+	}
+
+	if _, err = AddrFromPtr(s); err != nil {
+		return
+	}
+
+	isPtr = true
+
+	return
+}
+
+// commonFqdn is used to validate some rules common to all record names.
+func commonFqdn(s string) (isOk bool) {
+
+	var err error
+	var lbl string
+	var isAscii bool
+	var labels []string
+	var domstr string = strings.ToLower(strings.TrimSuffix(s, "."))
+
+	if isAscii, err = stringsx.IsAsciiSpecial(
+		domstr, false, false, false, false,
+		[]byte{
+			'a', 'b', 'c', 'd', 'e', 'f',
+			'g', 'h', 'i', 'j', 'k', 'l',
+			'm', 'n', 'o', 'p', 'q', 'r',
+			's', 't', 'u', 'v', 'w', 'x',
+			'y', 'z', '0', '1', '2', '3',
+			'4', '5', '6', '7', '8', '9',
+			'-', '_', '.',
+		},
+		nil,
+	); err != nil {
+		return
+	}
+	if !isAscii {
+		return
+	}
+
+	if (len(domstr) + 1) > 255 { // +1 for root label
+		return
+	}
+	labels = strings.Split(domstr, ".")
+
+	for _, lbl = range labels {
+		if len(lbl) < 1 || len(lbl) > 63 {
+			return
+		}
+	}
+
+	// TODO?
+
+	isOk = true
+
+	return
+}

netx/dnsx/funcs_test.go

@@ -0,0 +1,29 @@
+package dnsx
+
+import (
+	`net/netip`
+	"testing"
+)
+
+func TestPtr(t *testing.T) {
+
+	var err error
+	var ptr string
+	var ip netip.Addr
+	var ipStr string = "::ffff:192.168.0.1"
+	var ptrStr string = "1.0.0.0.8.a.0.c.f.f.f.f.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa."
+
+	if ip, err = AddrFromPtr(ptrStr); err != nil {
+		t.Fatal(err)
+	}
+	t.Logf("PTR -> Addr: %s -> %s", ptrStr, ip.String())
+	if ip.String() != ipStr {
+		t.Fatalf("expect IP %v, got %v", ipStr, ip.String())
+	}
+
+	ptr = AddrToPtr(ip)
+	if ptr != ptrStr {
+		t.Fatalf("expect PTR %v, got %v", ptrStr, ptr)
+	}
+	t.Logf("Addr -> PTR: %s -> %s", ip.String(), ptr)
+}

netx/funcs.go

@@ -102,11 +102,37 @@ func Cidr4ToStr(cidr uint8) (maskStr string, err error) {
 	return
 }
 
+/*
+FamilyToVer returns a more "human-friendly" IP version from a system/lower-level IP family
+([AFUnspec], [AFInet], [AFInet6]).
+
+ipVer will be int(4) for [AFInet], int(6) for [AFInet6], int(0) for [AFUnspec], or
+int(-1) for an unknown family.
+*/
+func FamilyToVer(family uint16) (ipVer int) {
+
+	switch family {
+	case AFInet:
+		ipVer = 4
+	case AFInet6:
+		ipVer = 6
+	case AFUnspec:
+		ipVer = 0
+	default:
+		ipVer = -1
+	}
+
+	return
+}
+
 /*
 GetAddrFamily returns the network family of a [net/netip.Addr].
 
 See also [GetIpFamily].
 
+Note that this returns [AFInet] or [AFInet6], NOT uint16(4) or uint16(6).
+(See [FamilyToVer] to get the associated higher-level value.)
+
 If addr is not a "valid" IP address or the version can't be determined, family will be AFUnspec (usually 0x00/0).
 */
 func GetAddrFamily(addr netip.Addr) (family uint16) {
@@ -131,6 +157,9 @@ func GetAddrFamily(addr netip.Addr) (family uint16) {
 /*
 GetIpFamily returns the network family of a [net.IP].
 
+Note that this returns [AFInet] or [AFInet6], NOT uint16(4) or uint16(6).
+(See [FamilyToVer] to get the associated higher-level value.)
+
 See also [GetAddrFamily].
 
 If ip is not a "valid" IP address or the version can't be determined,
@@ -158,6 +187,8 @@ If ip is an IPv4 address, it will simmply be the string representation (e.g. "20
 If ip is an IPv6 address, it will be enclosed in brackets (e.g. "[2001:db8::1]").
 
 If the version can't be determined, rfcStr will be an empty string.
+
+See also [IpRfcStr] for providing an IP address as a string.
 */
 func IpRfc(ip net.IP) (rfcStr string) {
 
@@ -170,6 +201,56 @@ func IpRfc(ip net.IP) (rfcStr string) {
 	return
 }
 
+/*
+IpRfcStr implements [IpRfc]/[AddrRfc] for string representations of an IP address s.
+
+If s is an IPv6 address already in the bracketed RFC format,
+then rfcStr will be equal to s.
+
+If s is not a string representation of an IP address, rfcStr will be empty.
+
+See [IpStripRfcStr] for the inverse (removing any brackets from s if present).
+*/
+func IpRfcStr(s string) (rfcStr string) {
+
+	var ip net.IP
+
+	if !IsIpAddr(s) {
+		return
+	}
+	if IsBracketedIp6(s) {
+		rfcStr = s
+		return
+	}
+	ip = net.ParseIP(s)
+	if ip == nil {
+		return
+	}
+	rfcStr = IpRfc(ip)
+
+	return
+}
+
+/*
+IpStripRfcStr returns IP address string s without any brackets.
+
+If s is not a valid IP address, stripStr will be empty.
+*/
+func IpStripRfcStr(s string) (stripStr string) {
+
+	if !IsIpAddr(s) {
+		return
+	}
+	if !IsBracketedIp6(s) {
+		stripStr = s
+		return
+	}
+	stripStr = strings.TrimPrefix(s, "[")
+	stripStr = strings.TrimSuffix(stripStr, "]")
+
+	return
+}
+
 /*
 IPMask4ToCidr returns a CIDR prefix size/bit size/bit length from a [net.IPMask].
 
@@ -257,6 +338,123 @@ func IPMask4ToStr(ipMask net.IPMask) (maskStr string, err error) {
 	return
 }
 
+/*
+IpVerStr provides the IP family of IP address/network string s.
+
+s may be one of the following formats/syntaxes:
+
+	* 203.0.113.0
+	* 203.0.113.1
+	* 203.0.113.0/24
+	* 203.0.113.1/24
+	* 2001:db8::
+	* 2001:db8::1
+	* 2001:db8::/32
+	* 2001:db8::1/32
+	* [2001:db8::]
+	* [2001:db8::1]
+
+
+Unlike [GetAddrFamily]/[GetIpFamily], this returns a more "friendly"
+version - if s is not valid syntax, ipVer will be int(0),
+otherwise ipVer will be int(4) for family IPv4 and int(6) for family IPv6.
+(See [VerToFamily] to get the associated system/lower-level value.)
+*/
+func IpVerStr(s string) (ipVer int) {
+
+	var err error
+	var ipstr string
+	var p netip.Prefix
+
+	ipstr = strings.TrimPrefix(s, "[")
+	ipstr = strings.TrimSuffix(ipstr, "]")
+
+	if p, err = netip.ParsePrefix(ipstr); err != nil {
+		return
+	}
+	if p.Addr().Is6() {
+		ipVer = 6
+	} else {
+		ipVer = 4
+	}
+
+	return
+}
+
+/*
+IsBracketedIp6 returns a boolean indicating if s is a valid bracket-enclosed IPv6 in string format
+(e.g. "[2001:db8::1]").
+
+It will return false for *non-bracketed* IPv6 addresses (e.g. "2001:db8::1"), IPv4 addresses,
+or if s is not a valid IPv6 address string.
+
+[IpRfcStr] or [IpStripRfcStr] can be used to coerce a string to a specific format.
+*/
+func IsBracketedIp6(s string) (isBrktdIp bool) {
+
+	var ip net.IP
+	var ipstr string
+
+	if IpVerStr(s) != 6 {
+		return
+	}
+
+	ipstr = strings.TrimPrefix(s, "[")
+	ipstr = strings.TrimSuffix(ipstr, "]")
+
+	if ip = net.ParseIP(ipstr); ip == nil {
+		return
+	}
+
+	isBrktdIp = ipstr == s
+
+	return
+}
+
+/*
+IsIpAddr returns a boolean indicating if s is an IP address (either IPv4 or IPv6) in string format.
+
+For IPv6, it will return true for both of these formats:
+
+	* 2001:db8::1
+	* [2001:db8::1]
+
+[IsBracketedIp6] can be used to narrow down which form.
+*/
+func IsIpAddr(s string) (isIp bool) {
+
+	var err error
+	var a netip.Addr
+
+	if a, err = netip.ParseAddr(s); err != nil {
+		return
+	}
+
+	isIp = a.IsValid()
+
+	return
+}
+
+/*
+IsPrefixNet returns true if s is a (valid) IP address or network (either IPv4 or IPv6) in:
+
+	<addr_or_net>/<prefix_len>
+
+format.
+*/
+func IsPrefixNet(s string) (isNet bool) {
+
+	var err error
+	var p netip.Prefix
+
+	if p, err = netip.ParsePrefix(s); err != nil {
+		return
+	}
+	isNet = p.Masked().IsValid()
+
+	return
+}
+
 /*
 Mask4ToCidr converts an IPv4 netmask *in bitmask form* to a CIDR prefix size/bit size/bit length.
 
@@ -408,3 +606,25 @@ func Mask4StrToMask(maskStr string) (mask uint32, err error) {
 
 	return
 }
+
+/*
+VerToFamily takes a "human-readable" IP version ipVer (4 or 6) and returns
+a system-level constant (e.g. [AFUnspec], [AFInet], [AFInet6]).
+
+If not a known IP version (i.e. neither 4 nor 6), family will be [AFUnspec].
+
+It is the inverse of [FamilyToVer].
+*/
+func VerToFamily(ipVer int) (family uint16) {
+
+	switch ipVer {
+	case 4:
+		family = AFInet
+	case 6:
+		family = AFInet6
+	default:
+		family = AFUnspec
+	}
+
+	return
+}

netx/funcs_test.go

@@ -7,6 +7,29 @@ import (
 	"testing"
 )
 
+func TestFuncsDns(t *testing.T) {
+
+	var err error
+	var domBin []byte
+	var domStr string
+	var domEx string = "foo.r00t2.io"
+
+	if domBin, err = DnsStrToWire(domEx); err != nil {
+		t.Fatal(err)
+	}
+	t.Logf("Domain %s to wire: %#x\n", domEx, domBin)
+	if domStr, err = DnsWireToStr(domBin); err != nil {
+		t.Fatal(err)
+	}
+	t.Logf("Domain wire %#x to string: %s\n", domBin, domStr)
+	if domStr != domEx {
+		t.Fatalf("DNS str wrong (%s != %s)\n)", domStr, domEx)
+	}
+	t.Logf("Domain string %s matches %s", domStr, domEx)
+
+	return
+}
+
 func TestFuncsIP(t *testing.T) {
 
 	var err error

stringsx/func_asciiinvaliderror.go

@@ -0,0 +1,18 @@
+package stringsx
+
+import (
+	`fmt`
+)
+
+// Error conforms an [AsciiInvalidError] to an error interface.
+func (a *AsciiInvalidError) Error() (errStr string) {
+
+	errStr = fmt.Sprintf(
+		"non-ASCII character '%c' at line:linepos %d:%d (byte %d), "+
+			"string position %d (byte %d): bytes %#x, UTF-8 codepoint U+%04X",
+		a.BadChar, a.Line, a.LineChar, a.LineByte,
+		a.Char, a.Byte, a.BadBytes, a.BadChar,
+	)
+
+	return
+}

stringsx/funcs.go

@@ -1,11 +1,165 @@
 package stringsx
 
 import (
+	`bytes`
+	`errors`
 	`fmt`
+	`io`
+	`slices`
 	`strings`
 	`unicode`
 )
 
+/*
+IsAscii returns true if all characters in string s are ASCII.
+
+This simply wraps [IsAsciiSpecial]:
+
+	isAscii, err = IsAsciiSpecial(s, allowCtl, true, allowExt, true, nil, nil)
+*/
+func IsAscii(s string, allowCtl, allowExt bool) (isAscii bool, err error) {
+
+	if isAscii, err = IsAsciiSpecial(
+		s, allowCtl, true, allowExt, true, nil, nil,
+	); err != nil {
+		return
+	}
+
+	return
+}
+
+/*
+IsAsciiBuf returns true if all of buffer buf is valid ASCII.
+
+Note that the buffer will be consumed/read by this function.
+
+This simply wraps [IsAsciiBufSpecial]:
+
+	isAscii, err = IsAsciiBufSpecial(r, allowCtl, true, allowExt, true, nil, nil)
+*/
+func IsAsciiBuf(r io.RuneReader, allowCtl, allowExt bool) (isAscii bool, err error) {
+
+	if isAscii, err = IsAsciiBufSpecial(
+		r, allowCtl, true, allowExt, true, nil, nil,
+	); err != nil {
+		return
+	}
+
+	return
+}
+
+/*
+IsAsciiSpecial allows for specifying specific ASCII ranges.
+
+allowCtl, if true, will allow control characters (0x00 to 0x1f inclusive).
+
+allowPrint, if true, will allow printable characters (what most people think of
+when they say "ASCII") (0x20 to 0x7f inclusive).
+
+allowExt, if true, will allow for "extended ASCII" - some later dialects expand
+to a full 8-bit ASCII range (0x80 to 0xff inclusive).
+
+wsCtl, if true, "shifts" the "whitespace control characters" (\t, \n, \r) to the "printable" space
+(such that allowPrint controls their validation). Thus:
+
+	IsAsciiSpecial(s, false, true, false, true, nil, nil)
+
+has the same effect as specifying:
+
+	IsAsciiSpecial(s, false, true, false, (-), []byte("\t\n\r"), nil)
+
+incl, if non-nil and non-empty, allows *additional* characters to be specified as included
+that would normally *not* be allowed.
+
+excl, if non-nil and non-empty, invalidates on additional characters that would normally be allowed.
+
+excl, if specified, takes precedence over incl if specified.
+
+An [AsciiInvalidError] will be returned on the first encountered invalid character.
+*/
+func IsAsciiSpecial(s string, allowCtl, allowPrint, allowExt, allowWs bool, incl, excl []byte) (isAscii bool, err error) {
+
+	var buf *bytes.Buffer = bytes.NewBufferString(s)
+
+	if isAscii, err = IsAsciiBufSpecial(buf, allowCtl, allowPrint, allowExt, allowWs, incl, excl); err != nil {
+		return
+	}
+
+	return
+}
+
+/*
+IsAsciiBufSpecial is the same as [IsAsciiSpecial] but operates on an [io.RuneReader].
+
+Note that the buffer will be consumed/read by this function.
+
+It will not return an [io.EOF] if encountered, but any other errors encountered will be returned.
+It is expected that r will return an [io.EOF] when exhausted.
+
+An [AsciiInvalidError] will be returned on the first encountered invalid character.
+*/
+func IsAsciiBufSpecial(r io.RuneReader, allowCtl, allowPrint, allowExt, allowWs bool, incl, excl []byte) (isAscii bool, err error) {
+
+	var b rune
+	var bLen int
+	var nextNewline bool
+	var tmpErr *AsciiInvalidError = new(AsciiInvalidError)
+	// I know, I know. This is essentually a lookup table. Keeps it speedy.
+	var allowed [256]bool = getAsciiCharMap(allowCtl, allowPrint, allowExt, allowWs, incl, excl)
+
+	for {
+		if b, bLen, err = r.ReadRune(); err != nil {
+			if errors.Is(err, io.EOF) {
+				err = nil
+				isAscii = true
+			}
+			return
+		}
+		// Set these *before* OK
+		if nextNewline {
+			tmpErr.Line++
+			tmpErr.LineByte = 0
+			tmpErr.LineChar = 0
+			nextNewline = false
+		} else {
+			tmpErr.LineChar++
+		}
+		tmpErr.Char++
+
+		if b == '\n' {
+			nextNewline = true
+		}
+		if b == rune(0xfffd) {
+			// not even valid unicode
+			tmpErr.BadChar = b
+			tmpErr.BadBytes = []byte(string(b))
+			err = tmpErr
+			return
+		}
+		if bLen > 2 || b > 0xff {
+			// ASCII only occupies a single byte, ISO-8859-1 occupies 2
+			tmpErr.BadChar = b
+			tmpErr.BadBytes = []byte(string(b))
+			err = tmpErr
+			return
+		}
+		if !allowed[byte(b)] {
+			tmpErr.BadChar = b
+			tmpErr.BadBytes = []byte{byte(b)}
+			err = tmpErr
+			return
+		}
+
+		// Set these *after* OK
+		tmpErr.LineByte += uint64(bLen)
+		tmpErr.Byte += uint64(bLen)
+	}
+
+	isAscii = true
+
+	return
+}
+
 /*
 LenSplit formats string `s` to break at, at most, every `width` characters.
 
@@ -252,6 +406,18 @@ func Redact(s, maskStr string, leading, trailing uint, newlines bool) (redacted
 	return
 }
 
+// Reverse reverses string s. (It's absolutely insane that this isn't in stdlib.)
+func Reverse(s string) (revS string) {
+
+	var rsl []rune = []rune(s)
+
+	slices.Reverse(rsl)
+
+	revS = string(rsl)
+
+	return
+}
+
 /*
 TrimLines is like [strings.TrimSpace] but operates on *each line* of s.
 It is *NIX-newline (`\n`) vs. Windows-newline (`\r\n`) agnostic.
@@ -313,6 +479,58 @@ func TrimSpaceRight(s string) (trimmed string) {
 	return
 }
 
+// getAsciiCharMap returns a lookup "table" for ASCII characters.
+func getAsciiCharMap(allowCtl, allowPrint, allowExt, allowWs bool, incl, excl []byte) (charmap [256]bool) {
+
+	var idx uint8
+
+	if allowCtl {
+		for idx < 0x1f {
+			charmap[idx] = true
+			idx++
+		}
+	} else {
+		idx = 0x1f
+	}
+	if allowPrint {
+		for idx < 0x7f {
+			charmap[idx] = true
+			idx++
+		}
+	} else {
+		idx = 0x7f
+	}
+	if allowExt {
+		for {
+			charmap[idx] = true
+			if idx == 0xff {
+				break
+			}
+			idx++
+		}
+	} else {
+		idx = 0xff
+	}
+	if allowWs {
+		charmap['\t'] = true
+		charmap['\n'] = true
+		charmap['\r'] = true
+	}
+
+	if incl != nil && len(incl) > 0 {
+		for _, idx = range incl {
+			charmap[idx] = true
+		}
+	}
+	if excl != nil && len(excl) > 0 {
+		for _, idx = range excl {
+			charmap[idx] = false
+		}
+	}
+
+	return
+}
+
 // getNewLine is too unpredictable/nuanced to be used as part of a public API promise so it isn't exported.
 func getNewLine(s string) (nl string) {
 

stringsx/funcs_test.go

@@ -37,6 +37,17 @@ type (
 	}
 )
 
+func TestFuncsAscii(t *testing.T) {
+
+	var err error
+	// var s string = "This is a §\nmulti-line\nstring 😀 with\nunicode text.\n"
+	var s string = "This is a §\nmulti-line\nstring with\nno unicode text.\n"
+
+	if _, err = IsAscii(s, false, true); err != nil {
+		t.Fatal(err)
+	}
+}
+
 func TestRedact(t *testing.T) {
 
 	var out string
@@ -171,6 +182,18 @@ func TestRedact(t *testing.T) {
 	}
 }
 
+func TestReverse(t *testing.T) {
+
+	var rev string
+	var s string = "012345679abcdef"
+
+	rev = Reverse(s)
+	if rev != "fedcba976543210" {
+		t.Errorf("reverse of s '%s'; expected 'fedcba976543210', got '%s'", s, rev)
+	}
+	t.Logf("s: %s\nReverse: %s", s, rev)
+}
+
 func TestTrimLines(t *testing.T) {
 
 	var out string

stringsx/types.go

@@ -0,0 +1,25 @@
+package stringsx
+
+type (
+	/*
+		AsciiInvalidError is an error used to return an error for the IsAscii* validations.
+
+		It is returned on the first found instance of an invalid ASCII character.
+	*/
+	AsciiInvalidError struct {
+		// Line is a 0-indexed line number where the invalid character was found.
+		Line uint64
+		// LineByte is the 0-indexed byte position for the current Line.
+		LineByte uint64
+		// LineChar is a 0-indexed character (rune) position where the invalid character was found on line number Line.
+		LineChar uint64
+		// Byte is the 0-indexed byte position across the entire input.
+		Byte uint64
+		// Char is the 0-indexed character (rune) position across the entire input.
+		Char uint64
+		// BadChar is the invalid rune
+		BadChar rune
+		// BadBytes is BadChar as bytes.
+		BadBytes []byte
+	}
+)

tplx/sprigx/TODO

@@ -0,0 +1,14 @@
+- osReadFileBytes
+- osReadFileStr
+- osReadDir
+
+- `dns*` funcs (net)
+- `url*` funcs (net/url)
+- `uuid*` funcs (github.com/google/uuid and r00t2.io/goutils/uuidx)
+
+- `http*` funcs:
+-- `httpReq`: returns a net/http.Request
+-- `http<Method>`: performs <Method> (? seems redundant if exposing httpReq)
+-- also have `resty*` funcs?
+
+- i should probably explicitly provide a "safe" set vs. "full" set. can just mod the map func getters to accept a "safeOnly" bool param.

tplx/sprigx/consts.go

@@ -1,11 +1,14 @@
 package sprigx
 
 import (
+	`net`
+	`net/netip`
 	`os`
 	`os/user`
 	`path`
 	`path/filepath`
 	`runtime`
+	`time`
 
 	`github.com/davecgh/go-spew/spew`
 	`github.com/shirou/gopsutil/v4/cpu`
@@ -16,6 +19,9 @@ import (
 	psnet `github.com/shirou/gopsutil/v4/net`
 	`github.com/shirou/gopsutil/v4/process`
 	`github.com/shirou/gopsutil/v4/sensors`
+	`go4.org/netipx`
+	`r00t2.io/goutils/netx`
+	`r00t2.io/goutils/timex`
 	`r00t2.io/sysutils`
 )
 
@@ -28,6 +34,62 @@ var (
 			"Meta"/Template-Helpers
 		*/
 		"metaIsNil": metaIsNil,
+		/*
+			Networking (net)
+		*/
+		"netCidrMask":     net.CIDRMask,
+		"netExtractAddr":  netExtractAddr,
+		"netExtractHost":  netExtractHost,
+		"netExtractIpnet": netExtractIpnet,
+		"netExtractPort":  netExtractPort,
+		"netIfaces":       net.Interfaces,
+		"netIp4Mask":      netIp4Mask,
+		"netJoinHostPort": net.JoinHostPort,
+		"netParseIP":      net.ParseIP,
+		/*
+			Networking (net/netip)
+		*/
+		"netipAddrPort":      netip.AddrPortFrom,
+		"netipParseAddr":     netip.ParseAddr,
+		"netipParseAddrPort": netip.ParseAddrPort,
+		"netipParsePrefix":   netip.ParsePrefix,
+		"netipPrefix":        netip.PrefixFrom,
+		/*
+			Networking (go4.org/netipx)
+		*/
+		"netipxAddrIpNet":   netipx.AddrIPNet,
+		"netipxCmpPfx":      netipx.ComparePrefix,
+		"netipxFromStdAddr": netipxFromStdAddr,
+		"netipxFromIp":      netipxFromIp,
+		"netipxFromIpNet":   netipxFromIpNet,
+		"netipxParseRange":  netipx.ParseIPRange,
+		"netipxPfxAddr":     netipx.ParsePrefixOrAddr,
+		"netipxPfxIpNet":    netipx.PrefixIPNet,
+		"netipxPfxLast":     netipx.PrefixLastIP,
+		"netipxPfxRange":    netipx.RangeOfPrefix,
+		"netipxRange":       netipx.IPRangeFrom,
+		/*
+			Networking (r00t.io/goutils/netx)
+		*/
+		"netxAddrRfc":     netx.AddrRfc,
+		"netxCidr4IpMask": netx.Cidr4ToIPMask,
+		"netxCidr4Mask":   netx.Cidr4ToMask,
+		"netxCidr4Str":    netx.Cidr4ToStr,
+		"netxFamilyVer":   netx.FamilyToVer,
+		"netxGetAddrFam":  netx.GetAddrFamily,
+		"netxGetIpFam":    netx.GetIpFamily,
+		"netxIpRfc":       netx.IpRfc,
+		"netxIpRfcStr":    netx.IpRfcStr,
+		"netxIpStripRfc":  netx.IpStripRfcStr,
+		"netxIp4MaskCidr": netx.IPMask4ToCidr,
+		"netxIp4MaskMask": netx.IPMask4ToMask,
+		/*
+			Numbers/Math
+		*/
+		"numFloat32Str": numFloat32Str,
+		"numFloat64":    numFloat64,
+		"numFloat64Str": numFloat64Str,
+		"numFloatStr":   numFloatStr,
 		/*
 			OS
 		*/
@@ -119,7 +181,21 @@ var (
 		"sysNumCpu":  runtime.NumCPU,
 		"sysOsName":  sysOsNm,
 		"sysRuntime": sysRuntime,
-
+		/*
+			Time/Dates/Timestamps
+		*/
+		"tmDate":          time.Date,
+		"tmFmt":           tmFmt,
+		"tmFloatMicro":    timex.F64Microseconds,
+		"tmFloatMilli":    timex.F64Milliseconds,
+		"tmFloatNano":     timex.F64Nanoseconds,
+		"tmFloat":         timex.F64Seconds,
+		"tmNow":           time.Now,
+		"tmParseDur8n":    time.ParseDuration,
+		"tmParseMonth":    tmParseMonth,
+		"tmParseMonthInt": tmParseMonthInt,
+		"tmParseMonthStr": tmParseMonthStr,
+		"tmParseTime":     time.Parse,
 	}
 
 	// htmlMap holds functions usable/intended for use in only an [html/template.FuncMap].

tplx/sprigx/docinfo.html

@@ -0,0 +1,77 @@
+<!-- https://stackoverflow.com/a/34481639 -->
+<!-- Generate a nice TOC -->
+<script src="https://code.jquery.com/jquery-1.11.3.min.js"></script>
+<script src="https://code.jquery.com/ui/1.11.4/jquery-ui.min.js"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery.tocify/1.9.0/javascripts/jquery.tocify.min.js"></script>
+<!-- We do not need the tocify CSS because the asciidoc CSS already provides most of what we neeed -->
+
+<style>
+.tocify-header {
+    font-style: italic;
+}
+
+.tocify-subheader {
+    font-style: normal;
+    font-size: 90%;
+}
+
+.tocify ul {
+    margin: 0;
+ }
+
+.tocify-focus {
+    color: #7a2518; 
+    background-color: rgba(0, 0, 0, 0.1);
+}
+
+.tocify-focus > a {
+    color: #7a2518; 
+}
+</style>
+
+<script type="text/javascript">
+    $(function () {
+        // Add a new container for the tocify toc into the existing toc so we can re-use its
+        // styling
+        $("#toc").append("<div id='generated-toc'></div>");
+        $("#generated-toc").tocify({
+            extendPage: true,
+            context: "#content",
+            highlightOnScroll: true,
+            hideEffect: "slideUp",
+            // Use the IDs that asciidoc already provides so that TOC links and intra-document
+            // links are the same. Anything else might confuse users when they create bookmarks.
+            hashGenerator: function(text, element) {
+                return $(element).attr("id");
+            },
+            // Smooth scrolling doesn't work properly if we use the asciidoc IDs
+            smoothScroll: false,
+            // Set to 'none' to use the tocify classes
+            theme: "none",
+            // Handle book (may contain h1) and article (only h2 deeper)
+            selectors: $( "#content" ).has( "h1" ).size() > 0 ? "h1,h2,h3,h4,h5" : "h2,h3,h4,h5",
+            ignoreSelector: ".discrete"
+        });
+
+        // Switch between static asciidoc toc and dynamic tocify toc based on browser size
+        // This is set to match the media selectors in the asciidoc CSS
+        // Without this, we keep the dynamic toc even if it is moved from the side to preamble
+        // position which will cause odd scrolling behavior
+        var handleTocOnResize = function() {
+            if ($(document).width() < 768) {
+                $("#generated-toc").hide();
+                $(".sectlevel0").show();
+                $(".sectlevel1").show();
+            }
+            else {
+                $("#generated-toc").show();
+                $(".sectlevel0").hide();
+                $(".sectlevel1").hide();
+            }
+        }
+
+        $(window).resize(handleTocOnResize);
+        handleTocOnResize();
+    });
+</script>
+

tplx/sprigx/errs.go

@@ -0,0 +1,16 @@
+package sprigx
+
+import (
+	`errors`
+)
+
+var (
+	ErrBadAddr     error = errors.New("invalid/bad address")
+	ErrBadAddrPort error = errors.New("invalid/bad address/port")
+	ErrBadMonth    error = errors.New("could not determine/parse month")
+	ErrBadNet      error = errors.New("invalid/bad network")
+	ErrOverflow    error = errors.New("integer/buffer overflow")
+	ErrBadType     error = errors.New("an invalid/unknown type was passed")
+	ErrNilVal      error = errors.New("a nil value was passed")
+	ErrUnderflow   error = errors.New("integer/buffer underflow")
+)

tplx/sprigx/funcs.go

@@ -1,14 +1,116 @@
 package sprigx
 
 import (
+	`errors`
 	htpl "html/template"
+	`math`
+	`reflect`
+	`strconv`
 	ttpl "text/template"
+
+	`github.com/Masterminds/sprig/v3`
 )
 
 /*
 Many of these functions are modeled after sprig's.
 */
 
+/*
+CombinedFuncMap returns a generic function map (like [FuncMap]) combined with
+[github.com/Masterminds/sprig/v3.GenericFuncMap].
+
+If preferSprigx is true, SprigX function names will override Sprig
+functions with the same name.
+If false, Sprig functions will override conflicting SprigX functions
+with the same name.
+
+You probably want [CombinedHtmlFuncMap] or [CombinedTxtFuncMap] instead,
+as they wrap this with the appropriate type.
+*/
+func CombinedFuncMap(preferSprigX bool) (fmap map[string]any) {
+
+	var fn any
+	var fnNm string
+	var sprigMap map[string]interface{} = sprig.GenericFuncMap()
+	var sprigxMap map[string]any = FuncMap()
+
+	if preferSprigX {
+		fmap = sprigMap
+		for fnNm, fn = range sprigxMap {
+			fmap[fnNm] = fn
+		}
+	} else {
+		fmap = sprigxMap
+		for fnNm, fn = range sprigMap {
+			fmap[fnNm] = fn
+		}
+	}
+
+	return
+}
+
+/*
+CombinedHtmlFuncMap returns an [htpl.FuncMap] (like [HtmlFuncMap]) combined with
+[github.com/Masterminds/sprig/v3.HtmlFuncMap].
+
+If preferSprigx is true, SprigX function names will override Sprig
+functions with the same name.
+If false, Sprig functions will override conflicting SprigX functions
+with the same name.
+*/
+func CombinedHtmlFuncMap(preferSprigX bool) (fmap htpl.FuncMap) {
+
+	var fn any
+	var fnNm string
+	var sprigMap htpl.FuncMap = sprig.HtmlFuncMap()
+	var sprigxMap htpl.FuncMap = HtmlFuncMap()
+
+	if preferSprigX {
+		fmap = sprigMap
+		for fnNm, fn = range sprigxMap {
+			fmap[fnNm] = fn
+		}
+	} else {
+		fmap = sprigxMap
+		for fnNm, fn = range sprigMap {
+			fmap[fnNm] = fn
+		}
+	}
+
+	return
+}
+
+/*
+CombinedTxtFuncMap returns a [ttpl.FuncMap] (like [TxtFuncMap]) combined with
+[github.com/Masterminds/sprig/v3.TxtFuncMap].
+
+If preferSprigx is true, SprigX function names will override Sprig
+functions with the same name.
+If false, Sprig functions will override conflicting SprigX functions
+with the same name.
+*/
+func CombinedTxtFuncMap(preferSprigX bool) (fmap ttpl.FuncMap) {
+
+	var fn any
+	var fnNm string
+	var sprigMap ttpl.FuncMap = sprig.TxtFuncMap()
+	var sprigxMap ttpl.FuncMap = TxtFuncMap()
+
+	if preferSprigX {
+		fmap = sprigMap
+		for fnNm, fn = range sprigxMap {
+			fmap[fnNm] = fn
+		}
+	} else {
+		fmap = sprigxMap
+		for fnNm, fn = range sprigMap {
+			fmap[fnNm] = fn
+		}
+	}
+
+	return
+}
+
 /*
 FuncMap returns a generic function map.
 
@@ -57,6 +159,11 @@ func HtmlFuncMap() (fmap htpl.FuncMap) {
 	return
 }
 
+// Nop explicitly performs a NO-OP and returns an empty string, allowing one to override "unsafe" functions.
+func Nop(obj ...any) (s string) {
+	return
+}
+
 // TxtFuncMap returns a [text/template.FuncMap].
 func TxtFuncMap() (fmap ttpl.FuncMap) {
 
@@ -79,3 +186,171 @@ func TxtFuncMap() (fmap ttpl.FuncMap) {
 
 	return
 }
+
+/*
+toFloat64 uses reflection to resolve any string or numeric type (even custom types) to a float64.
+
+It wraps toString for string types but will fall back to checking numeric types.
+
+If err != nil, then NaN (if true) indicates that:
+
+	* val is a string (or pointer to a string), but
+	* is not a valid numeric string
+
+(you can do this from the caller as well by calling `errors.Is(err, strconv.ErrSyntax)`).
+err will always be non-nil if NaN is true.
+
+err will be ErrNilVal if val is nil.
+*/
+func toFloat64(val any) (f float64, NaN bool, err error) {
+
+	var s string
+	var k reflect.Kind
+	var rv reflect.Value
+
+	// toString will return ErrNilVal if nil.
+	if s, err = toString(val); err != nil {
+		if errors.Is(err, ErrBadType) {
+			// This is OK, it's (hopefully) a number type.
+			err = nil
+		} else {
+			// *probably* ErrNilVal.
+			return
+		}
+	} else {
+		// We can go ahead and parse this directly since it's already deref'd if a ptr.
+		if f, err = strconv.ParseFloat(s, 64); err != nil {
+			NaN = errors.Is(err, strconv.ErrSyntax)
+		}
+		// We can return regardless here; it's up to the caller to check NaN/err.
+		// If they're false/nil, f is parsed already!
+		return
+	}
+
+	rv = reflect.ValueOf(val)
+	k = rv.Kind()
+
+	if k == reflect.Ptr {
+		if rv.IsNil() {
+			// *technically* this should be handled above, but best be safe.
+			err = ErrNilVal
+			return
+		}
+		rv = rv.Elem()
+		k = rv.Kind()
+	}
+
+	switch k {
+	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+		f = float64(rv.Int())
+	case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
+		f = float64(rv.Uint())
+	case reflect.Float32, reflect.Float64:
+		f = rv.Float()
+	default:
+		// No need to check for string types since we do that near the beginning.
+		err = ErrBadType
+		return
+	}
+
+	return
+}
+
+/*
+toInt wraps toFloat64, rounds it to the nearest integer,
+and converts to an int.
+
+NaN, err have the same meaning as in toFloat64.
+
+This function will panic if float64(val)'s f return exceeds
+math.MaxInt on your platform.
+*/
+func toInt(val any) (i int, NaN bool, err error) {
+
+	var f float64
+
+	if f, NaN, err = toFloat64(val); err != nil {
+		return
+	}
+
+	i = int(math.Round(f))
+
+	return
+}
+
+/*
+toPosFloat64 wraps toFloat64 and ensures that it is a positive float64.
+
+NaN, err have the same meaning as in toFloat64.
+*/
+func toPosFloat64(val any) (f float64, NaN bool, err error) {
+
+	if f, NaN, err = toFloat64(val); err != nil {
+		return
+	}
+
+	f = math.Abs(f)
+
+	return
+}
+
+/*
+toPosInt wraps toPosFloat64, rounds it to the nearest integer,
+and converts to an int.
+
+NaN, err have the same meaning as in toPosFloat64 (and thus toFloat64).
+
+This function will panic if float64(val)'s f return exceeds
+math.MaxInt on your platform.
+*/
+func toPosInt(val any) (i int, NaN bool, err error) {
+
+	var f float64
+
+	if f, NaN, err = toPosFloat64(val); err != nil {
+		return
+	}
+
+	i = int(math.Round(f))
+
+	return
+}
+
+/*
+toString uses reflection to resolve any string value (even custom types and ptrs)
+to a concrete string.
+
+err will be ErrBadType if val is not a string type/string-derived type.
+err will be ErrNilVal if val is nil.
+*/
+func toString(val any) (s string, err error) {
+
+	var rv reflect.Value
+	var k reflect.Kind
+
+	if val == nil {
+		err = ErrNilVal
+		return
+	}
+
+	rv = reflect.ValueOf(val)
+	k = rv.Kind()
+
+	if k == reflect.Ptr {
+		if rv.IsNil() {
+			// *technically* this should be handled above, but best be safe.
+			err = ErrNilVal
+			return
+		}
+		rv = rv.Elem()
+		k = rv.Kind()
+	}
+
+	if k == reflect.String {
+		s = rv.String()
+	} else {
+		err = ErrBadType
+	}
+
+	return
+}

tplx/sprigx/funcs_tpl_meta.go

@@ -1,10 +1,5 @@
 package sprigx
 
-// Nop explicitly performs a NO-OP and returns an empty string, allowing one to override "unsafe" functions.
-func Nop(obj ...any) (s string) {
-	return
-}
-
 // metaIsNil returns true if obj is explicitly nil.
 func metaIsNil(obj any) (isNil bool) {
 

tplx/sprigx/funcs_tpl_net.go

@@ -0,0 +1,82 @@
+package sprigx
+
+import (
+	`math`
+	`net`
+	`strconv`
+)
+
+// netExtractAddr calls net.ParseCIDR and returns the net.IP from it.
+func netExtractAddr(s string) (addr net.IP, err error) {
+
+	if addr, _, err = net.ParseCIDR(s); err != nil {
+		return
+	}
+
+	return
+}
+
+// netExtractHost extracts the host component from hostPort.
+func netExtractHost(hostPort string) (host string, err error) {
+
+	if host, _, err = net.SplitHostPort(hostPort); err != nil {
+		return
+	}
+
+	return
+}
+
+// netExtractIpnet calls net.ParseCIDR and returns the net.IPNet from it.
+func netExtractIpnet(s string) (ipnet *net.IPNet, err error) {
+
+	if _, ipnet, err = net.ParseCIDR(s); err != nil {
+		return
+	}
+
+	return
+}
+
+// netExtractPort extracts the port component from hostPort.
+func netExtractPort(hostPort string) (port uint16, err error) {
+
+	var portStr string
+	var u64 uint64
+
+	if _, portStr, err = net.SplitHostPort(hostPort); err != nil {
+		return
+	}
+
+	if u64, err = strconv.ParseUint(portStr, 10, 16); err != nil {
+		return
+	}
+	port = uint16(u64)
+
+	return
+}
+
+// netIp4Mask is a more flexible wrapper around net.IPv4Mask.
+func netIp4Mask(a, b, c, d any) (mask net.IPMask, err error) {
+
+	var idx int
+	var elem any
+	var elemInt int
+	var mBytes [4]byte
+	var orig [4]any = [4]any{a, b, c, d}
+
+	for idx, elem = range orig {
+		if elemInt, _, err = toPosInt(elem); err != nil {
+			return
+		}
+		if elemInt > math.MaxUint8 {
+			err = ErrOverflow
+			return
+		}
+		mBytes[idx] = byte(uint8(elemInt))
+	}
+
+	mask = net.IPv4Mask(
+		mBytes[0], mBytes[1], mBytes[2], mBytes[3],
+	)
+
+	return
+}

tplx/sprigx/funcs_tpl_netipx.go

@@ -0,0 +1,47 @@
+package sprigx
+
+import (
+	`net`
+	`net/netip`
+
+	`go4.org/netipx`
+)
+
+// netipxFromStdAddr wraps go4.org/netipx.FromStdAddr to comply with Go template requirements.
+func netipxFromStdAddr(ip net.IP, port int, zone string) (addrPort netip.AddrPort, err error) {
+
+	var ok bool
+
+	if addrPort, ok = netipx.FromStdAddr(ip, port, zone); !ok {
+		err = ErrBadAddrPort
+		return
+	}
+
+	return
+}
+
+// netipxFromIp wraps go4.org/netipx.FromStdIP to comply with Go template requirements.
+func netipxFromIp(ip net.IP) (addr netip.Addr, err error) {
+
+	var ok bool
+
+	if addr, ok = netipx.FromStdIP(ip); !ok {
+		err = ErrBadAddr
+		return
+	}
+
+	return
+}
+
+// netipxFromIpNet wraps go4.org/netipx.FromStdIPNet to comply with Go template requirements.
+func netipxFromIpNet(ipnet *net.IPNet) (pfx netip.Prefix, err error) {
+
+	var ok bool
+
+	if pfx, ok = netipx.FromStdIPNet(ipnet); !ok {
+		err = ErrBadNet
+		return
+	}
+
+	return
+}

tplx/sprigx/funcs_tpl_nums.go

@@ -0,0 +1,51 @@
+package sprigx
+
+import (
+	`math/big`
+)
+
+// numFloat64 returns any string representation of a numeric value or any type of numeric value to a float64.
+func numFloat64(val any) (f float64, err error) {
+
+	if f, _, err = toFloat64(val); err != nil {
+		return
+	}
+
+	return
+}
+
+/*
+numFloatStr wraps numFloat32Str and numFloat64Str.
+
+val can be a string representation of any numeric value or any type of numeric value.
+*/
+func numFloatStr(val any) (s string, err error) {
+
+	var f float64
+
+	if f, _, err = toFloat64(val); err != nil {
+		return
+	}
+	s = numFloat64Str(f)
+
+	return
+}
+
+// numFloat32Str returns float32 f as a complete string representation with no truncation (or right-padding).
+func numFloat32Str(f float32) (s string) {
+
+	s = numFloat64Str(float64(f))
+
+	return
+}
+
+// numFloat64Str returns float64 f as a complete string representation with no truncation (or right-padding).
+func numFloat64Str(f float64) (s string) {
+
+	var bf *big.Float
+
+	bf = big.NewFloat(f)
+	s = bf.Text('f', -1)
+
+	return
+}

tplx/sprigx/funcs_tpl_os.go

@@ -7,16 +7,29 @@ import (
 	`strings`
 )
 
-// osGroupById returns os/user.LookupGroupId. Can accept either an integer or a string.
-func osGroupById[T string | int](gid T) (g *user.Group, err error) {
+/*
+osGroupById returns os/user.LookupGroupId.
 
+Can accept either a string (`"1000"`) or any
+numeric type (`1000`, `-1000`, `1000.0`, `MyCustomType(1000)`, etc.)
+*/
+func osGroupById(gid any) (g *user.Group, err error) {
+
+	var i int
+	var NaN bool
 	var gidStr string
 
-	switch t := any(gid).(type) {
-	case string:
-		gidStr = t
-	case int:
-		gidStr = strconv.Itoa(t)
+	if i, NaN, err = toPosInt(gid); err != nil {
+		if NaN {
+			err = nil
+			if gidStr, err = toString(gid); err != nil {
+				return
+			}
+		} else {
+			return
+		}
+	} else {
+		gidStr = strconv.Itoa(i)
 	}
 
 	g, err = user.LookupGroupId(gidStr)
@@ -55,16 +68,29 @@ func osHost() (hostNm string, err error) {
 	return
 }
 
-// osUserById returns an os/user.LookupId. Can accept either an integer or a string.
-func osUserById[T string | int](uid T) (u *user.User, err error) {
+/*
+osUserById returns an os/user.LookupId.
 
+Can accept either a string (`"1000"`) or any
+numeric type (`1000`, `-1000`, `1000.0`, `MyCustomType(1000)`, etc.)
+*/
+func osUserById(uid any) (u *user.User, err error) {
+
+	var i int
+	var NaN bool
 	var uidStr string
 
-	switch t := any(uid).(type) {
-	case string:
-		uidStr = t
-	case int:
-		uidStr = strconv.Itoa(t)
+	if i, NaN, err = toPosInt(uid); err != nil {
+		if NaN {
+			err = nil
+			if uidStr, err = toString(uid); err != nil {
+				return
+			}
+		} else {
+			return
+		}
+	} else {
+		uidStr = strconv.Itoa(i)
 	}
 
 	u, err = user.LookupId(uidStr)

tplx/sprigx/funcs_tpl_time.go

@@ -0,0 +1,139 @@
+package sprigx
+
+import (
+	`errors`
+	`strconv`
+	`strings`
+	`time`
+)
+
+/*
+tmFmt formats time t using format string fstr.
+
+While one certainly can do the same via e.g.
+
+	{{- $t := tmNow -}}
+	{{ $t.Format $fstr }}
+
+This takes a time.Time as the second (and last) parameter,
+allowing it to work in pipelines.
+*/
+func tmFmt(fstr string, t time.Time) (out string) {
+
+	out = t.Format(fstr)
+
+	return
+}
+
+/*
+tmParseMonth attempts to first try tmParseMonthInt
+and then tries tmParseMonthStr if v is not "numeric".
+*/
+func tmParseMonth(v any) (mon time.Month, err error) {
+
+	var s string
+
+	if mon, err = tmParseMonthInt(v); err != nil {
+		if errors.Is(err, strconv.ErrSyntax) {
+			// NaN
+			err = nil
+		} else {
+			return
+		}
+	}
+
+	// If it gets here, it's a non-numeric string.
+	if s, err = toString(v); err != nil {
+		return
+	}
+	if mon, err = tmParseMonthStr(s); err != nil {
+		return
+	}
+
+	return
+}
+
+/*
+tmParseMonthInt parses a number representation of month n to a time.Month.
+n may be any numeric type or a string representation of a number
+(or a custom type derived from those).
+
+A negative integer (or float, etc.) will be converted to a positive one (e.g. -6 => 6 => time.June).
+
+floats are rounded to the nearest integer.
+
+The integer should map directly to the month constants in the time module:
+
+	* 1: January
+	* 2: February
+	* 3: March
+	* 4: April
+	* 5: May
+	* 6: June
+	* 7: July
+	* 8: August
+	* 9: September
+	* 10: October
+	* 11: November
+	* 12: December
+
+If n resolves to 0, mon will be the current month (as determined by time.Now).
+
+If n resolves to > 12, err will be ErrBadMonth.
+*/
+func tmParseMonthInt(n any) (mon time.Month, err error) {
+
+	var i int
+
+	if i, _, err = toPosInt(n); err != nil {
+		return
+	}
+
+	if i == 0 {
+		mon = time.Now().Month()
+		return
+	}
+
+	if i > 12 {
+		err = ErrBadMonth
+		return
+	}
+
+	mon = time.Month(i)
+
+	return
+}
+
+/*
+tmParseMonthStr parses a string representation of month s to a time.Month.
+
+It normalizes s to lowercase and only uses the first 3 characters
+(the minimum length needed to determine month name
+uniqueness - "June" vs. "July", "March" vs. "May").
+
+An empty (or whitespace-only) string will use the current month (as determined by time.Now).
+*/
+func tmParseMonthStr(s string) (mon time.Month, err error) {
+
+	var i int
+	var m time.Month
+
+	if strings.TrimSpace(s) == "" {
+		mon = time.Now().Month()
+		return
+	}
+
+	s = strings.ToLower(strings.TrimSpace(s))[0:3]
+
+	for i = range 12 {
+		m = time.Month(i + 1)
+		if strings.ToLower(m.String())[0:3] == s {
+			mon = m
+			return
+		}
+	}
+
+	err = ErrBadMonth
+
+	return
+}

uuidx/consts.go

@@ -0,0 +1,11 @@
+package uuidx
+
+const (
+	RfcNone RfcGen = iota
+	Rfc4122
+	Rfc9562
+)
+
+const (
+	MsGuidThreshold int = 4
+)

uuidx/doc.go

@@ -0,0 +1,73 @@
+/*
+Package uuidx intends to supplement [github.com/google/uuid].
+
+# Microsoft GUID Shenanigans
+
+The following functions are provided to deal with [Microsoft's incompetence]:
+
+	* [DetectMsGuid] (a confidence'd determination if a UUID is a Microsoft GUID or not)
+	* [IsFlippedEndian] for flipped-endian [uuid.UUID] comparison (e.g. a is the Microsoft-flipped-endian version of b)
+	* [IsMsGuid] (wraps [DetectMsGuid] and returns true if confidence is reasonably strong that it's a Microsoft GUID)
+	* [IsRfc] (the inverse of IsMsGuid, but also checks for strict RFC compliance and returns which RFC)
+	* [MsGuidToUuid] (explicitly convert/ensure a GUID/UUID is likely a UUID)
+	* [ToggleUuidMsGuid] (blindly flip the endianness of selected byte ranges for MS GUID <-> UUID conversion)
+	* [UuidToMsGuid] (explicitly convert/ensure a GUID/UUID is likely an MS GUID)
+
+Microsoft, in their typical insanity, uses a proprietary UUID format (usually referred to as the "Microsoft GUID Format"
+or "Mixed-Endian Format").
+
+Normally for, for example a UUIDv4, it's structured as thus per RFC 9562 [§ 5.4] (which obsoletes RFC 4122 [§ 4.4]):
+
+	       A               B               C               D                E
+	HEX(BE(uint32))-HEX(BE(uint16))-HEX(BE(uint16))-HEX(BE(<uint16>), BE(<6 bytes>))
+
+(where <BE> is big-endian packing).
+
+However, thanks to Microsoft we can't have nice things. They decided to completely ignore the standard, and
+instead keep D/E as big-endian *but use little-endian* for A through C inclusive:
+
+	       A               B               C               D                E
+	HEX(LE(uint32))-HEX(LE(uint16))-HEX(LE(uint16))-HEX(BE(<uint16>), BE(<6 bytes>))
+
+"Surely that had SOME reason to do that," you may say to yourself, "they wouldn't make some arbitrary formatting
+change from a standard just because."
+
+You would be wrong. To my knowledge, they have never provided any technological justfification to this insanity,
+and now it's infected its way into a slew of other technologies they've had their grubby little hands involved in
+(e.g. UEFI). And it's of course too late to change.
+
+So anyways here's a library to make dealing with Microsoft's hubris a little easier.
+
+# Validation/Verification
+
+Aside from trying to address Microsoft silliness, there are some additional functions:
+
+	* [Equal] for [uuid.UUID] comparison
+	* [IsMaxUUID] (if a given [uuid.UUID] is an RFC 9562 [§ 5.10] UUID)
+	* [IsNilUUID] (if a given [uuid.UUID] is an RFC 9562 [§ 5.9] UUID)
+	* [IsValid] (If an RFC can be considered safely conformant to RFC spec)
+
+# Future Incorporation/Deprecation/Obsolescence
+
+Worth keeping an eye on are:
+
+	* https://github.com/google/uuid/pull/192
+	* https://github.com/golang/go/issues/62026
+	* https://github.com/golang/go/issues/76319
+		(generally it's a bad idea for an API addition overall, but some good ideas were raised)
+
+Some of these additions may deprecate/obsolete components of this package.
+I'll try to keep them around but mark as deprecated as they are (if they are),
+but I make no concrete promises - I hate making new major releases in Go's
+[silly module architecture] even more than I do keeping old deprecated code around.
+So caveat emptor.
+
+[Microsoft's incompetence]: https://learn.microsoft.com/en-us/windows/win32/api/guiddef/ns-guiddef-guid
+[§ 5.4]: https://datatracker.ietf.org/doc/html/rfc9562#section-5.4
+[§ 4.4]: https://datatracker.ietf.org/doc/html/rfc4122#section-4.4
+[§ 5.9]: https://datatracker.ietf.org/doc/html/rfc9562#section-5.9
+[§ 5.10]: https://datatracker.ietf.org/doc/html/rfc9562#section-5.10
+[github:google/uuid#192]: https://github.com/google/uuid/pull/192
+[silly module architecture]: https://go.dev/doc/modules/major-version
+*/
+package uuidx

uuidx/funcs.go

@@ -0,0 +1,481 @@
+package uuidx
+
+import (
+	"github.com/google/uuid"
+)
+
+/*
+DetectMsGuid tries to guess if a given [uuid.UUID] is actually a Microsoft GUID or not.
+
+Note that there are technically *two* types of Microsoft GUIDs:
+
+	* One is predictable, and defined in RFC 9562 [§ 4.2] as a known variant.
+		Detecting this is very easy and (assuming an RFC-compliant UUID is originally passed) is detectable with 100% confidence.
+		It's also legacy, and Microsoft no longer uses this format. Because they are insane and enjoy the suffering of others.
+	* The other, MODERN Microsoft GUID currently in use is the endianness-flipped version (see [ToggleUuidMsGuid]).
+		This is impossible to 100% determine, but analysis can get *pretty* close.
+
+cs is a confidence scoring. As more logic is added, it *is* mathematically possible
+(though unlikely) that cs == 0, so the caller is then responsible for making further
+guesswork based on contextual analysis ("Did I get this UUID/GUID from an Active Directory attribute?"
+"Is it a SID constant?" etc.).
+
+A score > 0 indicates a confidence leaning towards the provided UUID/GUID being a Microsoft GUID.
+A score < 0 indicates a confidence leaning towards the provided UUID/GUID *not* being a Microsoft GUID.
+Note that a score of < 0 does not necessarily indicate it is a *proper, standard RFC-compliant UUID*,
+simply that it is likely NOT a Microsoft GUID. [IsRfc] will be of further help in these cases.
+
+csFlip indicates a score for the [ToggleUuidMsGuid]-flipped version of u.
+It follows the same rules for thresholds and such as cs, but may be awarded different confidence levels
+internally due to different chances of false positives.
+If both cs and csFlip are > 0 but csFlip > cs, it is better to assume that u is *not* in the flipped-endian format
+but *is* a Microsoft GUID (in other words, it is likely that u has *already been flipped* to proper/consistent endianness
+instead of being a mixed-endian GUID).
+
+In some cases where flipped-endianness does not matter (e.g. [IsNilUUID], [IsMaxUUID]),
+cs and csFlip will be equal.
+
+*Randomly-generated* GUIDs on Windows Server 2000-family and up are almost always UUIDv4.
+Pre-Windows Server 2000 family *OR* any *statically-defined* GUIDs (schemaIDGUID, rightsGUID, CLSID constants, etc.)
+are all over the place - TYPICALLY UUIDv1, but it's nothing predictable enough to be useful in definitive classification.
+COM interfaces are all OVER the place in UUID version, but usually *not* UUIDv4.
+
+A target/expected UUID version can be provided via tgtVer. To disable version analysis, use 0 (or 0x00, etc.).
+It is *highly* recommended to provide a tgtVer if it is known; it can significantly boost confidence in the correct direction.
+A warning, though - if a tgtVer IS specified but is wrong (e.g. a UUIDv1 was passed in but tgtVer was specified as 4 for UUIDv4),
+it can *negatively* affect confidence accuracy.
+Thus if you aren't ABSOLUTELY certain of the target UUID version, it's better to use 0/0x00 to disable the check.
+Providing a target version can be key to breaking some "ties" (e.g. both cs and csFlip are equal).
+For example, the given RFC-compliant UUIDv4:
+
+	8d8e35ae-58d2-4d28-b09d-ffffffffffff
+
+when flipped evaluates to an RFC-compliant UUIDv2:
+
+	ae358e8d-d258-284d-b09d-ffffffffffff
+
+and in this case, cs and csFlip will both end up as 0.
+Providing a tgtVer of 4 shifts this to a proper "tie-breaker" of cs == -3 and csFlip == 0.
+Similarly, the endian-flipped UUIDv4 evaluates as a UUIDv2:
+
+	9856ea36-c2ca-2347-af0c-3b42f76c9eca
+
+from the original unflipped UUIDv4:
+
+	36ea5698-cac2-4723-af0c-3b42f76c9eca
+
+which results in a cs == 1 and csFlip == 0 - not very high confidence (but at least a correct and non-zero lean).
+Providing a tgtVer == 4 changes this to cs == 7 and csFlip == 0, which is *much* more decisive.
+
+UUIDs/GUIDs found to be strictly RFC-conforming (via [IsRfc], which returns false for Microsoft GUIDs)
+are *heavily* weighted negatively in their respective scoring forms.
+
+Confidence levels can be generally considered as the following:
+
+	* cs >= 7: Likely Microsoft GUID (mixed-endian)
+	* cs >= 4: Likely Microsoft GUID
+	* 0 < cs < 4: Leans Microsoft GUID, but untrusted/ambiguous
+	* cs == 0: Entirely and completely ambiguous/indeterminate
+	* -4 < cs < 0: Leans UUID/non-Microsoft GUID but untrusted/ambiguous
+	* cs <= -5: Likely UUID/not Microsoft GUID
+	* csFlip >= cs && csFlip >= 4: u is likely a pre-flipped (ToggleUuidMsGuid'd) Microsoft GUID
+					(i.e. u is likely directly from a Microsoft API/ data source
+					and no normalization has occurred yet)
+
+[§ 4.2]: https://datatracker.ietf.org/doc/html/rfc9562#section-4.2
+*/
+func DetectMsGuid(u uuid.UUID, tgtVer uuid.Version) (cs, csFlip int) {
+
+	var isRfc bool
+	var flippedRfc bool
+	var flipped uuid.UUID = ToggleUuidMsGuid(u)
+
+	// These are the exact same when flipped, and are statically defined.
+	if IsNilUUID(u) || IsMaxUUID(u) {
+		cs = -12
+		csFlip = -12
+		return
+	}
+
+	// Most/all(?) Microsoft GUIDs are not NCS.
+	if IsNcs(u) {
+		cs -= 2
+	}
+	if IsNcs(flipped) {
+		// The flipped has a higher likelihood of false-pos, so we don't score it as confidently.
+		csFlip -= 1
+	}
+
+	if u.Version() == 0 {
+		if u.Variant() == uuid.Microsoft {
+			cs += 10
+		} else {
+			cs -= 2
+		}
+	}
+	if flipped.Version() == 0 {
+		if flipped.Variant() == uuid.Microsoft {
+			csFlip += 4
+		} else {
+			csFlip -= 1
+		}
+	}
+
+	// Valid RFC version and variant. IsRfc returns false for the Microsoft Variant and version == 0.
+	// Modern MS uses an RFC 4122 variant indicator but flips the endianness.
+	isRfc, _ = IsRfc(u)
+	flippedRfc, _ = IsRfc(flipped)
+	if u.Variant() == uuid.RFC4122 { // This might be the strongest indicator.
+		if isRfc && !flippedRfc {
+			// This is *very* strong of being an MS GUID.
+			cs -= 8
+			csFlip += 4
+		} else if !isRfc && flippedRfc {
+			// It probably is an MS GUID but was already flipped.
+			csFlip += 6
+		} else if isRfc && flippedRfc {
+			/*
+				If both are RFC-compat, it's a weird case where
+				it actually IS RFC compliant and by chance the flipped is *also* RFC compat.
+				An example of this is:
+					8d8e35ae-58d2-4d28-b09d-ffffffffffff
+				Which has the flipped version of:
+					ae358e8d-d258-284d-b09d-ffffffffffff
+				The original is a v4, the flipped evaluates as a v2!
+
+				Providing a target version breaks this away to a definitive score.
+			*/
+		}
+	}
+
+	// *HEAVILY* weigh a provided version.
+	if tgtVer != 0 {
+		// NCS does some weird things to the versioning field. We return early on it though.
+		// MS GUIDs have a pretty small chance of matching,
+		// but their flipped counterpart SHOULD match versions.
+		if flipped.Version() == tgtVer {
+			cs += 7
+		} else {
+			cs -= 3
+		}
+	} else {
+		// Give a *very small* boost to flippedRfc and flipped.Version() == 4, since it's so common.
+		// Don't make this too high though since the version is explicitly specified as unknown.
+		if flippedRfc && flipped.Version() == 4 {
+			cs += 1
+		}
+	}
+
+	return
+}
+
+/*
+Equal returns `true` if the two provided [uuid.UUID] are the same.
+
+Currently it just wraps:
+
+	eq = a == b
+
+but is provided as a safety guarantee if the underlying structures/types should change.
+*/
+func Equal(a, b uuid.UUID) (eq bool) {
+
+	eq = a == b
+
+	return
+}
+
+/*
+IsFlippedEndian can be used to check if [uuid.UUID] is a direct endian-flipped ([ToggleUuidMsGuid])
+of b (or vice versa, obviously).
+
+It simply wraps:
+
+		isFlipped = Equal(a, ToggleUuidMsGuid(b))
+
+but can be useful for shorthand/readability.
+*/
+func IsFlippedEndian(a, b uuid.UUID) (isFlipped bool) {
+
+	isFlipped = Equal(a, ToggleUuidMsGuid(b))
+
+	return
+}
+
+/*
+IsMaxUUID returns `true` if the specified UUID is explicitly an RFC-defined
+"Max UUID". (You may also see it specified in some places as the "Omni UUID".)
+
+For details, see RFC 9562 [§ 5.10].
+
+[§ 5.10]: https://datatracker.ietf.org/doc/html/rfc9562#section-5.10
+*/
+func IsMaxUUID(u uuid.UUID) (isMax bool) {
+
+	isMax = u == uuid.Max
+
+	return
+}
+
+/*
+IsMsGuid wraps
+
+	if cmp, _ = DetectMsGuid(msGUID, tgtVer); cmp < -3 {
+		isMs = true
+	}
+
+Note that [uuid.Microsoft] is an actual RFC-defined variant, but *Microsoft no longer uses it*
+and in MODERN implementations do the endianness flip [ToggleUuidMsGuid] of (USUALLY) a UUIDv4.
+
+See [DetectMsGuid] for a more in-depth result that will let you use the confidence level directly,
+and for details on the weird things that can go wrong with this guesswork.
+
+Note that this won't be 100% reliable due to math things, but it should be ...somewhat reliable
+enough most of the time. Maybe. But you are *strongly* recommended to use [DetectMsGuid] instead
+wherever possible.
+
+See also [MsGuidToUuid] and [UuidToMsGuid].
+*/
+func IsMsGuid(msGUID uuid.UUID, tgtVer uuid.Version) (isMs bool) {
+
+	var cmp int
+
+	if cmp, _ = DetectMsGuid(msGUID, tgtVer); cmp < -3 {
+		isMs = true
+	}
+
+	return
+}
+
+/*
+IsNcs is shorthand for:
+
+	isNcs = u.Variant() == uuid.Reserved
+
+See also the notes in [IsRfc].
+*/
+func IsNcs(u uuid.UUID) (isNcs bool) {
+
+	// https://archive.org/details/networkcomputing0000zahn/page/10/mode/1up
+
+	isNcs = u.Variant() == uuid.Reserved
+
+	return
+}
+
+/*
+IsNilUUID returns `true` if the specified UUID is explicitly an RFC-defined
+"Nil UUID".
+
+For details, see RFC 9562 [§ 5.9].
+
+[§ 5.9]: https://datatracker.ietf.org/doc/html/rfc9562#section-5.9
+*/
+func IsNilUUID(u uuid.UUID) (isNil bool) {
+
+	isNil = u == uuid.Nil
+
+	return
+}
+
+/*
+IsRfc returns `true` if the specified UUID is a proper standard RFC UUID.
+
+Because Microsoft is insane, rfc will be false even if it's a (legacy) Microsoft form
+of an RFC UUID. Use [IsMsGuid] for that.
+
+In the special case of u being a valid NCS UUID, rfc will be false but gen will be [Rfc4122].
+This is because RFC 9652 deprecates the NCS UUID. See [IsNcs].
+(You are highly unlikely to encounter an NCS UUID "in the wild" unless you are working
+with VERY old systems/data or are receiving a UUID from someone who severely
+misunderstands that UUIDs are structured/versioned/typed and thinks they're
+just random byes in hex with hyphens in certain places.)
+(They aren't that, if you're one of those someones.)
+
+Nil UUID ([IsNilUUID]) and Max UUID ([IsMaxUUID]) return true with RFCs 4122 and RFC 9562 respectively.
+*/
+func IsRfc(u uuid.UUID) (rfc bool, gen RfcGen) {
+
+	if IsNilUUID(u) {
+		rfc = true
+		gen = Rfc4122
+		return
+	}
+	if IsMaxUUID(u) {
+		rfc = true
+		gen = Rfc9562
+		return
+	}
+	if IsNcs(u) {
+		gen = Rfc4122
+		return
+	}
+
+	// TODO: Are there any sub-version checks that can be applied?
+	switch u.Variant() {
+	case uuid.Invalid, uuid.Microsoft, uuid.Future:
+		return
+	case uuid.RFC4122:
+		if !(0x01 <= u.Version() && u.Version() <= 0x08) {
+			return
+		}
+		rfc = true
+		gen = Rfc4122
+		// 4122 only covers UUIDv1 through UUIDv5.
+		if 0x06 <= u.Version() && u.Version() <= 0x08 {
+			gen = Rfc9562
+		}
+	default: // Safety net in case upstream adds a uuid.RFC9562 variant or something.
+		if !(0x01 <= u.Version() && u.Version() <= 0x08) {
+			return
+		}
+		if u.Variant() < uuid.Future {
+			return
+		}
+		rfc = true
+		gen = RfcNone
+		// 4122 only covers UUIDv1 through UUIDv5.
+		if 0x06 <= u.Version() && u.Version() <= 0x08 {
+			gen = Rfc9562
+		}
+	}
+
+	return
+}
+
+/*
+IsValid indicates if the given [uuid.UUID] strictly conforms to RFC.
+
+A Nil UUID (as in RFC 9562 [§ 5.9], not a `nil` *uuid.UUID) will return `true`
+as it IS technically defined per RFC despite not conforming to a version.
+Use [IsNilUUID] to further determine that.
+
+Likewise, a Max UUID (RFC 9562 [§ 5.10]) will return `true` as it is also
+defined per RFC despite not conforming to a version.
+Use [IsMaxUUID] to further determine that.
+
+Microsoft GUIDs will always return false since they defy RFC.
+Use [IsMsGuid] to check for that condition.
+
+[§ 5.9]: https://datatracker.ietf.org/doc/html/rfc9562#section-5.9
+[§ 5.10]: https://datatracker.ietf.org/doc/html/rfc9562#section-5.10
+*/
+func IsValid(u uuid.UUID) (valid bool) {
+
+	if IsNilUUID(u) {
+		valid = true
+		return
+	}
+	if IsMaxUUID(u) {
+		valid = true
+		return
+	}
+
+	switch u.Variant() {
+	case uuid.Invalid, uuid.Reserved, uuid.Microsoft, uuid.Future:
+		return
+	case uuid.RFC4122:
+		valid = true
+	// TODO: If they add an RFC9562 or something, need a case here.
+	default:
+		return
+	}
+
+	// If we got here, it *should* be RFC.
+	if valid, _ = IsRfc(u); !valid {
+		return
+	}
+
+	return
+}
+
+/*
+MsGuidToUuid converts a Microsoft GUID to a UUID.
+
+If [IsMsGuid] is false for msGUID, u will be equal to msGUID.
+
+See [UuidToMsGuid] for the inverse, and [IsRfc] to check
+if the result is a strictly conforming UUID.
+
+Use [ToggleUuidMsGuid] if you want msGUID explicitly flipped
+with no gating from [IsMsGuid].
+*/
+func MsGuidToUuid(msGUID uuid.UUID) (u uuid.UUID) {
+
+	if !IsMsGuid(msGUID, 0x00) {
+		u = msGUID
+		return
+	}
+	u = ToggleUuidMsGuid(msGUID)
+
+	return
+}
+
+/*
+ToggleUuidMsGuid switches the src to it's "other" format:
+
+	* if it's a Microsoft GUID, it will be converted to a UUID
+	* if it's a UUID, it will be converted to a Microsoft GUID
+
+No detection ([IsRfc], [IsMsGuid], etc.) nor validation/verification ([IsValid]) is performed,
+which is why this is a "toggle" - it just flips some endianness for certain byte ranges.
+
+If you prefer something a little more explicit, see [MsGuidToUuid] and/or [UuidToMsGuid].
+Alternatively call [IsMsGuid] or [IsRfc] directly.
+*/
+func ToggleUuidMsGuid(orig uuid.UUID) (converted uuid.UUID) {
+
+	var cb [16]byte
+	var ob [16]byte = orig
+
+	// Can just directly map the allocations;
+	// the operation is the exact same regardless of whether the original is RFC and target is MS or vice versa.
+	cb = [16]byte{
+		// THESE GET ENDIAN-SWAPPED
+		ob[3], ob[2], ob[1], ob[0], // "A"
+		ob[5], ob[4], // "B"
+		ob[7], ob[6], // "C"
+		// THESE STAY THE SAME (should be BE for both)
+		ob[8], ob[9], ob[10], ob[11], // "D"
+		ob[12], ob[13], ob[14], ob[15], // "E"
+	}
+
+	converted = uuid.UUID(cb)
+
+	return
+}
+
+/*
+UuidToMsGuid converts a UUID to a Microsoft GUID.
+
+If [DetectMsGuid] indicates a good likelihood for u already being a Microsoft GUID
+(cs being greater than or equal to [MsGuidThreshold]), msGUID will be equal to u.
+
+If [DetectMsGuid] detects it as a Microsoft unflipped endianness (i.e. csFlip > cs),
+msGUID will be the [ToggleUuidMsGuid]-flipped format of u UNLESS u.Variant == [uuid.Microsoft].
+Thus this function *should* (with plenty of caveats mentioned elsewhere in other functions/documentation)
+be usable for flipping a purely non-Microsoft-tainted RFC-conforming UUID, and not flipping it otherwise
+as it's already a "Microsoft GUID" of some generation (either legacy or newer).
+
+See [MsGuidToUuid] for the inverse.
+
+Use [ToggleUuidMsGuid] if you want u explicitly flipped with no gating from [DetectMsGuid] or
+via u's [uuid.Variant].
+*/
+func UuidToMsGuid(u uuid.UUID) (msGUID uuid.UUID) {
+
+	var msCmp int
+	var flipped int
+
+	if msCmp, flipped = DetectMsGuid(u, 0x00); msCmp >= MsGuidThreshold && msCmp > flipped {
+		msGUID = u
+		return
+	}
+	if u.Variant == uuid.Microsoft {
+		msGUID = u
+		return
+	}
+	msGUID = ToggleUuidMsGuid(u)
+
+	return
+}

uuidx/funcs_rfcgen.go

@@ -0,0 +1,22 @@
+package uuidx
+
+// String conforms an [RfcGen] to a [fmt.Stringer] interface.
+func (g *RfcGen) String() (s string) {
+
+	if g == nil {
+		s = "UNSPECIFIED_NIL"
+	}
+
+	switch *g {
+	case RfcNone:
+		s = "INVALID"
+	case Rfc4122:
+		s = "RFC 4122"
+	case Rfc9562:
+		s = "RFC 9562"
+	default:
+		s = "UNKNOWN"
+	}
+
+	return
+}

uuidx/types.go

@@ -0,0 +1,5 @@
+package uuidx
+
+type (
+	RfcGen uint8
+)