v1.10.2

FIXED:
* Windows logging needs to import bitmnask

.encoding.TODO/bit/docs.go

@@ -0,0 +1,19 @@
+/*
+Package bit aims to provide feature parity with stdlib's [encoding/hex].
+
+It's a ludicrous tragedy that hex/base16, base32, base64 all have libraries for converting
+to/from string representations... but there's nothing for binary ('01010001' etc.) whatsoever.
+
+This package also provides some extra convenience functions and types in an attempt to provide
+an abstracted bit-level fidelity in Go. A [Bit] is a bool type, in which that underlying bool
+being false represents a 0 and that underlying bool being true represents a 1.
+
+Note that a [Bit] or arbitrary-length or non-octal-aligned [][Bit] may take up more bytes in memory
+than expected; a [Bit] will actually always occupy a single byte -- thus representing
+`00000000 00000000` as a [][Bit] or [16][Bit] will actually occupy *sixteen bytes* in memory,
+NOT 2 bytes (nor, obviously, [2][Byte])!
+It is recommended instead to use a [Bits] instead of a [Bit] slice or array, as it will try to properly align to the
+smallest memory allocation possible (at the cost of a few extra CPU cycles on adding/removing one or more [Bit]).
+It will properly retain any appended, prepended, leading, or trailing bits that do not currently align to a byte.
+*/
+package bit

.encoding.TODO/bit/funcs.go

@@ -0,0 +1,14 @@
+package bit
+
+// TODO: Provide analogues of encoding/hex, encoding/base64, etc. functions etc.
+
+/*
+	TODO: Also provide interfaces for the following:
+
+	* https://pkg.go.dev/encoding#BinaryAppender
+	* https://pkg.go.dev/encoding#BinaryMarshaler
+	* https://pkg.go.dev/encoding#BinaryUnmarshaler
+	* https://pkg.go.dev/encoding#TextAppender
+	* https://pkg.go.dev/encoding#TextMarshaler
+	* https://pkg.go.dev/encoding#TextUnmarshaler
+*/

.encoding.TODO/bit/types.go

@@ -0,0 +1,34 @@
+package bit
+
+type (
+	// Bit aims to provide a native-like type for a single bit (Golang operates on the smallest fidelity level of *byte*/uint8).
+	Bit bool
+
+	// Bits is an arbitrary length of bits.
+	Bits struct {
+		/*
+			leading is a series of Bit that do not cleanly align to the beginning of Bits.b.
+			They will always be the bits at the *beginning* of the sequence.
+			len(Bits.leading) will *never* be more than 7;
+			it's converted into a byte, prepended to Bits.b, and cleared if it reaches that point.
+		*/
+		leading []Bit
+		// b is the condensed/memory-aligned alternative to an [][8]Bit (or []Bit, or [][]Bit, etc.).
+		b []byte
+		/*
+			remaining is a series of Bit that do not cleanly align to the end of Bits.b.
+			They will always be the bits at the *end* of the sequence.
+			len(Bits.remaining) will *never* be more than 7;
+			it's converted into a byte, appended to Bits.b, and cleared if it reaches that point.
+		*/
+		remaining []Bit
+		// fixedLen, if 0, represents a "slice". If >= 1, it represents an "array".
+		fixedLen uint
+	}
+
+	// Byte is this package's representation of a byte. It's primarily for convenience.
+	Byte byte
+
+	// Bytes is defined as a type for convenience single-call functions.
+	Bytes []Byte
+)

bitmask/bitmask.go

@@ -0,0 +1,171 @@
+package bitmask
+
+import (
+	"bytes"
+	"encoding/binary"
+	"errors"
+	"math/bits"
+)
+
+// MaskBit is a flag container.
+type MaskBit uint
+
+/*
+	NewMaskBit is a convenience function.
+	It will return a MaskBit with a (referenced) value of 0, so set your consts up accordingly.
+
+	It is highly recommended to set this default as a "None" flag (separate from your iotas!)
+	as shown in the example.
+*/
+func NewMaskBit() (m *MaskBit) {
+
+	m = new(MaskBit)
+
+	return
+}
+
+// NewMaskBitExplicit is like NewMaskBit, but allows you to specify a non-zero (0x0) value.
+func NewMaskBitExplicit(value uint) (m *MaskBit) {
+
+	var v MaskBit = MaskBit(value)
+
+	m = &v
+
+	return
+}
+
+/*
+	HasFlag is true if m has MaskBit flag set/enabled.
+
+	THIS WILL RETURN FALSE FOR OR'd FLAGS.
+
+	For example:
+
+		flagA MaskBit = 0x01
+		flagB MaskBit = 0x02
+		flagComposite = flagA | flagB
+
+		m *MaskBit = NewMaskBitExplicit(uint(flagA))
+
+	m.HasFlag(flagComposite) will return false even though flagComposite is an OR
+	that contains flagA.
+	Use [MaskBit.IsOneOf] instead if you do not desire this behavior,
+	and instead want to test composite flag *membership*.
+	(MaskBit.IsOneOf will also return true for non-composite equality.)
+
+	To be more clear, if MaskBit flag is a composite MaskBit (e.g. flagComposite above),
+	HasFlag will only return true of ALL bits in flag are also set in MaskBit m.
+*/
+func (m *MaskBit) HasFlag(flag MaskBit) (r bool) {
+
+	var b MaskBit = *m
+
+	if b&flag == flag {
+		r = true
+	}
+	return
+}
+
+/*
+	IsOneOf is like a "looser" form of [MaskBit.HasFlag]
+	in that it allows for testing composite membership.
+
+	See [MaskBit.HasFlag] for more information.
+
+	If composite is *not* an OR'd MaskBit (i.e.
+	it falls directly on a boundary -- 0, 1, 2, 4, 8, 16, etc.),
+	then IsOneOf will behave exactly like HasFlag.
+
+	If m is a composite MaskBit (it usually is) and composite is ALSO a composite MaskBit,
+	IsOneOf will return true if ANY of the flags set in m is set in composite.
+*/
+func (m *MaskBit) IsOneOf(composite MaskBit) (r bool) {
+
+	var b MaskBit = *m
+
+	if b&composite != 0 {
+		r = true
+	}
+	return
+}
+
+// AddFlag adds MaskBit flag to m.
+func (m *MaskBit) AddFlag(flag MaskBit) {
+
+	*m |= flag
+
+	return
+}
+
+// ClearFlag removes MaskBit flag from m.
+func (m *MaskBit) ClearFlag(flag MaskBit) {
+
+	*m &^= flag
+
+	return
+}
+
+// ToggleFlag switches MaskBit flag in m to its inverse; if true, it is now false and vice versa.
+func (m *MaskBit) ToggleFlag(flag MaskBit) {
+
+	*m ^= flag
+
+	return
+}
+
+/*
+	Bytes returns the current value of a MasBit as a byte slice (big-endian).
+
+	If trim is false, b will (probably) be 4 bytes long if you're on a 32-bit size system,
+	and b will (probably) be 8 bytes long if you're on a 64-bit size system. You can determine
+	the size of the resulting slice via (math/)bits.UintSize / 8.
+
+	If trim is true, it will trim leading null bytes (if any). This will lead to an unpredictable
+	byte slice length in b, but is most likely preferred for byte operations.
+
+*/
+func (m *MaskBit) Bytes(trim bool) (b []byte) {
+
+	var b2 []byte
+	var size int = bits.UintSize / 8
+	var err error
+
+	b2 = make([]byte, size)
+
+	switch s := bits.UintSize; s {
+	case 32:
+		binary.BigEndian.PutUint32(b2[:], uint32(*m))
+	case 64:
+		binary.BigEndian.PutUint64(b2[:], uint64(*m))
+	default:
+		err = errors.New("unsupported Uint/system bit size")
+		panic(err)
+	}
+
+	if trim {
+		b = bytes.TrimLeft(b2, "\x00")
+		return
+	} else {
+		b = b2
+		return
+	}
+
+	return
+}
+
+// Copy returns a pointer to a (new) copy of a MaskBit.
+func (m *MaskBit) Copy() (newM *MaskBit) {
+
+	newM = new(MaskBit)
+	*newM = *m
+
+	return
+}
+
+// Value returns the current raw uint value of a MaskBit.
+func (m *MaskBit) Value() (v uint) {
+
+	v = uint(*m)
+
+	return
+}

bitmask/bitmasks.go

@@ -1,46 +0,0 @@
-package bitmask
-
-// MaskBit is a flag container.
-type MaskBit uint8
-
-/*
-	NewMaskBit is a convenience function.
-	It will return a MaskBit with a (referenced) value of 0, so set your consts up accordingly.
-	It is highly recommended to set this default as a "None" flag (separate from your iotas!)
-	as shown in the example.
-*/
-func NewMaskBit() (m *MaskBit) {
-
-	m = new(MaskBit)
-
-	return
-}
-
-// HasFlag is true if m has MaskBit flag set/enabled.
-func (m *MaskBit) HasFlag(flag MaskBit) (r bool) {
-
-	var b MaskBit = *m
-
-	if b&flag != 0 {
-		r = true
-	}
-	return
-}
-
-// AddFlag adds MaskBit flag to m.
-func (m *MaskBit) AddFlag(flag MaskBit) {
-	*m |= flag
-	return
-}
-
-// ClearFlag removes MaskBit flag from m.
-func (m *MaskBit) ClearFlag(flag MaskBit) {
-	*m &= flag
-	return
-}
-
-// ToggleFlag switches MaskBit flag in m to its inverse; if true, it is now false and vice versa.
-func (m *MaskBit) ToggleFlag(flag MaskBit) {
-	*m ^= flag
-	return
-}

bitmask/doc.go

@@ -1,9 +1,35 @@
 /*
 Package bitmask handles a flag-like opt/bitmask system.
 
-See https://yourbasic.org/golang/bitmask-flag-set-clear/ for more information.
+See https://yourbasic.org/golang/bitmask-flag-set-clear/ for basic information on what bitmasks are and why they're useful.
 
-To use this, set constants like thus:
+Specifically, in the case of Go, they allow you to essentially manage many, many, many "booleans" as part of a single value.
+
+A single bool value in Go takes up 8 bits/1 byte, unavoidably.
+
+However, a [bitmask.MaskBit] is backed by a uint which (depending on your platform) is either 32 bits/4 bytes or 64 bits/8 bytes.
+
+"But wait, that takes up more memory though!"
+
+Yep, but bitmasking lets you store a "boolean" AT EACH BIT - it operates on
+whether a bit in a byte/set of bytes at a given position is 0 or 1.
+
+Which means on 32-bit platforms, a [MaskBit] can have up to 4294967295 "booleans" in a single value (0 to (2^32)-1).
+
+On 64-bit platforms, a [MaskBit] can have up to 18446744073709551615 "booleans" in a single value (0 to (2^64)-1).
+
+If you tried to do that with Go bool values, that'd take up 4294967295 bytes (4 GiB)
+or 18446744073709551615 bytes (16 EiB - yes, that's [exbibytes]) of RAM for 32-bit/64-bit platforms respectively.
+
+"But that has to be so slow to unpack that!"
+
+Nope. It's not using compression or anything, the CPU is just comparing bit "A" vs. bit "B" 32/64 times. That's super easy work for a CPU.
+
+There's a reason Doom used bitmasking for the "dmflags" value in its server configs.
+
+# Usage
+
+To use this library, set constants like thus:
 
 	package main
 
@@ -11,18 +37,18 @@ To use this, set constants like thus:
 		"r00t2.io/goutils/bitmask"
 	)
 
-	const OPTNONE types.MaskBit = 0
+	const OPTNONE bitmask.MaskBit = 0
 	const (
-		OPT1 types.MaskBit = 1 << iota
+		OPT1 bitmask.MaskBit = 1 << iota
 		OPT2
 		OPT3
 		// ...
 	)
 
-	var MyMask *MaskBit
+	var MyMask *bitmask.MaskBit
 
 	func main() {
-		MyMask = types.NewMaskBit
+		MyMask = bitmask.NewMaskBit()
 
 		MyMask.AddFlag(OPT1)
 		MyMask.AddFlag(OPT3)
@@ -41,5 +67,96 @@ As would this:
 But this would return false:
 
 	MyMask.HasFlag(OPT2)
+
+# Technical Caveats
+
+TARGETING
+
+When implementing, you should always set MyMask (from Usage section above) as the actual value.
+For example, if you are checking a permissions set for a user that has the value, say, 6
+
+	var userPerms uint = 6 // 0x0000000000000006
+
+and your library has the following permission bits defined:
+
+	const PermsNone bitmask.MaskBit = 0
+	const (
+		PermsList bitmask.MaskBit = 1 << iota // 1
+		PermsRead                             // 2
+		PermsWrite                            // 4
+		PermsExec                             // 8
+		PermsAdmin                            // 16
+	)
+
+And you want to see if the user has the PermsRead flag set, you would do:
+
+	userPermMask = bitmask.NewMaskBitExplicit(userPerms)
+	if userPermMask.HasFlag(PermsRead) {
+		// ...
+	}
+
+NOT:
+
+	userPermMask = bitmask.NewMaskBitExplicit(PermsRead)
+	// Nor:
+	// userPermMask = PermsRead
+	if userPermMask.HasFlag(userPerms) {
+		// ...
+	}
+
+This will be terribly, horribly wrong, cause incredibly unexpected results,
+and quite possibly cause massive security issues. Don't do it.
+
+COMPOSITES
+
+If you want to define a set of flags that are a combination of other flags,
+your inclination would be to bitwise-OR them together:
+
+	const (
+		flagA bitmask.MaskBit = 1 << iota // 1
+		flagB                             // 2
+	)
+
+	const (
+		flagAB bitmask.MaskBit = flagA | flagB // 3
+	)
+
+Which is fine and dandy. But if you then have:
+
+	var myMask *bitmask.MaskBit = bitmask.NewMaskBit()
+
+	myMask.AddFlag(flagA)
+
+You may expect this call to [MaskBit.HasFlag]:
+
+	myMask.HasFlag(flagAB)
+
+to be true, since flagA is "in" flagAB.
+It will return false - HasFlag does strict comparisons.
+It will only return true if you then ALSO do:
+
+	// This would require setting flagA first.
+	// The order of setting flagA/flagB doesn't matter,
+	// but you must have both set for HasFlag(flagAB) to return true.
+	myMask.AddFlag(flagB)
+
+or if you do:
+
+	// This can be done with or without additionally setting flagA.
+	myMask.AddFlag(flagAB)
+
+Instead, if you want to see if a mask has membership within a composite flag,
+you can use [MaskBit.IsOneOf].
+
+# Other Options
+
+If you need something with more flexibility (as always, at the cost of complexity),
+you may be interested in one of the following libraries:
+
+	* [github.com/alvaroloes/enumer]
+	* [github.com/abice/go-enum]
+	* [github.com/jeffreyrichter/enum/enum]
+
+[exbibytes]: https://simple.wikipedia.org/wiki/Exbibyte
 */
 package bitmask

go.mod

@@ -1,10 +1,15 @@
 module r00t2.io/goutils
 
-go 1.16
+go 1.24.5
 
 require (
-	github.com/coreos/go-systemd v0.0.0-20191104093116-d3cd4ed1dbcf
-	github.com/google/uuid v1.3.0
-	golang.org/x/sys v0.0.0-20211216021012-1d35b9e2eb4e
-	r00t2.io/sysutils v1.1.1
+	github.com/coreos/go-systemd/v22 v22.5.0
+	github.com/google/uuid v1.6.0
+	golang.org/x/sys v0.34.0
+	r00t2.io/sysutils v1.14.0
+)
+
+require (
+	github.com/djherbis/times v1.6.0 // indirect
+	golang.org/x/sync v0.16.0 // indirect
 )

go.sum

@@ -1,8 +1,13 @@
-github.com/coreos/go-systemd v0.0.0-20191104093116-d3cd4ed1dbcf h1:iW4rZ826su+pqaw19uhpSCzhj44qo35pNgKFGqzDKkU=
-github.com/coreos/go-systemd v0.0.0-20191104093116-d3cd4ed1dbcf/go.mod h1:F5haX7vjVVG0kc13fIWeqUViNPyEJxv/OmvnBo0Yme4=
-github.com/google/uuid v1.3.0 h1:t6JiXgmwXMjEs8VusXIJk2BXHsn+wx8BZdTaoZ5fu7I=
-github.com/google/uuid v1.3.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
-golang.org/x/sys v0.0.0-20211216021012-1d35b9e2eb4e h1:fLOSk5Q00efkSvAm+4xcoXD+RRmLmmulPn5I3Y9F2EM=
-golang.org/x/sys v0.0.0-20211216021012-1d35b9e2eb4e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-r00t2.io/sysutils v1.1.1 h1:q2P5u50HIIRk6muCPo1Gpapy6sNT4oaB1l2O/C/mi3A=
-r00t2.io/sysutils v1.1.1/go.mod h1:Wlfi1rrJpoKBOjWiYM9rw2FaiZqraD6VpXyiHgoDo/o=
+github.com/coreos/go-systemd/v22 v22.5.0 h1:RrqgGjYQKalulkV8NGVIfkXQf6YYmOyiJKk8iXXhfZs=
+github.com/coreos/go-systemd/v22 v22.5.0/go.mod h1:Y58oyj3AT4RCenI/lSvhwexgC+NSVTIJ3seZv2GcEnc=
+github.com/djherbis/times v1.6.0 h1:w2ctJ92J8fBvWPxugmXIv7Nz7Q3iDMKNx9v5ocVH20c=
+github.com/djherbis/times v1.6.0/go.mod h1:gOHeRAz2h+VJNZ5Gmc/o7iD9k4wW7NMVqieYCY99oc0=
+github.com/godbus/dbus/v5 v5.0.4/go.mod h1:xhWf0FNVPg57R7Z0UbKHbJfkEywrmjJnf7w5xrFpKfA=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+golang.org/x/sync v0.16.0 h1:ycBJEhp9p4vXvUZNszeOq0kGTPghopOL8q0fq3vstxw=
+golang.org/x/sync v0.16.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA=
+golang.org/x/sys v0.0.0-20220615213510-4f61da869c0c/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=
+r00t2.io/sysutils v1.14.0/go.mod h1:ZJ7gZxFVQ7QIokQ5fPZr7wl0XO5Iu+LqtE8j3ciRINw=

iox/docs.go

@@ -0,0 +1,4 @@
+/*
+Package iox includes extensions to the stdlib `io` module.
+*/
+package iox

iox/errs.go

@@ -0,0 +1,9 @@
+package iox
+
+import (
+	`errors`
+)
+
+var (
+	ErrBufTooSmall error = errors.New("buffer too small; buffer size must be > 0")
+)

iox/funcs.go

@@ -0,0 +1,41 @@
+package iox
+
+import (
+	`io`
+)
+
+/*
+CopyBufN is a mix between io.CopyN and io.CopyBuffer.
+
+Despite what the docs may suggest, io.CopyN does NOT *read* n bytes from src AND write n bytes to dst.
+Instead, it always reads 32 KiB from src, and writes n bytes to dst.
+
+There are, of course, cases where this is deadfully undesired.
+
+One can, of course, use io.CopyBuffer, but this is a bit annoying since you then have to provide a buffer yourself.
+
+This convenience-wraps io.CopyBuffer to have a similar signature to io.CopyN but properly uses n for both reading and writing.
+*/
+func CopyBufN(dst io.Writer, src io.Reader, n int64) (written int64, err error) {
+
+	var b []byte
+
+	if n <= 0 {
+		err = ErrBufTooSmall
+		return
+	}
+
+	b = make([]byte, n)
+
+	written, err = io.CopyBuffer(dst, src, b)
+
+	return
+}
+
+// CopyBufWith allows for specifying a buffer allocator function, otherwise acts as CopyBufN.
+func CopyBufWith(dst io.Writer, src io.Reader, bufFunc func() (b []byte)) (written int64, err error) {
+
+	written, err = io.CopyBuffer(dst, src, bufFunc())
+
+	return
+}

iox/types.go

@@ -0,0 +1,8 @@
+package iox
+
+type (
+	// RuneWriter matches the behavior of *(bytes.Buffer).WriteRune and *(bufio.Writer).WriteRune
+	RuneWriter interface {
+		WriteRune(r rune) (n int, err error)
+	}
+)

logging/TODO

@@ -1,9 +1,23 @@
+- macOS support beyond the legacy NIX stuff. it apparently uses something called "ULS", "Unified Logging System".
+-- https://developer.apple.com/documentation/os/logging
+-- https://developer.apple.com/documentation/os/generating-log-messages-from-your-code
+-- no native Go support (yet)?
+--- https://developer.apple.com/forums/thread/773369
+
+- The log destinations for e.g. consts_nix.go et. al. probably should be unexported types.
+
+- add a `log/slog` logging.Logger?
+
 - Implement code line/func/etc. (only for debug?):
   https://stackoverflow.com/a/24809646
   https://golang.org/pkg/runtime/#Caller
   -- log.LlongFile and log.Lshortfile flags don't currently work properly for StdLogger/FileLogger; they refer to the file in logging package rather than the caller.
+  -- ZeroLog seems to be able to do it, take a peek there.
 
-- Suport remote loggers? (eventlog, syslog, systemd)
+- StdLogger2; where stdout and stderr are both logged to depending on severity level.
+  - make configurable via OR bitmask
+
+- Suport remote loggers? (eventlog, syslog, journald)
 
 - JSON logger? YAML logger? XML logger?
 

logging/consts.go

@@ -12,3 +12,16 @@ const (
 	// appendFlags are the flags used for testing the file (and opening/writing).
 	appendFlags int = os.O_APPEND | os.O_CREATE | os.O_WRONLY
 )
+
+const PriorityNone logPrio = 0
+const (
+	PriorityEmergency logPrio = 1 << iota
+	PriorityAlert
+	PriorityCritical
+	PriorityError
+	PriorityWarning
+	PriorityNotice
+	PriorityInformational
+	PriorityDebug
+)
+const PriorityAll logPrio = PriorityEmergency | PriorityAlert | PriorityCritical | PriorityError | PriorityWarning | PriorityNotice | PriorityInformational | PriorityDebug

logging/consts_darwin.go

@@ -0,0 +1,9 @@
+package logging
+
+var (
+	// defLogPaths indicates default log paths.
+	defLogPaths = []string{
+		"/var/log/golang/program.log",
+		"~/Library/Logs/Golang/program.log",
+	}
+)

logging/consts_linux.go

@@ -1,32 +1,5 @@
 package logging
 
-import (
-	`log/syslog`
-
-	`r00t2.io/goutils/bitmask`
-)
-
-const (
-	// devlog is the path to the syslog char device.
-	devlog string = "/dev/log"
-	// syslogFacility is the facility to use; it's a little like a context or scope if you think of it in those terms.
-	syslogFacility syslog.Priority = syslog.LOG_USER
-)
-
-// Flags for logger configuration. These are used internally.
-const (
-	// LogUndefined indicates an undefined Logger type.
-	LogUndefined bitmask.MaskBit = 1 << iota
-	// LogJournald flags a SystemDLogger Logger type.
-	LogJournald
-	// LogSyslog flags a SyslogLogger Logger type.
-	LogSyslog
-	// LogFile flags a FileLogger Logger type.
-	LogFile
-	// LogStdout flags a StdLogger Logger type.
-	LogStdout
-)
-
 var (
 	// defLogPaths indicates default log paths.
 	defLogPaths = []string{

logging/consts_nix.go

@@ -0,0 +1,34 @@
+//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.
+
+package logging
+
+import (
+	"log/syslog"
+
+	"r00t2.io/goutils/bitmask"
+)
+
+const (
+	// devlog is the path to the syslog char device.
+	devlog string = "/dev/log"
+	// syslogFacility is the facility to use; it's a little like a context or scope if you think of it in those terms.
+	syslogFacility syslog.Priority = syslog.LOG_USER
+)
+
+// Flags for logger configuration. These are used internally.
+
+// LogUndefined indicates an undefined Logger type.
+const LogUndefined bitmask.MaskBit = iota
+const (
+	// LogJournald flags a SystemDLogger Logger type. This will, for hopefully obvious reasons, only work on Linux systemd systems.
+	LogJournald bitmask.MaskBit = 1 << iota
+	// LogSyslog flags a SyslogLogger Logger type.
+	LogSyslog
+	// LogFile flags a FileLogger Logger type.
+	LogFile
+	// LogStdout flags a StdLogger Logger type.
+	LogStdout
+)

logging/consts_windows.go

@@ -8,11 +8,11 @@ import (
 )
 
 // Flags for logger configuration. These are used internally.
+// LogUndefined indicates an undefined Logger type.
+const LogUndefined bitmask.MaskBit = 0
 const (
-	// LogUndefined indicates an undefined Logger type.
-	LogUndefined bitmask.MaskBit = 1 << iota
 	// LogWinLogger indicates a WinLogger Logger type (Event Log).
-	LogWinLogger
+	LogWinLogger bitmask.MaskBit = 1 << iota
 	// LogFile flags a FileLogger Logger type.
 	LogFile
 	// LogStdout flags a StdLogger Logger type.

logging/doc.go

@@ -3,18 +3,22 @@ Package logging implements and presents various loggers under a unified interfac
 
 These particular loggers (logging.Logger) available are:
 
-		StdLogger
-		FileLogger
-		SystemDLogger (Linux only)
-		SyslogLogger (Linux only)
-		WinLogger (Windows only)
+	NullLogger
+	StdLogger
+	FileLogger
+	SystemDLogger (Linux only)
+	SyslogLogger (Linux/macOS/other *NIX-like only)
+	WinLogger (Windows only)
 
-There is a sixth type of logging.Logger, MultiLogger, that allows for multiple loggers to be written to with a single call.
+There is a seventh type of logging.Logger, MultiLogger, that allows for multiple loggers to be written to with a single call.
+(This is similar to stdlib's io.MultiWriter()'s return value, but with priority awareness and fmt string support).
 
-Note that for some Loggers, the prefix may be modified - "literal" loggers (StdLogger and FileLogger) will append a space to the end of the prefix.
+As you may have guessed, NullLogger doesn't actually log anything but is fully "functional" as a logging.Logger (similar to io.discard/io.Discard()'s return).
+
+Note that for some Loggers, the prefix may be modified after the Logger has already initialized.
+"Literal" loggers (StdLogger and FileLogger) will append a space to the end of the prefix by default.
 If this is undesired (unlikely), you will need to modify (Logger).Prefix and run (Logger).Logger.SetPrefix(yourPrefixHere) for the respective logger.
 
-
 Every logging.Logger type has the following methods that correspond to certain "levels".
 
 	Alert(s string, v ...interface{}) (err error)
@@ -36,6 +40,7 @@ Note that in the case of a MultiLogger, err (if not nil) will be a (r00t2.io/gou
 logging.Logger types also have the following methods:
 
 	DoDebug(d bool) (err error)
+	GetDebug() (d bool)
 	SetPrefix(p string) (err error)
 	GetPrefix() (p string, err error)
 	Setup() (err error)
@@ -43,5 +48,17 @@ logging.Logger types also have the following methods:
 
 In some cases, Logger.Setup and Logger.Shutdown are no-ops. In other cases, they perform necessary initialization/cleanup and closing of the logger.
 It is recommended to *always* run Setup and Shutdown before and after using, respectively, regardless of the actual logging.Logger type.
+
+Lastly, all logging.Loggers have a ToLogger() method. This returns a *log.Logger (from stdlib log), which also conforms to io.Writer inherently.
+In addition. all have a ToRaw() method, which extends a Logger even further and returns an unexported type (*logging.logWriter) compatible with:
+
+  - io.ByteWriter
+  - io.Writer
+  - io.WriteCloser (Shutdown() on the Logger backend is called during Close(), rendering the underlying Logger unsafe to use afterwards)
+  - io.StringWriter
+
+and, if stdlib io ever defines an e.g. RuneWriter (WriteRune(r rune) (n int, err error)), it will conform to that too (see (r00t2.io/goutils/iox).RuneWriter).
+Obviously this and io.ByteWriter are fairly silly, as they're intended to be high-speed throughput-optimized methods, but if you wanted to e.g.
+log every single byte on a wire as a separate log message, go ahead; I'm not your dad.
 */
 package logging

logging/errs.go

@@ -1,7 +1,7 @@
 package logging
 
 import (
-	`errors`
+	"errors"
 )
 
 var (
@@ -12,6 +12,8 @@ var (
 		exists with too restrictive perms to write/append to, and/or could not be created.
 	*/
 	ErrInvalidFile error = errors.New("a FileLogger was requested but the file does not exist and cannot be created")
+	// ErrInvalidRune is returned if a rune was expected but it is not a valid UTF-8 codepoint.
+	ErrInvalidRune error = errors.New("specified rune is not valid UTF-8 codepoint")
 	// ErrNoEntry indicates that the user attempted to MultiLogger.RemoveLogger a Logger but one by that identifier does not exist.
 	ErrNoEntry error = errors.New("the Logger specified to be removed does not exist")
 )

logging/errs_linux.go

@@ -1,18 +1,10 @@
 package logging
 
 import (
-	`errors`
-	`fmt`
+	"errors"
 )
 
 var (
 	// ErrNoSysD indicates that the user attempted to add a SystemDLogger to a MultiLogger but systemd is unavailable.
 	ErrNoSysD error = errors.New("a systemd (journald) Logger was requested but systemd is unavailable on this system")
-	// ErrNoSyslog indicates that the user attempted to add a SyslogLogger to a MultiLogger but syslog's logger device is unavailable.
-	ErrNoSyslog error = errors.New("a Syslog Logger was requested but Syslog is unavailable on this system")
-	/*
-		ErrInvalidDevLog indicates that the user attempted to add a SyslogLogger to a MultiLogger but
-		the Syslog char device file is... not actually a char device file.
-	*/
-	ErrInvalidDevLog error = errors.New(fmt.Sprintf("a Syslog Logger was requested but %v is not a valid logger handle", devlog))
 )

logging/errs_nix.go

@@ -0,0 +1,19 @@
+//go:build !(windows || plan9 || wasip1 || js || ios)
+// +build !windows,!plan9,!wasip1,!js,!ios
+
+package logging
+
+import (
+	"errors"
+	"fmt"
+)
+
+var (
+	// ErrNoSyslog indicates that the user attempted to add a SyslogLogger to a MultiLogger but syslog's logger device is unavailable.
+	ErrNoSyslog error = errors.New("a Syslog Logger was requested but Syslog is unavailable on this system")
+	/*
+		ErrInvalidDevLog indicates that the user attempted to add a SyslogLogger to a MultiLogger but
+		the Syslog char device file is... not actually a char device file.
+	*/
+	ErrInvalidDevLog error = errors.New(fmt.Sprintf("a Syslog Logger was requested but %v is not a valid logger handle", devlog))
+)

logging/funcs.go

@@ -1,9 +1,33 @@
 package logging
 
 import (
+	"log"
 	"os"
 )
 
+/*
+ToLog returns a stdlib *log.Logger from a logging.Logger. It simply wraps the (logging.Logger).ToLogger() methods.
+
+prio is an OR'd logPrio of the Priority* constants.
+*/
+func ToLog(l Logger, prio logPrio) (stdLibLog *log.Logger) {
+
+	stdLibLog = l.ToLogger(prio)
+
+	return
+}
+
+// ToRaw returns a *logWriter from a logging.Logger. It is an alternative to the (logging.Logger).ToRaw() methods.
+func ToRaw(l Logger, prio logPrio) (raw *logWriter) {
+
+	raw = &logWriter{
+		backend: l,
+		prio:    prio,
+	}
+
+	return
+}
+
 // testOpen attempts to open a file for writing to test for suitability as a LogFile path.
 func testOpen(path string) (success bool, err error) {
 

logging/funcs_file.go

@@ -1,12 +1,12 @@
 package logging
 
 import (
-	`errors`
+	"errors"
 	"fmt"
-	`io/fs`
+	"io/fs"
 	"log"
 	"os"
-	`strings`
+	"strings"
 )
 
 // Setup sets up/configures a FileLogger and prepares it for use.
@@ -43,8 +43,8 @@ func (l *FileLogger) Shutdown() (err error) {
 }
 
 /*
-	GetPrefix returns the prefix used by this FileLogger.
-	err will always be nil; it's there for interface-compat.
+GetPrefix returns the prefix used by this FileLogger.
+err will always be nil; it's there for interface-compat.
 */
 func (l *FileLogger) GetPrefix() (prefix string, err error) {
 
@@ -54,9 +54,9 @@ func (l *FileLogger) GetPrefix() (prefix string, err error) {
 }
 
 /*
-	DoDebug sets the debug state of this FileLogger.
-	Note that this merely acts as a *safety filter* for debug messages to avoid sensitive information being written to the log.
-	err will always be nil; it's there for interface-compat.
+DoDebug sets the debug state of this FileLogger.
+Note that this merely acts as a *safety filter* for debug messages to avoid sensitive information being written to the log.
+err will always be nil; it's there for interface-compat.
 */
 func (l *FileLogger) DoDebug(d bool) (err error) {
 
@@ -65,9 +65,17 @@ func (l *FileLogger) DoDebug(d bool) (err error) {
 	return
 }
 
+// GetDebug returns the debug status of this FileLogger.
+func (l *FileLogger) GetDebug() (d bool) {
+
+	d = l.EnableDebug
+
+	return
+}
+
 /*
-	SetPrefix sets the prefix for this FileLogger.
-	err will always be nil; it's there for interface-compat.
+SetPrefix sets the prefix for this FileLogger.
+err will always be nil; it's there for interface-compat.
 */
 func (l *FileLogger) SetPrefix(prefix string) (err error) {
 
@@ -212,6 +220,22 @@ func (l *FileLogger) Warning(s string, v ...interface{}) (err error) {
 	return
 }
 
+// ToLogger returns a stdlib log.Logger.
+func (l *FileLogger) ToLogger(prio logPrio) (stdLibLog *log.Logger) {
+
+	stdLibLog = log.New(l.ToRaw(prio), "", 0)
+
+	return
+}
+
+// ToRaw returns a *logWriter.
+func (l *FileLogger) ToRaw(prio logPrio) (raw *logWriter) {
+
+	raw = &logWriter{backend: l, prio: prio}
+
+	return
+}
+
 // renderWrite prepares/formats a log message to be written to this FileLogger.
 func (l *FileLogger) renderWrite(msg, prio string) {
 

logging/funcs_linux.go

@@ -5,7 +5,7 @@ import (
 	`os`
 	`path`
 
-	sysd `github.com/coreos/go-systemd/journal`
+	sysd `github.com/coreos/go-systemd/v22/journal`
 	`r00t2.io/goutils/bitmask`
 	`r00t2.io/sysutils/paths`
 )

logging/funcs_logprio.go

@@ -0,0 +1,25 @@
+package logging
+
+import (
+	`r00t2.io/goutils/bitmask`
+)
+
+// HasFlag provides a wrapper for functionality to the underlying bitmask.MaskBit.
+func (l *logPrio) HasFlag(prio logPrio) (hasFlag bool) {
+
+	var m *bitmask.MaskBit
+	var p *bitmask.MaskBit
+
+	if l == nil {
+		return
+	}
+
+	m = bitmask.NewMaskBitExplicit(uint(*l))
+	p = bitmask.NewMaskBitExplicit(uint(prio))
+
+	// Use IsOneOf instead in case PriorityAll is passed for prio.
+	// hasFlag = m.HasFlag(*p)
+	hasFlag = m.IsOneOf(*p)
+
+	return
+}

logging/funcs_logwriter.go

@@ -0,0 +1,211 @@
+package logging
+
+import (
+	"unicode/utf8"
+
+	"r00t2.io/goutils/multierr"
+)
+
+/*
+Close calls Logger.Shutdown() on the underlying Logger.
+The Logger *must not be used* after this; it will need to be re-initialized with Logger.Setup()
+or a new Logger (and thuse new logWriter) must be created to replace it.
+
+It (along with logWriter.Write()) conforms to WriteCloser().
+*/
+func (l *logWriter) Close() (err error) {
+
+	if err = l.backend.Shutdown(); err != nil {
+		return
+	}
+
+	return
+}
+
+/*
+Write writes bytes b to the underlying Logger's priority level if the logWriter's priority level(s) match.
+It conforms to io.Writer. n will *always* == len(b) on success, because otherwise n would technically be >= len(b)
+(if multiple priorities are enabled), which is undefined behavior per io.Writer.
+
+b is converted to a string to normalize to the underlying Logger.
+*/
+func (l *logWriter) Write(b []byte) (n int, err error) {
+
+	var s string
+	var mErr *multierr.MultiError = multierr.NewMultiError(nil)
+
+	if b == nil {
+		return
+	}
+
+	s = string(b)
+
+	// Since this explicitly checks each priority level, there's no need for IsOneOf in case of PriorityAll.
+
+	if l.prio.HasFlag(PriorityEmergency) {
+		if err = l.backend.Emerg(s); err != nil {
+			mErr.AddError(err)
+			err = nil
+		}
+	}
+	if l.prio.HasFlag(PriorityAlert) {
+		if err = l.backend.Alert(s); err != nil {
+			mErr.AddError(err)
+			err = nil
+		}
+	}
+	if l.prio.HasFlag(PriorityCritical) {
+		if err = l.backend.Crit(s); err != nil {
+			mErr.AddError(err)
+			err = nil
+		}
+	}
+	if l.prio.HasFlag(PriorityError) {
+		if err = l.backend.Err(s); err != nil {
+			mErr.AddError(err)
+			err = nil
+		}
+	}
+	if l.prio.HasFlag(PriorityWarning) {
+		if err = l.backend.Warning(s); err != nil {
+			mErr.AddError(err)
+			err = nil
+		}
+	}
+	if l.prio.HasFlag(PriorityNotice) {
+		if err = l.backend.Notice(s); err != nil {
+			mErr.AddError(err)
+			err = nil
+		}
+	}
+	if l.prio.HasFlag(PriorityInformational) {
+		if err = l.backend.Info(s); err != nil {
+			mErr.AddError(err)
+			err = nil
+		}
+	}
+	if l.prio.HasFlag(PriorityDebug) {
+		if err = l.backend.Debug(s); err != nil {
+			mErr.AddError(err)
+			err = nil
+		}
+	}
+
+	if !mErr.IsEmpty() {
+		err = mErr
+		return
+	}
+
+	n = len(b)
+
+	return
+}
+
+/*
+WriteByte conforms a logWriter to an io.ByteWriter. (It just wraps logWriter.Write().)
+You should probably never use this; the logging overhead/prefix is going to be more data than the single byte itself.
+
+c is converted to a string to normalize to the underlying Logger.
+*/
+func (l *logWriter) WriteByte(c byte) (err error) {
+
+	if _, err = l.Write([]byte{c}); err != nil {
+		return
+	}
+
+	return
+}
+
+/*
+WriteRune follows the same signature of (bytes.Buffer).WriteRune() and (bufio.Writer).WriteRune(); thus if `io` ever defines an io.RuneWriter interface, here ya go.
+
+n will *always* be equal to (unicode/utf8).RuneLen(r), unless r is an "invalid rune" -- in which case n will be 0 and err will be ErrInvalidRune..
+*/
+func (l *logWriter) WriteRune(r rune) (n int, err error) {
+
+	var b []byte
+
+	n = utf8.RuneLen(r)
+	if n < 0 {
+		err = ErrInvalidRune
+		n = 0
+		return
+	}
+
+	b = make([]byte, n)
+	utf8.EncodeRune(b, r)
+
+	if n, err = l.Write(b); err != nil {
+		return
+	}
+
+	return
+}
+
+/*
+WriteString writes string s to the underlying Logger's priority level if the logWriter's priority level(s) match.
+It conforms to io.StringWriter. n will *always* == len(s) on success, because otherwise n would technically be >= len(s)
+(if multiple priorities are enabled), which is undefined behavior per io.StringWriter.
+*/
+func (l *logWriter) WriteString(s string) (n int, err error) {
+
+	var mErr *multierr.MultiError = multierr.NewMultiError(nil)
+
+	if l.prio.HasFlag(PriorityEmergency) {
+		if err = l.backend.Emerg(s); err != nil {
+			mErr.AddError(err)
+			err = nil
+		}
+	}
+	if l.prio.HasFlag(PriorityAlert) {
+		if err = l.backend.Alert(s); err != nil {
+			mErr.AddError(err)
+			err = nil
+		}
+	}
+	if l.prio.HasFlag(PriorityCritical) {
+		if err = l.backend.Crit(s); err != nil {
+			mErr.AddError(err)
+			err = nil
+		}
+	}
+	if l.prio.HasFlag(PriorityError) {
+		if err = l.backend.Err(s); err != nil {
+			mErr.AddError(err)
+			err = nil
+		}
+	}
+	if l.prio.HasFlag(PriorityWarning) {
+		if err = l.backend.Warning(s); err != nil {
+			mErr.AddError(err)
+			err = nil
+		}
+	}
+	if l.prio.HasFlag(PriorityNotice) {
+		if err = l.backend.Notice(s); err != nil {
+			mErr.AddError(err)
+			err = nil
+		}
+	}
+	if l.prio.HasFlag(PriorityInformational) {
+		if err = l.backend.Info(s); err != nil {
+			mErr.AddError(err)
+			err = nil
+		}
+	}
+	if l.prio.HasFlag(PriorityDebug) {
+		if err = l.backend.Debug(s); err != nil {
+			mErr.AddError(err)
+			err = nil
+		}
+	}
+
+	if !mErr.IsEmpty() {
+		err = mErr
+		return
+	}
+
+	n = len(s)
+
+	return
+}

logging/funcs_multilogger.go

@@ -1,11 +1,12 @@
 package logging
 
 import (
-	`errors`
-	`fmt`
-	`sync`
+	"errors"
+	"fmt"
+	"log"
+	"sync"
 
-	`r00t2.io/goutils/multierr`
+	"r00t2.io/goutils/multierr"
 )
 
 // Setup sets up/configures a MultiLogger (and all its MultiLogger.Loggers) and prepares it for use.
@@ -67,8 +68,8 @@ func (m *MultiLogger) Shutdown() (err error) {
 }
 
 /*
-	GetPrefix returns the prefix used by this MultiLogger (and all its MultiLogger.Loggers).
-	err will always be nil; it's there for interface-compat.
+GetPrefix returns the prefix used by this MultiLogger (and all its MultiLogger.Loggers).
+err will always be nil; it's there for interface-compat.
 */
 func (m *MultiLogger) GetPrefix() (prefix string, err error) {
 
@@ -79,10 +80,10 @@ func (m *MultiLogger) GetPrefix() (prefix string, err error) {
 }
 
 /*
-	DoDebug sets the debug state of this MultiLogger (and all its MultiLogger.Loggers).
-	Note that this merely acts as a *safety filter* for debug messages to avoid sensitive information being written to the log.
+DoDebug sets the debug state of this MultiLogger (and all its MultiLogger.Loggers).
+Note that this merely acts as a *safety filter* for debug messages to avoid sensitive information being written to the log.
 
-	If you had a logger-specific EnableDebug set, you will need to re-set it to your desired state after running this method.
+If you had a logger-specific EnableDebug set, you will need to re-set it to your desired state after running this method.
 */
 func (m *MultiLogger) DoDebug(d bool) (err error) {
 
@@ -114,10 +115,18 @@ func (m *MultiLogger) DoDebug(d bool) (err error) {
 	return
 }
 
-/*
-	SetPrefix sets the prefix for this MultiLogger (and all its MultiLogger.Loggers).
+// GetDebug returns the debug status of this MultiLogger.
+func (m *MultiLogger) GetDebug() (d bool) {
 
-	If you had a logger-specific Prefix set, you will need to re-set it to your desired prefix after running this method.
+	d = m.EnableDebug
+
+	return
+}
+
+/*
+SetPrefix sets the prefix for this MultiLogger (and all its MultiLogger.Loggers).
+
+If you had a logger-specific Prefix set, you will need to re-set it to your desired prefix after running this method.
 */
 func (m *MultiLogger) SetPrefix(prefix string) (err error) {
 
@@ -362,3 +371,19 @@ func (m *MultiLogger) Warning(s string, v ...interface{}) (err error) {
 
 	return
 }
+
+// ToLogger returns a stdlib log.Logger.
+func (m *MultiLogger) ToLogger(prio logPrio) (stdLibLog *log.Logger) {
+
+	stdLibLog = log.New(m.ToRaw(prio), "", 0)
+
+	return
+}
+
+// ToRaw returns a *logWriter.
+func (m *MultiLogger) ToRaw(prio logPrio) (raw *logWriter) {
+
+	raw = &logWriter{backend: m, prio: prio}
+
+	return
+}

logging/funcs_multilogger_mgr.go

@@ -1,10 +1,10 @@
 package logging
 
 import (
-	`path`
+	"path"
 
-	`github.com/google/uuid`
-	`r00t2.io/sysutils/paths`
+	"github.com/google/uuid"
+	"r00t2.io/sysutils/paths"
 )
 
 /*
@@ -145,6 +145,40 @@ func (m *MultiLogger) AddFileLogger(identifier string, logFlags int, logfilePath
 	return
 }
 
+/*
+	AddNullLogger adds a NullLogger to a MultiLogger.
+
+	identifier is a string to use to identify the added NullLogger in MultiLogger.Loggers.
+	If empty, one will be automatically generated.
+*/
+func (m *MultiLogger) AddNullLogger(identifier string) (err error) {
+
+	var exists bool
+	var prefix string
+
+	if identifier == "" {
+		identifier = uuid.New().String()
+	}
+
+	if _, exists = m.Loggers[identifier]; exists {
+		err = ErrExistingLogger
+		return
+	}
+
+	m.Loggers[identifier] = &NullLogger{}
+	if err = m.Loggers[identifier].Setup(); err != nil {
+		return
+	}
+
+	if prefix, err = m.Loggers[identifier].GetPrefix(); err != nil {
+		return
+	}
+
+	m.Loggers[identifier].Debug("logger initialized of type %T with prefix %v", m.Loggers[identifier], prefix)
+
+	return
+}
+
 // RemoveLogger will let you remove a Logger from MultiLogger.Loggers.
 func (m *MultiLogger) RemoveLogger(identifier string) (err error) {
 

logging/funcs_multilogger_mgr_linux.go

@@ -1,20 +1,17 @@
 package logging
 
 import (
-	`os`
-
-	sysd `github.com/coreos/go-systemd/journal`
-	`github.com/google/uuid`
-	`r00t2.io/sysutils/paths`
+	sysd "github.com/coreos/go-systemd/v22/journal"
+	"github.com/google/uuid"
 )
 
 /*
-	AddDefaultLogger adds a default Logger (as would be determined by GetLogger) to a MultiLogger.
+AddDefaultLogger adds a default Logger (as would be determined by GetLogger) to a MultiLogger.
 
-	identifier is a string to use to identify the added Logger in MultiLogger.Loggers.
-	If empty, one will be automatically generated.
+identifier is a string to use to identify the added Logger in MultiLogger.Loggers.
+If empty, one will be automatically generated.
 
-	See the documentation for GetLogger for details on other arguments.
+See the documentation for GetLogger for details on other arguments.
 */
 func (m *MultiLogger) AddDefaultLogger(identifier string, logFlags int, logPaths ...string) (err error) {
 
@@ -40,10 +37,10 @@ func (m *MultiLogger) AddDefaultLogger(identifier string, logFlags int, logPaths
 }
 
 /*
-	AddSysdLogger adds a SystemDLogger to a MultiLogger.
+AddSysdLogger adds a SystemDLogger to a MultiLogger.
 
-	identifier is a string to use to identify the added SystemDLogger in MultiLogger.Loggers.
-	If empty, one will be automatically generated.
+identifier is a string to use to identify the added SystemDLogger in MultiLogger.Loggers.
+If empty, one will be automatically generated.
 */
 func (m *MultiLogger) AddSysdLogger(identifier string) (err error) {
 
@@ -80,55 +77,3 @@ func (m *MultiLogger) AddSysdLogger(identifier string) (err error) {
 
 	return
 }
-
-/*
-	AddSyslogLogger adds a SyslogLogger to a MultiLogger.
-
-	identifier is a string to use to identify the added SyslogLogger in MultiLogger.Loggers.
-	If empty, one will be automatically generated.
-*/
-func (m *MultiLogger) AddSyslogLogger(identifier string) (err error) {
-
-	var exists bool
-	var hasSyslog bool
-	var stat os.FileInfo
-	var devlogPath string = devlog
-	var prefix string
-
-	if identifier == "" {
-		identifier = uuid.New().String()
-	}
-
-	if _, exists = m.Loggers[identifier]; exists {
-		err = ErrExistingLogger
-		return
-	}
-
-	if hasSyslog, stat, err = paths.RealPathExistsStat(&devlogPath); hasSyslog && err != nil {
-		return
-	} else if !hasSyslog {
-		err = ErrNoSyslog
-		return
-	}
-
-	if stat.Mode().IsRegular() {
-		err = ErrInvalidDevLog
-		return
-	}
-
-	m.Loggers[identifier] = &SyslogLogger{
-		EnableDebug: m.EnableDebug,
-		Prefix:      m.Prefix,
-	}
-	if err = m.Loggers[identifier].Setup(); err != nil {
-		return
-	}
-
-	if prefix, err = m.Loggers[identifier].GetPrefix(); err != nil {
-		return
-	}
-
-	m.Loggers[identifier].Debug("logger initialized of type %T with prefix %v", m.Loggers[identifier], prefix)
-
-	return
-}

logging/funcs_multilogger_mgr_nix.go

@@ -0,0 +1,63 @@
+//go:build !(windows || plan9 || wasip1 || js || ios)
+// +build !windows,!plan9,!wasip1,!js,!ios
+
+package logging
+
+import (
+	"os"
+
+	"github.com/google/uuid"
+	"r00t2.io/sysutils/paths"
+)
+
+/*
+AddSyslogLogger adds a SyslogLogger to a MultiLogger.
+
+identifier is a string to use to identify the added SyslogLogger in MultiLogger.Loggers.
+If empty, one will be automatically generated.
+*/
+func (m *MultiLogger) AddSyslogLogger(identifier string) (err error) {
+
+	var exists bool
+	var hasSyslog bool
+	var stat os.FileInfo
+	var devlogPath string = devlog
+	var prefix string
+
+	if identifier == "" {
+		identifier = uuid.New().String()
+	}
+
+	if _, exists = m.Loggers[identifier]; exists {
+		err = ErrExistingLogger
+		return
+	}
+
+	if hasSyslog, stat, err = paths.RealPathExistsStat(&devlogPath); hasSyslog && err != nil {
+		return
+	} else if !hasSyslog {
+		err = ErrNoSyslog
+		return
+	}
+
+	if stat.Mode().IsRegular() {
+		err = ErrInvalidDevLog
+		return
+	}
+
+	m.Loggers[identifier] = &SyslogLogger{
+		EnableDebug: m.EnableDebug,
+		Prefix:      m.Prefix,
+	}
+	if err = m.Loggers[identifier].Setup(); err != nil {
+		return
+	}
+
+	if prefix, err = m.Loggers[identifier].GetPrefix(); err != nil {
+		return
+	}
+
+	m.Loggers[identifier].Debug("logger initialized of type %T with prefix %v", m.Loggers[identifier], prefix)
+
+	return
+}

logging/funcs_multilogger_mgr_oldnix.go

@@ -0,0 +1,41 @@
+//go:build !(windows || plan9 || wasip1 || js || ios || linux)
+// +build !windows,!plan9,!wasip1,!js,!ios,!linux
+
+// Linux is excluded because it has its own.
+
+package logging
+
+import (
+	"github.com/google/uuid"
+)
+
+/*
+AddDefaultLogger adds a default Logger (as would be determined by GetLogger) to a MultiLogger.
+
+identifier is a string to use to identify the added Logger in MultiLogger.Loggers.
+If empty, one will be automatically generated.
+
+See the documentation for GetLogger for details on other arguments.
+*/
+func (m *MultiLogger) AddDefaultLogger(identifier string, logFlags int, logPaths ...string) (err error) {
+
+	var l Logger
+	var exists bool
+
+	if identifier == "" {
+		identifier = uuid.New().String()
+	}
+
+	if _, exists = m.Loggers[identifier]; exists {
+		err = ErrExistingLogger
+		return
+	}
+
+	if l, err = GetLogger(m.EnableDebug, m.Prefix, logFlags, logPaths...); err != nil {
+		return
+	}
+
+	m.Loggers[identifier] = l
+
+	return
+}

logging/funcs_nulllogger.go

@@ -0,0 +1,94 @@
+package logging
+
+import (
+	"log"
+)
+
+// Setup does nothing at all; it's here for interface compat. 🙃
+func (l *NullLogger) Setup() (err error) {
+	return
+}
+
+// DoDebug does nothing at all; it's here for interface compat. 🙃
+func (l *NullLogger) DoDebug(d bool) (err error) {
+	return
+}
+
+// GetDebug returns the debug status of this NullLogger. It will always return true. 🙃
+func (n *NullLogger) GetDebug() (d bool) {
+
+	d = true
+
+	return
+}
+
+// SetPrefix does nothing at all; it's here for interface compat. 🙃
+func (l *NullLogger) SetPrefix(p string) (err error) {
+	return
+}
+
+// GetPrefix does nothing at all; it's here for interface compat. 🙃
+func (l *NullLogger) GetPrefix() (p string, err error) {
+	return
+}
+
+// Shutdown does nothing at all; it's here for interface compat. 🙃
+func (l *NullLogger) Shutdown() (err error) {
+	return
+}
+
+// Alert does nothing at all; it's here for interface compat. 🙃
+func (l *NullLogger) Alert(s string, v ...interface{}) (err error) {
+	return
+}
+
+// Crit does nothing at all; it's here for interface compat. 🙃
+func (l *NullLogger) Crit(s string, v ...interface{}) (err error) {
+	return
+}
+
+// Debug does nothing at all; it's here for interface compat. 🙃
+func (l *NullLogger) Debug(s string, v ...interface{}) (err error) {
+	return
+}
+
+// Emerg does nothing at all; it's here for interface compat. 🙃
+func (l *NullLogger) Emerg(s string, v ...interface{}) (err error) {
+	return
+}
+
+// Err does nothing at all; it's here for interface compat. 🙃
+func (l *NullLogger) Err(s string, v ...interface{}) (err error) {
+	return
+}
+
+// Info does nothing at all; it's here for interface compat. 🙃
+func (l *NullLogger) Info(s string, v ...interface{}) (err error) {
+	return
+}
+
+// Notice does nothing at all; it's here for interface compat. 🙃
+func (l *NullLogger) Notice(s string, v ...interface{}) (err error) {
+	return
+}
+
+// Warning does nothing at all; it's here for interface compat. 🙃
+func (l *NullLogger) Warning(s string, v ...interface{}) (err error) {
+	return
+}
+
+// ToLogger returns a stdlib log.Logger (that doesn't actually write to anything).
+func (l *NullLogger) ToLogger(prio logPrio) (stdLibLog *log.Logger) {
+
+	stdLibLog = log.New(&nullWriter{}, "", 0)
+
+	return
+}
+
+// ToRaw returns a *logWriter. (This is a little less efficient than using ToLogger's log.Logger as an io.Writer if that's all you need.)
+func (l *NullLogger) ToRaw(prio logPrio) (raw *logWriter) {
+
+	raw = &logWriter{backend: l, prio: prio}
+
+	return
+}

logging/funcs_nullwriter.go

@@ -0,0 +1,58 @@
+package logging
+
+import (
+	"unicode/utf8"
+)
+
+// Close conforms a nullWriter to an io.WriteCloser. It obviously does nothing, and will always return with err == nil.
+func (nw *nullWriter) Close() (err error) {
+
+	// NO-OP
+
+	return
+}
+
+// Write conforms a nullWriter to an io.Writer, but it writes... nothing. To avoid errors, however, in downstream code it pretends it does (n will *always* == len(b)).
+func (nw *nullWriter) Write(b []byte) (n int, err error) {
+
+	if b == nil {
+		return
+	}
+	n = len(b)
+
+	return
+}
+
+// WriteByte conforms to an io.ByteWriter but again... nothing is actually written anywhere.
+func (nw *nullWriter) WriteByte(c byte) (err error) {
+
+	// NO-OP
+
+	_ = c
+
+	return
+}
+
+/*
+WriteRune conforms to the other Loggers. It WILL return the proper value for n (matching (bytes.Buffer).WriteRune() and (bufio.Writer).WriteRune() signatures,
+and it WILL return an ErrInvalidRune if r is not a valid rune, but otherwise it will no-op.
+*/
+func (nw *nullWriter) WriteRune(r rune) (n int, err error) {
+
+	n = utf8.RuneLen(r)
+	if n < 0 {
+		err = ErrInvalidRune
+		n = 0
+		return
+	}
+
+	return
+}
+
+// WriteString conforms to an io.StringWriter but nothing is actually written. (n will *always* == len(s))
+func (nw *nullWriter) WriteString(s string) (n int, err error) {
+
+	n = len(s)
+
+	return
+}

logging/funcs_oldnix.go

@@ -0,0 +1,138 @@
+//go:build !(windows || plan9 || wasip1 || js || ios || linux)
+// +build !windows,!plan9,!wasip1,!js,!ios,!linux
+
+// Linux is excluded because it has its own.
+
+package logging
+
+import (
+	native "log"
+	"os"
+	"path"
+
+	"r00t2.io/goutils/bitmask"
+	"r00t2.io/sysutils/paths"
+)
+
+var (
+	_ = native.Logger{}
+	_ = os.Interrupt
+)
+
+/*
+GetLogger returns an instance of Logger that best suits your system's capabilities.
+
+If enableDebug is true, debug messages (which according to your program may or may not contain sensitive data) are rendered and written.
+
+If prefix is "\x00" (a null byte), then the default logging prefix will be used. If anything else, even an empty string,
+is specified then that will be used instead for the prefix.
+
+logConfigFlags is the corresponding flag(s) OR'd for StdLogger.LogFlags / FileLogger.StdLogger.LogFlags if either is selected. See StdLogger.LogFlags and
+https://pkg.go.dev/log#pkg-constants for details.
+
+logPaths is an (optional) list of strings to use as paths to test for writing. If the file can be created/written to,
+it will be used (assuming you have no higher-level loggers available). Only the first logPaths entry that "works" will be used, later entries will be ignored.
+If you want to log to multiple files simultaneously, use a MultiLogger instead.
+
+If you call GetLogger, you will only get a single ("best") logger your system supports.
+If you want to log to multiple Logger destinations at once (or want to log to an explicit Logger type),
+use GetMultiLogger.
+*/
+func GetLogger(enableDebug bool, prefix string, logConfigFlags int, logPaths ...string) (logger Logger, err error) {
+
+	var logPath string
+	var logFlags bitmask.MaskBit
+	var currentPrefix string
+
+	// Configure system-supported logger(s).
+
+	// If we can detect syslog, use that. If not, try to use a file logger (+ stdout).
+	// Last ditch, stdout.
+	var hasSyslog bool
+	var stat os.FileInfo
+	var devlogPath string = devlog
+
+	if hasSyslog, stat, err = paths.RealPathExistsStat(&devlogPath); hasSyslog && err != nil {
+		return
+	}
+
+	if hasSyslog && !stat.Mode().IsRegular() {
+		logFlags.AddFlag(LogSyslog)
+	} else {
+		var exists bool
+		var success bool
+		var ckLogPaths []string
+
+		logFlags.AddFlag(LogStdout)
+		ckLogPaths = defLogPaths
+		if logPaths != nil {
+			ckLogPaths = logPaths
+		}
+		for _, p := range ckLogPaths {
+			if exists, _ = paths.RealPathExists(&p); exists {
+				if success, err = testOpen(p); err != nil {
+					continue
+				} else if !success {
+					continue
+				}
+				logFlags.AddFlag(LogFile)
+				logPath = p
+				break
+			} else {
+				dirPath := path.Dir(p)
+				if err = paths.MakeDirIfNotExist(dirPath); err != nil {
+					continue
+				}
+				if success, err = testOpen(p); err != nil {
+					continue
+				} else if !success {
+					continue
+				}
+				logFlags.AddFlag(LogFile)
+				logPath = p
+				break
+			}
+		}
+	}
+
+	if logFlags.HasFlag(LogSyslog) {
+		logger = &SyslogLogger{
+			Prefix:      logPrefix,
+			EnableDebug: enableDebug,
+		}
+	} else {
+		if logFlags.HasFlag(LogFile) {
+			logger = &FileLogger{
+				StdLogger: StdLogger{
+					Prefix:      logPrefix,
+					EnableDebug: enableDebug,
+					LogFlags:    logConfigFlags,
+				},
+				Path: logPath,
+			}
+		} else {
+			logger = &StdLogger{
+				Prefix:      logPrefix,
+				EnableDebug: enableDebug,
+				LogFlags:    logConfigFlags,
+			}
+		}
+	}
+
+	if prefix != "\x00" {
+		if err = logger.SetPrefix(prefix); err != nil {
+			return
+		}
+	}
+	if err = logger.Setup(); err != nil {
+		return
+	}
+
+	if currentPrefix, err = logger.GetPrefix(); err != nil {
+		return
+	}
+
+	logger.Debug("logger initialized of type %T with prefix %v", logger, currentPrefix)
+
+	return
+}

logging/funcs_std.go

@@ -2,15 +2,15 @@ package logging
 
 import (
 	"fmt"
-	`io`
-	`log`
-	`os`
-	`strings`
+	"io"
+	"log"
+	"os"
+	"strings"
 )
 
 /*
-	Setup sets up/configures a StdLogger and prepares it for use.
-	err will always be nil; it's there for interface-compat.
+Setup sets up/configures a StdLogger and prepares it for use.
+err will always be nil; it's there for interface-compat.
 */
 func (l *StdLogger) Setup() (err error) {
 
@@ -47,8 +47,8 @@ func (l *StdLogger) Setup() (err error) {
 }
 
 /*
-	Shutdown cleanly shuts down a StdLogger.
-	err will always be nil; it's there for interface-compat.
+Shutdown cleanly shuts down a StdLogger.
+err will always be nil; it's there for interface-compat.
 */
 func (l *StdLogger) Shutdown() (err error) {
 
@@ -58,8 +58,8 @@ func (l *StdLogger) Shutdown() (err error) {
 }
 
 /*
-	GetPrefix returns the prefix used by this StdLogger.
-	err will always be nil; it's there for interface-compat.
+GetPrefix returns the prefix used by this StdLogger.
+err will always be nil; it's there for interface-compat.
 */
 func (l *StdLogger) GetPrefix() (prefix string, err error) {
 
@@ -69,9 +69,9 @@ func (l *StdLogger) GetPrefix() (prefix string, err error) {
 }
 
 /*
-	DoDebug sets the debug state of this StdLogger.
-	Note that this merely acts as a *safety filter* for debug messages to avoid sensitive information being written to the log.
-	err will always be nil; it's there for interface-compat.
+DoDebug sets the debug state of this StdLogger.
+Note that this merely acts as a *safety filter* for debug messages to avoid sensitive information being written to the log.
+err will always be nil; it's there for interface-compat.
 */
 func (l *StdLogger) DoDebug(d bool) (err error) {
 
@@ -80,9 +80,17 @@ func (l *StdLogger) DoDebug(d bool) (err error) {
 	return
 }
 
+// GetDebug returns the debug status of this StdLogger.
+func (l *StdLogger) GetDebug() (d bool) {
+
+	d = l.EnableDebug
+
+	return
+}
+
 /*
-	SetPrefix sets the prefix for this StdLogger.
-	err will always be nil; it's there for interface-compat.
+SetPrefix sets the prefix for this StdLogger.
+err will always be nil; it's there for interface-compat.
 */
 func (l *StdLogger) SetPrefix(prefix string) (err error) {
 
@@ -227,6 +235,22 @@ func (l *StdLogger) Warning(s string, v ...interface{}) (err error) {
 	return
 }
 
+// ToLogger returns a stdlib log.Logger.
+func (l *StdLogger) ToLogger(prio logPrio) (stdLibLog *log.Logger) {
+
+	stdLibLog = log.New(l.ToRaw(prio), "", 0)
+
+	return
+}
+
+// ToRaw returns a *logWriter.
+func (l *StdLogger) ToRaw(prio logPrio) (raw *logWriter) {
+
+	raw = &logWriter{backend: l, prio: prio}
+
+	return
+}
+
 // renderWrite prepares/formats a log message to be written to this StdLogger.
 func (l *StdLogger) renderWrite(msg, prio string) {
 

logging/funcs_sysd_linux.go

@@ -4,12 +4,12 @@ import (
 	"fmt"
 	"log"
 
-	"github.com/coreos/go-systemd/journal"
+	"github.com/coreos/go-systemd/v22/journal"
 )
 
 /*
-	Setup sets up/configures a SystemDLogger and prepares it for use.
-	err will always be nil; it's there for interface-compat.
+Setup sets up/configures a SystemDLogger and prepares it for use.
+err will always be nil; it's there for interface-compat.
 */
 func (l *SystemDLogger) Setup() (err error) {
 
@@ -19,8 +19,8 @@ func (l *SystemDLogger) Setup() (err error) {
 }
 
 /*
-	Shutdown cleanly shuts down a SystemDLogger.
-	err will always be nil; it's there for interface-compat.
+Shutdown cleanly shuts down a SystemDLogger.
+err will always be nil; it's there for interface-compat.
 */
 func (l *SystemDLogger) Shutdown() (err error) {
 
@@ -30,8 +30,8 @@ func (l *SystemDLogger) Shutdown() (err error) {
 }
 
 /*
-	GetPrefix returns the prefix used by this SystemDLogger.
-	err will always be nil; it's there for interface-compat.
+GetPrefix returns the prefix used by this SystemDLogger.
+err will always be nil; it's there for interface-compat.
 */
 func (l *SystemDLogger) GetPrefix() (prefix string, err error) {
 
@@ -41,9 +41,9 @@ func (l *SystemDLogger) GetPrefix() (prefix string, err error) {
 }
 
 /*
-	DoDebug sets the debug state of this SystemDLogger.
-	Note that this merely acts as a *safety filter* for debug messages to avoid sensitive information being written to the log.
-	err will always be nil; it's there for interface-compat.
+DoDebug sets the debug state of this SystemDLogger.
+Note that this merely acts as a *safety filter* for debug messages to avoid sensitive information being written to the log.
+err will always be nil; it's there for interface-compat.
 */
 func (l *SystemDLogger) DoDebug(d bool) (err error) {
 
@@ -52,9 +52,17 @@ func (l *SystemDLogger) DoDebug(d bool) (err error) {
 	return
 }
 
+// GetDebug returns the debug status of this SystemDLogger.
+func (l *SystemDLogger) GetDebug() (d bool) {
+
+	d = l.EnableDebug
+
+	return
+}
+
 /*
-	SetPrefix sets the prefix for this SystemDLogger.
-	err will always be nil; it's there for interface-compat.
+SetPrefix sets the prefix for this SystemDLogger.
+err will always be nil; it's there for interface-compat.
 */
 func (l *SystemDLogger) SetPrefix(prefix string) (err error) {
 
@@ -215,3 +223,19 @@ func (l *SystemDLogger) renderWrite(msg string, prio journal.Priority) {
 
 	return
 }
+
+// ToLogger returns a stdlib log.Logger.
+func (l *SystemDLogger) ToLogger(prio logPrio) (stdLibLog *log.Logger) {
+
+	stdLibLog = log.New(l.ToRaw(prio), "", 0)
+
+	return
+}
+
+// ToRaw returns a *logWriter.
+func (l *SystemDLogger) ToRaw(prio logPrio) (raw *logWriter) {
+
+	raw = &logWriter{backend: l, prio: prio}
+
+	return
+}

logging/funcs_syslog_nix.go

@@ -1,3 +1,6 @@
+//go:build !(windows || plan9 || wasip1 || js || ios)
+// +build !windows,!plan9,!wasip1,!js,!ios
+
 package logging
 
 import (
@@ -5,7 +8,7 @@ import (
 	"log"
 	"log/syslog"
 
-	`r00t2.io/goutils/multierr`
+	"r00t2.io/goutils/multierr"
 )
 
 // Setup sets up/configures a SyslogLogger and prepares it for use.
@@ -73,8 +76,8 @@ func (l *SyslogLogger) Shutdown() (err error) {
 }
 
 /*
-	GetPrefix returns the prefix used by this SyslogLogger.
-	err will always be nil; it's there for interface-compat.
+GetPrefix returns the prefix used by this SyslogLogger.
+err will always be nil; it's there for interface-compat.
 */
 func (l *SyslogLogger) GetPrefix() (prefix string, err error) {
 
@@ -84,9 +87,9 @@ func (l *SyslogLogger) GetPrefix() (prefix string, err error) {
 }
 
 /*
-	DoDebug sets the debug state of this SyslogLogger.
-	Note that this merely acts as a *safety filter* for debug messages to avoid sensitive information being written to the log.
-	err will always be nil; it's there for interface-compat.
+DoDebug sets the debug state of this SyslogLogger.
+Note that this merely acts as a *safety filter* for debug messages to avoid sensitive information being written to the log.
+err will always be nil; it's there for interface-compat.
 */
 func (l *SyslogLogger) DoDebug(d bool) (err error) {
 
@@ -95,6 +98,14 @@ func (l *SyslogLogger) DoDebug(d bool) (err error) {
 	return
 }
 
+// GetDebug returns the debug status of this SyslogLogger.
+func (l *SyslogLogger) GetDebug() (d bool) {
+
+	d = l.EnableDebug
+
+	return
+}
+
 // SetPrefix sets the prefix for this SyslogLogger.
 func (l *SyslogLogger) SetPrefix(prefix string) (err error) {
 
@@ -258,3 +269,19 @@ func (l *SyslogLogger) Warning(s string, v ...interface{}) (err error) {
 
 	return
 }
+
+// ToLogger returns a stdlib log.Logger.
+func (l *SyslogLogger) ToLogger(prio logPrio) (stdLibLog *log.Logger) {
+
+	stdLibLog = log.New(l.ToRaw(prio), "", 0)
+
+	return
+}
+
+// ToRaw returns a *logWriter.
+func (l *SyslogLogger) ToRaw(prio logPrio) (raw *logWriter) {
+
+	raw = &logWriter{backend: l, prio: prio}
+
+	return
+}

logging/funcs_winlogger_windows.go

@@ -1,26 +1,27 @@
 package logging
 
 import (
-	`errors`
-	`fmt`
-	`os`
-	`os/exec`
-	`syscall`
+	"errors"
+	"fmt"
+	"log"
+	"os"
+	"os/exec"
+	"syscall"
 
-	`golang.org/x/sys/windows/registry`
-	`golang.org/x/sys/windows/svc/eventlog`
-	`r00t2.io/sysutils/paths`
+	"golang.org/x/sys/windows/registry"
+	"golang.org/x/sys/windows/svc/eventlog"
+	"r00t2.io/sysutils/paths"
 )
 
 /*
-	Setup sets up/configures a WinLogger and prepares it for use.
-	This will fail with an Access Denied (the first time, at least) unless running with elevated permissions unless WinLogger.Prefix is
-	a registered Event Log source.
+Setup sets up/configures a WinLogger and prepares it for use.
+This will fail with an Access Denied (the first time, at least) unless running with elevated permissions unless WinLogger.Prefix is
+a registered Event Log source.
 
-	If a failure occurs while trying to open the log with the given WinLogger.Prefix ("source"), a new Event Log source will be registered.
-	If WinLogger.Executable is not empty at the time of calling WinLogger.Setup (or WinLogger.ForceService is true),
-	eventlog.Install will be used (with the WinLogger.ExpandKey field).
-	Otherwise eventlog.InstallAsEventCreate will be used.
+If a failure occurs while trying to open the log with the given WinLogger.Prefix ("source"), a new Event Log source will be registered.
+If WinLogger.Executable is not empty at the time of calling WinLogger.Setup (or WinLogger.ForceService is true),
+eventlog.Install will be used (with the WinLogger.ExpandKey field).
+Otherwise eventlog.InstallAsEventCreate will be used.
 */
 func (l *WinLogger) Setup() (err error) {
 
@@ -108,8 +109,8 @@ func (l *WinLogger) Remove() (err error) {
 }
 
 /*
-	Shutdown cleanly shuts down a WinLogger but keep the source registered. Use WinLogger.Remove
-	(or set WinLogger.RemoveOnClose to true before calling WinLogger.Shutdown) to remove the registered source.
+Shutdown cleanly shuts down a WinLogger but keep the source registered. Use WinLogger.Remove
+(or set WinLogger.RemoveOnClose to true before calling WinLogger.Shutdown) to remove the registered source.
 */
 func (l *WinLogger) Shutdown() (err error) {
 
@@ -128,8 +129,8 @@ func (l *WinLogger) Shutdown() (err error) {
 }
 
 /*
-	GetPrefix returns the prefix used by this WinLogger.
-	err will always be nil; it's there for interface-compat.
+GetPrefix returns the prefix used by this WinLogger.
+err will always be nil; it's there for interface-compat.
 */
 func (l *WinLogger) GetPrefix() (prefix string, err error) {
 
@@ -139,9 +140,9 @@ func (l *WinLogger) GetPrefix() (prefix string, err error) {
 }
 
 /*
-	DoDebug sets the debug state of this WinLogger.
-	Note that this merely acts as a *safety filter* for debug messages to avoid sensitive information being written to the log.
-	err will always be nil; it's there for interface-compat.
+DoDebug sets the debug state of this WinLogger.
+Note that this merely acts as a *safety filter* for debug messages to avoid sensitive information being written to the log.
+err will always be nil; it's there for interface-compat.
 */
 func (l *WinLogger) DoDebug(d bool) (err error) {
 
@@ -150,6 +151,14 @@ func (l *WinLogger) DoDebug(d bool) (err error) {
 	return
 }
 
+// GetDebug returns the debug status of this WinLogger.
+func (l *WinLogger) GetDebug() (d bool) {
+
+	d = l.EnableDebug
+
+	return
+}
+
 // SetPrefix sets the prefix for this WinLogger.
 func (l *WinLogger) SetPrefix(prefix string) (err error) {
 
@@ -334,3 +343,19 @@ func (l *WinLogger) Warning(s string, v ...interface{}) (err error) {
 	return
 
 }
+
+// ToLogger returns a stdlib log.Logger.
+func (l *WinLogger) ToLogger(prio logPrio) (stdLibLog *log.Logger) {
+
+	stdLibLog = log.New(l.ToRaw(prio), "", 0)
+
+	return
+}
+
+// ToRaw returns a *logWriter.
+func (l *WinLogger) ToRaw(prio logPrio) (raw *logWriter) {
+
+	raw = &logWriter{backend: l, prio: prio}
+
+	return
+}

logging/types.go

@@ -2,11 +2,15 @@ package logging
 
 import (
 	"log"
-	`os`
+	"os"
+
+	"r00t2.io/goutils/bitmask"
 )
 
+type logPrio bitmask.MaskBit
+
 /*
-	Logger is one of the various loggers offered by this module.
+Logger is one of the various loggers offered by this module.
 */
 type Logger interface {
 	Alert(s string, v ...interface{}) (err error)
@@ -18,15 +22,18 @@ type Logger interface {
 	Notice(s string, v ...interface{}) (err error)
 	Warning(s string, v ...interface{}) (err error)
 	DoDebug(d bool) (err error)
+	GetDebug() (d bool)
 	SetPrefix(p string) (err error)
 	GetPrefix() (p string, err error)
 	Setup() (err error)
 	Shutdown() (err error)
+	ToLogger(prio logPrio) (stdLibLog *log.Logger)
+	ToRaw(prio logPrio) (raw *logWriter)
 }
 
 /*
-	StdLogger uses the log package in stdlib to perform all logging. The default is to write to STDOUT.
-	If you wish to modify the underling log.Logger object, you can access it directly via StdLogger.Logger.
+StdLogger uses the log package in stdlib to perform all logging. The default is to write to STDOUT.
+If you wish to modify the underling log.Logger object, you can access it directly via StdLogger.Logger.
 */
 type StdLogger struct {
 	// All log.Logger fields/methods are exposed.
@@ -71,11 +78,11 @@ type StdLogger struct {
 }
 
 /*
-	FileLogger uses a StdLogger with a file handle writer to write to the file given at Path.
+FileLogger uses a StdLogger with a file handle writer to write to the file given at Path.
 
-	NOTE: If you wish to change the FileLogger.StdLogger.LogFlags, do *not* run FileLogger.StdLogger.Setup after doing so as this
-	will instead create a logger detached from the file handler. Instead, be sure to call FileLogger.Setup.
-	(Alternatively, run FileLogger.Shutdown and replace your logger with a new FileLogger.)
+NOTE: If you wish to change the FileLogger.StdLogger.LogFlags, do *not* run FileLogger.StdLogger.Setup after doing so as this
+will instead create a logger detached from the file handler. Instead, be sure to call FileLogger.Setup.
+(Alternatively, run FileLogger.Shutdown and replace your logger with a new FileLogger.)
 */
 type FileLogger struct {
 	// StdLogger is used for the log formation and handling. See StdLogger for more details.
@@ -86,6 +93,9 @@ type FileLogger struct {
 	writer *os.File
 }
 
+// NullLogger is used mainly for test implementations, mockup code, etc. It does absolutely nothing with all messages sent to it.
+type NullLogger struct{}
+
 // MultiLogger is used to contain one or more Loggers and present them all as a single Logger.
 type MultiLogger struct {
 	/*
@@ -101,3 +111,12 @@ type MultiLogger struct {
 	*/
 	Loggers map[string]Logger
 }
+
+// logWriter is used as a log.Logger and is returned by <Logger>.ToLogger.
+type logWriter struct {
+	backend Logger
+	prio    logPrio
+}
+
+// nullWriter is used as a shortcut by NullLogger.ToLogger.
+type nullWriter struct{}

logging/types_linux.go

@@ -1,27 +1,9 @@
 package logging
 
-import (
-	`log/syslog`
-)
-
 /*
-	SystemDLogger (yes, I'm aware it's actually written as "systemd") writes to journald on systemd-enabled systems.
+SystemDLogger (yes, I'm aware it's actually written as "systemd") writes to journald on systemd-enabled systems.
 */
 type SystemDLogger struct {
 	EnableDebug bool
 	Prefix      string
 }
-
-// SyslogLogger writes to syslog on syslog-enabled systems.
-type SyslogLogger struct {
-	EnableDebug bool
-	Prefix      string
-	alert,
-	crit,
-	debug,
-	emerg,
-	err,
-	info,
-	notice,
-	warning *syslog.Writer
-}

logging/types_nix.go

@@ -0,0 +1,22 @@
+//go:build !(windows || plan9 || wasip1 || js || ios)
+// +build !windows,!plan9,!wasip1,!js,!ios
+
+package logging
+
+import (
+	"log/syslog"
+)
+
+// SyslogLogger writes to syslog on syslog-enabled systems.
+type SyslogLogger struct {
+	EnableDebug bool
+	Prefix      string
+	alert,
+	crit,
+	debug,
+	emerg,
+	err,
+	info,
+	notice,
+	warning *syslog.Writer
+}

multierr/funcs.go

@@ -69,6 +69,9 @@ func (e *MultiError) Error() (errStr string) {
 		numErrs = len(e.Errors)
 	}
 
+	e.lock.Lock()
+	defer e.lock.Unlock()
+
 	for idx, err := range e.Errors {
 		if (idx + 1) < numErrs {
 			errStr += fmt.Sprintf("%v%v", err.Error(), e.ErrorSep)
@@ -87,6 +90,9 @@ func (e *MultiError) AddError(err error) {
 		return
 	}
 
+	e.lock.Lock()
+	defer e.lock.Unlock()
+
 	e.Errors = append(e.Errors, err)
 
 }

multierr/types.go

@@ -1,9 +1,14 @@
 package multierr
 
+import (
+	`sync`
+)
+
 // MultiError is a type of error.Error that can contain multiple errors.
 type MultiError struct {
 	// Errors is a slice of errors to combine/concatenate when .Error() is called.
 	Errors []error `json:"errors"`
 	// ErrorSep is a string to use to separate errors for .Error(). The default is "\n".
 	ErrorSep string `json:"separator"`
+	lock sync.Mutex
 }

netx/docs.go

@@ -0,0 +1,4 @@
+/*
+Package netx includes extensions to the stdlib `net` module.
+*/
+package netx

netx/inetcksum/consts.go

@@ -0,0 +1,24 @@
+package inetcksum
+
+import (
+	`encoding/binary`
+)
+
+const (
+	// EmptyCksum is returned for checksums of 0-length byte slices/buffers.
+	EmptyCksum uint16 = 0xffff
+)
+
+const (
+	// cksumMask is AND'd with a checksum to get the "carried ones".
+	cksumMask uint32 = 0x0000ffff
+	// cksumShift is used in the "carried-ones folding".
+	cksumShift uint32 = 0x00000010
+	// padShift is used to "pad out" a checksum for odd-length buffers by left-shifting.
+	padShift uint32 = 0x00000008
+)
+
+var (
+	// ord is the byte order used by the Internet Checksum.
+	ord binary.ByteOrder = binary.BigEndian
+)

netx/inetcksum/docs.go

@@ -0,0 +1,32 @@
+/*
+Package inetcksum applies the "Internet Checksum" algorithm as specified/described in:
+
+	* [RFC 1071]
+	* [RFC 1141]
+	* [RFC 1624]
+
+It provides [InetChecksum], which can be used as a:
+
+	* [hash.Hash]
+	* [io.ByteWriter]
+	* [io.StringWriter]
+	* [io.Writer]
+	* [io.WriterTo]
+
+and allows one to retrieve the actual bytes that were checksummed.
+It is also fully concurrency-safe.
+
+There is also an [InetChecksumSimple] provided, which is more
+tailored for performance/resource usage at the cost of no concurrency
+safety and no data retention, which can be used as a:
+
+	* [hash.Hash]
+	* [io.ByteWriter]
+	* [io.StringWriter]
+	* [io.Writer]
+
+[RFC 1071]: https://datatracker.ietf.org/doc/html/rfc1071
+[RFC 1141]: https://datatracker.ietf.org/doc/html/rfc1141
+[RFC 1624]: https://datatracker.ietf.org/doc/html/rfc1624
+*/
+package inetcksum

netx/inetcksum/funcs.go

@@ -0,0 +1,62 @@
+package inetcksum
+
+import (
+	`io`
+)
+
+// New returns a new initialized [InetChecksum]. It will never panic.
+func New() (i *InetChecksum) {
+
+	i = &InetChecksum{}
+	_ = i.Aligned()
+
+	return
+}
+
+/*
+NewFromBytes returns a new [InetChecksum] initialized with explicit bytes.
+
+b may be nil or 0-length; this will not cause an error.
+*/
+func NewFromBytes(b []byte) (i *InetChecksum, copied int, err error) {
+
+	var cksum InetChecksum
+
+	if b != nil && len(b) > 0 {
+		if copied, err = cksum.Write(b); err != nil {
+			return
+		}
+		_ = i.Aligned()
+	} else {
+		i = New()
+		return
+	}
+
+	i = &cksum
+
+	return
+}
+
+/*
+NewFromBuf returns an [InetChecksum] from a specified [io.Reader].
+
+buf may be nil. If it isn't, NewFromBuf will call [io.Copy] on buf.
+Note that this may exhaust your passed buf or advance its current seek position/offset,
+depending on its type.
+*/
+func NewFromBuf(buf io.Reader) (i *InetChecksum, copied int64, err error) {
+
+	var cksum InetChecksum
+
+	_ = i.Aligned()
+
+	if buf != nil {
+		if copied, err = io.Copy(&cksum, buf); err != nil {
+			return
+		}
+	}
+
+	i = &cksum
+
+	return
+}

netx/inetcksum/funcs_inetchecksum.go

@@ -0,0 +1,351 @@
+package inetcksum
+
+import (
+	`io`
+)
+
+/*
+Aligned returns true if the current underlying buffer in an InetChecksum is
+aligned to the algorithm's requirement for an even number of bytes.
+
+Note that if Aligned returns false, a single null pad byte will be applied
+to the underlying data buffer at time of a Sum* call, but will not be written
+to the persistent underlying storage.
+
+If aligned's underlying buffer/storage is empty or nil, aligned will be true.
+
+Aligned will also force-set the internal state's aligned status.
+*/
+func (i *InetChecksum) Aligned() (aligned bool) {
+
+	i.alignLock.Lock()
+	defer i.alignLock.Unlock()
+
+	i.bufLock.RLock()
+	aligned = i.buf.Len()&2 == 0
+	i.bufLock.RUnlock()
+
+	i.aligned = aligned
+
+	return
+}
+
+// BlockSize returns the number of bytes at a time that InetChecksum operates on. (It will always return 1.)
+func (i *InetChecksum) BlockSize() (blockSize int) {
+
+	blockSize = 1
+
+	return
+}
+
+/*
+Bytes returns teh bytes currently in the internal storage.
+
+curBuf will be nil if the internal storage has not yet been initialized.
+*/
+func (i *InetChecksum) Bytes() (curBuf []byte) {
+
+	i.bufLock.RLock()
+	defer i.bufLock.RUnlock()
+
+	if i.buf.Len() != 0 {
+		curBuf = i.buf.Bytes()
+	}
+
+	return
+}
+
+// Clear empties the internal buffer (but does not affect the checksum state).
+func (i *InetChecksum) Clear() {
+
+	i.bufLock.Lock()
+	defer i.bufLock.Unlock()
+
+	i.buf.Reset()
+}
+
+/*
+DisablePersist disables the internal persistence of an InetChecksum.
+
+This is recommended for integrations that desire the concurrency safety
+of an InetChecksum but want a smaller memory footprint and do not need a copy
+of data that was hashed.
+
+Any data existing in the buffer will NOT be cleared out if DisablePersist is called.
+You must call [InetChecksum.Clear] to do that.
+
+Persistence CANNOT be reenabled once disabled. [InetChecksum.Reset]
+must be called to re-enable persistence.
+*/
+func (i *InetChecksum) DisablePersist() {
+
+	i.bufLock.Lock()
+	defer i.bufLock.Unlock()
+
+	i.disabledBuf = true
+}
+
+// Len returns the current amount of bytes stored in this InetChecksum's internal buffer.
+func (i *InetChecksum) Len() (l int) {
+
+	i.bufLock.RLock()
+	defer i.bufLock.RUnlock()
+	l = i.buf.Len()
+
+	return
+}
+
+/*
+Reset resets the internal buffer/storage to an empty state.
+
+If persistence was disabled ([InetChecksum.DisablePersist]),
+this method will re-enable it with an empty buffer.
+If you wish the buffer to be disabled, you must invoke [InetChecksum.DisablePersist]
+again.
+
+If you only wish to clear the buffer without losing the checksum state,
+use [InetChecksum.Clear].
+*/
+func (i *InetChecksum) Reset() {
+
+	i.alignLock.Lock()
+	i.bufLock.Lock()
+	i.sumLock.Lock()
+	i.lastLock.Lock()
+
+	i.aligned = false
+	i.alignLock.Unlock()
+
+	i.buf.Reset()
+	i.disabledBuf = false
+	i.bufLock.Unlock()
+
+	i.last = 0x00
+	i.lastLock.Unlock()
+
+	i.sum = 0
+	i.sumLock.Unlock()
+}
+
+// Size returns how many bytes a checksum is. (It will always return 2.)
+func (i *InetChecksum) Size() (bufSize int) {
+
+	bufSize = 2
+
+	return
+}
+
+// Sum computes the checksum cksum of the current buffer and appends it as big-endian bytes to b.
+func (i *InetChecksum) Sum(b []byte) (cksumAppended []byte) {
+
+	var sum16 []byte = i.Sum16Bytes()
+
+	cksumAppended = append(b, sum16...)
+
+	return
+}
+
+/*
+Sum16 computes the checksum of the current buffer and returns it as a uint16.
+
+This is the native number used in the IPv4 header.
+All other Sum* methods wrap this method.
+
+If the underlying buffer is empty or nil, cksum will be 0xffff (65535)
+in line with common implementations.
+*/
+func (i *InetChecksum) Sum16() (cksum uint16) {
+
+	var thisSum uint32
+
+	i.alignLock.RLock()
+	i.lastLock.RLock()
+	i.sumLock.RLock()
+
+	thisSum = i.sum
+	i.sumLock.RUnlock()
+
+	if !i.aligned {
+		/*
+			"Pad" at the end of the additive ops - a bitshift is used on the sum integer itself
+			instead of a binary.Append() or append() or such to avoid additional memory allocation.
+		*/
+		thisSum += uint32(i.last) << padShift
+	}
+	i.lastLock.RUnlock()
+	i.alignLock.RUnlock()
+
+	// Fold the "carried ones".
+	for thisSum > cksumMask {
+		thisSum = (thisSum & cksumMask) + (thisSum >> cksumShift)
+	}
+	cksum = ^uint16(thisSum)
+
+	return
+}
+
+/*
+Sum16Bytes is a convenience wrapper around [InetChecksum.Sum16]
+which returns a slice of the uint16 as a 2-byte-long slice instead.
+*/
+func (i *InetChecksum) Sum16Bytes() (cksum []byte) {
+
+	var sum16 uint16 = i.Sum16()
+
+	cksum = make([]byte, 2)
+
+	ord.PutUint16(cksum, sum16)
+
+	return
+}
+
+/*
+Write writes data to the underlying InetChecksum buffer. It conforms to [io.Writer].
+
+If this operation returns an error, you MUST call [InetChecksum.Reset] as the instance
+being used can no longer be considered to be in a consistent state.
+
+p may be nil or empty; no error will be returned and n will be 0 if so.
+
+Write is concurrency safe; a copy of p is made first and all hashing/internal
+storage writing is performed on/which that copy.
+*/
+func (i *InetChecksum) Write(p []byte) (n int, err error) {
+
+	var idx int
+	var bufLen int
+	var buf []byte
+	var iter int
+	var origLast byte
+	var origAligned bool
+	var origSum uint32
+
+	if p == nil || len(p) == 0 {
+		return
+	}
+
+	// The TL;DR here is the checksum boils down to:
+	// cksum = cksum + ((high << 8) | low)
+
+	bufLen = len(p)
+	buf = make([]byte, bufLen)
+	copy(buf, p)
+
+	i.alignLock.Lock()
+	defer i.alignLock.Unlock()
+	i.bufLock.Lock()
+	defer i.bufLock.Unlock()
+	i.sumLock.Lock()
+	defer i.sumLock.Unlock()
+	i.lastLock.Lock()
+	defer i.lastLock.Unlock()
+
+	origLast = i.last
+	origAligned = i.aligned
+	origSum = i.sum
+
+	if !i.aligned {
+		// Last write was unaligned, so pair i.last in.
+		i.sum += (uint32(i.last) << padShift) | uint32(buf[0])
+		i.aligned = true
+		idx = 1
+	}
+
+	// Operate on bytepairs.
+	// Note that idx is set to either 0 or 1 depending on if
+	// buf[0] has already been summed in.
+	for iter = idx; iter < bufLen; iter += 2 {
+		if iter+1 < bufLen {
+			// Technically could use "i.sum += uint32(ord.Uint16(buf[iter:iter+2))" here instead.
+			i.sum += (uint32(buf[iter]) << padShift) | uint32(buf[iter+1])
+		} else {
+			i.last = buf[iter]
+			i.aligned = false
+			break
+		}
+	}
+
+	if !i.disabledBuf {
+		if n, err = i.buf.Write(buf); err != nil {
+			i.sum = origSum
+			i.aligned = origAligned
+			i.last = origLast
+			return
+		}
+	}
+
+	return
+}
+
+// WriteByte writes a single byte to the underlying storage. It conforms to [io.ByteWriter].
+func (i *InetChecksum) WriteByte(c byte) (err error) {
+
+	var origLast byte
+	var origAligned bool
+	var origSum uint32
+
+	i.alignLock.Lock()
+	defer i.alignLock.Unlock()
+	i.bufLock.Lock()
+	defer i.bufLock.Unlock()
+	i.sumLock.Lock()
+	defer i.sumLock.Unlock()
+	i.lastLock.Lock()
+	defer i.lastLock.Unlock()
+
+	origLast = i.last
+	origAligned = i.aligned
+	origSum = i.sum
+
+	if i.aligned {
+		// Since it's a single byte, we just set i.last and unalign.
+		i.last = c
+		i.aligned = false
+	} else {
+		// It's unaligned, so join with i.last and align.
+		i.sum += (uint32(i.last) << padShift) | uint32(c)
+		i.aligned = true
+	}
+
+	if !i.disabledBuf {
+		if err = i.WriteByte(c); err != nil {
+			i.sum = origSum
+			i.aligned = origAligned
+			i.last = origLast
+			return
+		}
+	}
+
+	return
+}
+
+// WriteString writes a string to the underlying storage. It conforms to [io.StringWriter].
+func (i *InetChecksum) WriteString(s string) (n int, err error) {
+
+	if n, err = i.Write([]byte(s)); err != nil {
+		return
+	}
+
+	return
+}
+
+// WriteTo writes the current contents of the underlying buffer to w. The contents are not drained. Noop if persistence is disabled.
+func (i *InetChecksum) WriteTo(w io.Writer) (n int64, err error) {
+
+	var wrtn int
+
+	if i.disabledBuf {
+		return
+	}
+
+	i.bufLock.RLock()
+	defer i.bufLock.RUnlock()
+
+	if wrtn, err = w.Write(i.buf.Bytes()); err != nil {
+		n = int64(wrtn)
+		return
+	}
+	n = int64(wrtn)
+
+	return
+}

netx/inetcksum/funcs_inetchecksumsimple.go

@@ -0,0 +1,172 @@
+package inetcksum
+
+/*
+Aligned returns true if the current checksum for an InetChecksumSimple is
+aligned to the algorithm's requirement for an even number of bytes.
+
+Note that if Aligned returns false, a single null pad byte will be applied
+to the underlying data buffer at time of a Sum* call.
+*/
+func (i *InetChecksumSimple) Aligned() (aligned bool) {
+
+	aligned = i.aligned
+
+	return
+}
+
+// BlockSize returns the number of bytes at a time that InetChecksumSimple operates on. (It will always return 1.)
+func (i *InetChecksumSimple) BlockSize() (blockSize int) {
+
+	blockSize = 1
+
+	return
+}
+
+// Reset resets the state of an InetChecksumSimple.
+func (i *InetChecksumSimple) Reset() {
+
+	i.last = 0x00
+	i.sum = 0
+	i.last = 0x00
+
+}
+
+// Size returns how many bytes a checksum is. (It will always return 2.)
+func (i *InetChecksumSimple) Size() (bufSize int) {
+
+	bufSize = 2
+
+	return
+}
+
+// Sum computes the checksum cksum of the current buffer and appends it as big-endian bytes to b.
+func (i *InetChecksumSimple) Sum(b []byte) (cksumAppended []byte) {
+
+	var sum16 []byte = i.Sum16Bytes()
+
+	cksumAppended = append(b, sum16...)
+
+	return
+}
+
+/*
+Sum16 computes the checksum of the current buffer and returns it as a uint16.
+
+This is the native number used in the IPv4 header.
+All other Sum* methods wrap this method.
+
+If the underlying buffer is empty or nil, cksum will be 0xffff (65535)
+in line with common implementations.
+*/
+func (i *InetChecksumSimple) Sum16() (cksum uint16) {
+
+	var thisSum uint32
+
+	thisSum = i.sum
+
+	if !i.aligned {
+		/*
+			"Pad" at the end of the additive ops - a bitshift is used on the sum integer itself
+			instead of a binary.Append() or append() or such to avoid additional memory allocation.
+		*/
+		thisSum += uint32(i.last) << padShift
+	}
+
+	// Fold the "carried ones".
+	for thisSum > cksumMask {
+		thisSum = (thisSum & cksumMask) + (thisSum >> cksumShift)
+	}
+	cksum = ^uint16(thisSum)
+
+	return
+}
+
+/*
+Sum16Bytes is a convenience wrapper around [InetChecksumSimple.Sum16]
+which returns a slice of the uint16 as a 2-byte-long slice instead.
+*/
+func (i *InetChecksumSimple) Sum16Bytes() (cksum []byte) {
+
+	var sum16 uint16 = i.Sum16()
+
+	cksum = make([]byte, 2)
+
+	ord.PutUint16(cksum, sum16)
+
+	return
+}
+
+/*
+Write writes data to the underlying InetChecksumSimple buffer. It conforms to [io.Writer].
+
+p may be nil or empty; no error will be returned and n will be 0 if so.
+
+A copy of p is made first and all hashing operations are performed on that copy.
+*/
+func (i *InetChecksumSimple) Write(p []byte) (n int, err error) {
+
+	var idx int
+	var bufLen int
+	var buf []byte
+	var iter int
+
+	if p == nil || len(p) == 0 {
+		return
+	}
+
+	// The TL;DR here is the checksum boils down to:
+	// cksum = cksum + ((high << 8) | low)
+
+	bufLen = len(p)
+	buf = make([]byte, bufLen)
+	copy(buf, p)
+
+	if !i.aligned {
+		// Last write was unaligned, so pair i.last in.
+		i.sum += (uint32(i.last) << padShift) | uint32(buf[0])
+		i.aligned = true
+		idx = 1
+	}
+
+	// Operate on bytepairs.
+	// Note that idx is set to either 0 or 1 depending on if
+	// buf[0] has already been summed in.
+	for iter = idx; iter < bufLen; iter += 2 {
+		if iter+1 < bufLen {
+			// Technically could use "i.sum += uint32(ord.Uint16(buf[iter:iter+2))" here instead.
+			i.sum += (uint32(buf[iter]) << padShift) | uint32(buf[iter+1])
+		} else {
+			i.last = buf[iter]
+			i.aligned = false
+			break
+		}
+	}
+
+	return
+}
+
+// WriteByte checksums a single byte. It conforms to [io.ByteWriter].
+func (i *InetChecksumSimple) WriteByte(c byte) (err error) {
+
+	if i.aligned {
+		// Since it's a single byte, we just set i.last and unalign.
+		i.last = c
+		i.aligned = false
+	} else {
+		// It's unaligned, so join with i.last and align.
+		i.sum += (uint32(i.last) << padShift) | uint32(c)
+		i.aligned = true
+	}
+
+	return
+}
+
+// WriteString checksums a string. It conforms to [io.StringWriter].
+func (i *InetChecksumSimple) WriteString(s string) (n int, err error) {
+
+	if n, err = i.Write([]byte(s)); err != nil {
+		return
+	}
+
+	return
+}

netx/inetcksum/types.go

@@ -0,0 +1,68 @@
+package inetcksum
+
+import (
+	`bytes`
+	`sync`
+)
+
+type (
+	/*
+		InetChecksum implements [hash.Hash] and various other stdlib interfaces.
+
+		If the current data in an InetChecksum's buffer is not aligned
+		to an even number of bytes -- e.g. InetChecksum.buf.Len() % 2 != 0,
+		[InetChecksum.Aligned] will return false (otherwise it will return
+		true).
+
+		If [InetChecksum.Aligned] returns false, the checksum result of an
+		[InetChecksum.Sum] or [InetChecksum.Sum16] (or any other operation
+		returning a sum) will INCLUDE THE PAD NULL BYTE (which is only
+		applied *at the time of the Sum/Sum32 call) and is NOT applied to
+		the persistent underlying storage.
+
+		InetChecksum differs from [InetChecksumSimple] in that it:
+
+			* Is MUCH better-suited/safer for concurrent operations - ALL
+				methods are concurrency-safe.
+			* Allows the data that is hashed to be recovered from a
+				sequential internal buffer. (See [InetChecksum.DisablePersist]
+				to disable the persistent internal buffer.)
+
+		At the cost of increased memory usage and additional cycles for mutexing.
+
+		Note that once persistence is disabled for an InetChecksum, it cannot be
+		re-enabled until/unless [InetChecksum.Reset] is called (which will reset
+		the persistence to enabled with a fresh buffer). Any data within the
+		persistent buffer will be removed if [InetChecksum.DisablePersist] is called.
+	*/
+	InetChecksum struct {
+		buf         bytes.Buffer
+		disabledBuf bool
+		aligned     bool
+		last        byte
+		sum         uint32
+		bufLock     sync.RWMutex
+		alignLock   sync.RWMutex
+		lastLock    sync.RWMutex
+		sumLock     sync.RWMutex
+	}
+
+	/*
+		InetChecksumSimple is like [InetChecksum], but with a few key differences.
+
+		It is MUCH much more performant/optimized for *single throughput* operations.
+		Because it also does not retain a buffer of what was hashed, it uses *far* less
+		memory over time.
+
+		However, the downside is it is NOT concurrency safe. There are no promises made
+		about safety or proper checksum ordering with concurrency for this type, but it
+		should have much better performance for non-concurrent use.
+
+		It behaves much more like a traditional [hash.Hash].
+	*/
+	InetChecksumSimple struct {
+		aligned bool
+		last    byte
+		sum     uint32
+	}
+)

remap/doc.go

@@ -0,0 +1,4 @@
+/*
+Package remap provides convenience functions around regular expressions, primarily offering maps for named capture groups.
+*/
+package remap

remap/funcs_remap.go

@@ -0,0 +1,488 @@
+package remap
+
+/*
+Map returns a map[string][]<match bytes> for regexes with named capture groups matched in bytes b.
+Note that this supports non-unique group names; [regexp.Regexp] allows for patterns with multiple groups
+using the same group name (though your IDE might complain; I know GoLand does).
+
+Each match for each group is in a slice keyed under that group name, with that slice
+ordered by the indexing done by the regex match itself.
+
+In summary, the parameters are as follows:
+
+# inclNoMatch
+
+If true, then attempt to return a non-nil matches (as long as b isn't nil).
+Group keys will be populated and explicitly defined as nil.
+
+For example, if a pattern
+
+	^(?P<g1>foo)(?P<g1>bar)(?P<g2>baz)$
+
+is provided but b does not match then matches will be:
+
+	map[string][][]byte{
+		"g1": nil,
+		"g2": nil,
+	}
+
+# inclNoMatchStrict
+
+If true (and inclNoMatch is true), instead of a single nil the group's values will be
+a slice of nil values explicitly matching the number of times the group name is specified
+in the pattern.
+
+For example, if a pattern:
+
+	^(?P<g1>foo)(?P<g1>bar)(?P<g2>baz)$
+
+is provided but b does not match then matches will be:
+
+	map[string][][]byte{
+		"g1": [][]byte{
+			nil,
+			nil,
+		},
+		"g2": [][]byte{
+			nil,
+		},
+	}
+
+# mustMatch
+
+If true, matches will be nil if the entirety of b does not match the pattern (and thus
+no capture groups matched) (overrides inclNoMatch) -- explicitly:
+
+	matches == nil
+
+Otherwise if false (and assuming inclNoMatch is false), matches will be:
+
+	map[string][][]byte{}{}
+
+# Condition Tree
+
+In detail, matches and/or its values may be nil or empty under the following condition tree:
+
+	IF b is nil:
+		THEN matches will always be nil
+	ELSE:
+		IF all of b does not match pattern
+			IF mustMuch is true
+				THEN matches == nil
+			ELSE
+				THEN matches == map[string][][]byte{} (non-nil but empty)
+		ELSE IF pattern has no named capture groups
+			IF inclNoMatch is true
+				THEN matches == map[string][][]byte{} (non-nil but empty)
+			ELSE
+				THEN matches == nil
+		ELSE
+			IF there are no named group matches
+				IF inclNoMatch is true
+					THEN matches is non-nil; matches[<group name>, ...] is/are defined but nil (_, ok = matches[<group name>]; ok == true)
+				ELSE
+					THEN matches == nil
+			ELSE
+				IF <group name> does not have a match
+					IF inclNoMatch is true
+						IF inclNoMatchStrict is true
+							THEN matches[<group name>] is defined and non-nil, but populated with placeholder nils
+								(matches[<group name>] == [][]byte{nil[, nil...]})
+						ELSE
+							THEN matches[<group name>] is guaranteed defined but may be nil (_, ok = matches[<group name>]; ok == true)
+					ELSE
+						THEN matches[<group name>] is not defined (_, ok = matches[<group name>]; ok == false)
+				ELSE
+					matches[<group name>] == []{<match>[, <match>...]}
+*/
+func (r *ReMap) Map(b []byte, inclNoMatch, inclNoMatchStrict, mustMatch bool) (matches map[string][][]byte) {
+
+	var ok bool
+	var mIdx int
+	var match []byte
+	var grpNm string
+	var names []string
+	var matchBytes [][]byte
+	var tmpMap map[string][][]byte = make(map[string][][]byte)
+
+	if b == nil {
+		return
+	}
+
+	names = r.Regexp.SubexpNames()
+	matchBytes = r.Regexp.FindSubmatch(b)
+
+	if matchBytes == nil {
+		// b does not match pattern
+		if !mustMatch {
+			matches = make(map[string][][]byte)
+		}
+		return
+	}
+
+	if names == nil || len(names) == 0 || len(names) == 1 {
+		/*
+			no named capture groups;
+			technically only the last condition would be the case.
+		*/
+		if inclNoMatch {
+			matches = make(map[string][][]byte)
+		}
+		return
+	}
+	names = names[1:]
+
+	if len(matchBytes) == 0 || len(matchBytes) == 1 {
+		/*
+			no submatches whatsoever.
+			*Technically* I don't think this condition can actually be reached.
+			This is more of a safe-return before we re-slice.
+		*/
+		matches = make(map[string][][]byte)
+		if inclNoMatch {
+			if len(names) >= 1 {
+				for _, grpNm = range names {
+					matches[grpNm] = nil
+				}
+			}
+		}
+		return
+	}
+	matchBytes = matchBytes[1:]
+
+	for mIdx, match = range matchBytes {
+		grpNm = names[mIdx]
+		/*
+			Thankfully, it's actually a build error if a pattern specifies a named
+			capture group with an empty name.
+			So we don't need to worry about accounting for that,
+			and can just skip over grpNm == "" (which is an *unnamed* capture group).
+		*/
+		if grpNm == "" {
+			continue
+		}
+
+		if match == nil {
+			// group did not match
+			if !inclNoMatch {
+				continue
+			}
+			if _, ok = tmpMap[grpNm]; !ok {
+				if !inclNoMatchStrict {
+					tmpMap[grpNm] = nil
+				} else {
+					tmpMap[grpNm] = [][]byte{nil}
+				}
+			} else {
+				if inclNoMatchStrict {
+					tmpMap[grpNm] = append(tmpMap[grpNm], nil)
+				}
+			}
+			continue
+		}
+
+		if _, ok = tmpMap[grpNm]; !ok {
+			tmpMap[grpNm] = make([][]byte, 0)
+		}
+		tmpMap[grpNm] = append(tmpMap[grpNm], match)
+	}
+
+	// This *technically* should be completely handled above.
+	if inclNoMatch {
+		for _, grpNm = range names {
+			if _, ok = tmpMap[grpNm]; !ok {
+				tmpMap[grpNm] = nil
+			}
+		}
+	}
+
+	if len(tmpMap) > 0 {
+		matches = tmpMap
+	}
+
+	return
+}
+
+/*
+MapString is exactly like ReMap.Map(), but operates on (and returns) strings instead.
+(matches will always be nil if s == “.)
+
+A small deviation, though; empty strings instead of nils (because duh) will occupy slice placeholders (if `inclNoMatchStrict` is specified).
+This unfortunately *does not provide any indication* if an empty string positively matched the pattern (a "hit") or if it was simply
+not matched at all (a "miss"). If you need definitive determination between the two conditions, it is instead recommended to either
+*not* use inclNoMatchStrict or to use ReMap.Map() instead and convert any non-nil values to strings after.
+
+Particularly:
+
+# inclNoMatch
+
+If true, then attempt to return a non-nil matches (as long as s isn't empty).
+Group keys will be populated and explicitly defined as nil.
+
+For example, if a pattern
+
+	^(?P<g1>foo)(?P<g1>bar)(?P<g2>baz)$
+
+is provided but s does not match then matches will be:
+
+	map[string][]string{
+		"g1": nil,
+		"g2": nil,
+	}
+
+# inclNoMatchStrict
+
+If true (and inclNoMatch is true), instead of a single nil the group's values will be
+a slice of eempty string values explicitly matching the number of times the group name is specified
+in the pattern.
+
+For example, if a pattern:
+
+	^(?P<g1>foo)(?P<g1>bar)(?P<g2>baz)$
+
+is provided but s does not match then matches will be:
+
+	map[string][]string{
+		"g1": []string{
+			"",
+			"",
+		},
+		"g2": []string{
+			"",
+		},
+	}
+
+# mustMatch
+
+If true, matches will be nil if the entirety of s does not match the pattern (and thus
+no capture groups matched) (overrides inclNoMatch) -- explicitly:
+
+	matches == nil
+
+Otherwise if false (and assuming inclNoMatch is false), matches will be:
+
+	map[string][]string{}{}
+
+# Condition Tree
+
+In detail, matches and/or its values may be nil or empty under the following condition tree:
+
+	IF s is empty:
+		THEN matches will always be nil
+	ELSE:
+		IF all of s does not match pattern
+			IF mustMuch is true
+				THEN matches == nil
+			ELSE
+				THEN matches == map[string][]string{} (non-nil but empty)
+		ELSE IF pattern has no named capture groups
+			IF inclNoMatch is true
+				THEN matches == map[string][]string{} (non-nil but empty)
+			ELSE
+				THEN matches == nil
+		ELSE
+			IF there are no named group matches
+				IF inclNoMatch is true
+					THEN matches is non-nil; matches[<group name>, ...] is/are defined but nil (_, ok = matches[<group name>]; ok == true)
+				ELSE
+					THEN matches == nil
+			ELSE
+				IF <group name> does not have a match
+					IF inclNoMatch is true
+						IF inclNoMatchStrict is true
+							THEN matches[<group name>] is defined and non-nil, but populated with placeholder nils
+								(matches[<group name>] == []string{""[, ""...]})
+						ELSE
+							THEN matches[<group name>] is guaranteed defined but may be nil (_, ok = matches[<group name>]; ok == true)
+					ELSE
+						THEN matches[<group name>] is not defined (_, ok = matches[<group name>]; ok == false)
+				ELSE
+					matches[<group name>] == []{<match>[, <match>...]}
+*/
+func (r *ReMap) MapString(s string, inclNoMatch, inclNoMatchStrict, mustMatch bool) (matches map[string][]string) {
+
+	var ok bool
+	var endIdx int
+	var startIdx int
+	var chunkIdx int
+	var grpNm string
+	var names []string
+	var matchStr string
+	/*
+		A slice of indices or index pairs.
+		For each element `e` in idxChunks,
+		* if `e` is nil, no group match.
+		* if len(e) == 1, only a single character was matched.
+		* otherwise len(e) == 2, the start and end of the match.
+	*/
+	var idxChunks [][]int
+	var matchIndices []int
+	var chunkIndices []int // always 2 elements; start pos and end pos
+	var tmpMap map[string][]string = make(map[string][]string)
+
+	/*
+		OK so this is a bit of a deviation.
+
+		It's not as straightforward as above, because there isn't an explicit way
+		like above to determine if a pattern was *matched as an empty string* vs.
+		*not matched*.
+
+		So instead do roundabout index-y things.
+	*/
+
+	if s == "" {
+		return
+	}
+	/*
+		I'm not entirely sure how serious they are about "the slice should not be modified"...
+
+		DO NOT sort or dedupe `names`! If the same name for groups is duplicated,
+		it will be duplicated here in proper order and the ordering is tied to
+		the ordering of matchIndices.
+	*/
+	names = r.Regexp.SubexpNames()[:]
+	matchIndices = r.Regexp.FindStringSubmatchIndex(s)
+
+	if matchIndices == nil {
+		// s does not match pattern at all.
+		if !mustMatch {
+			matches = make(map[string][]string)
+		}
+		return
+	}
+
+	if names == nil || len(names) <= 1 {
+		/*
+			No named capture groups;
+			technically only the last condition would be the case,
+			as (regexp.Regexp).SubexpNames() will ALWAYS at the LEAST
+			return a `[]string{""}`.
+		*/
+		if inclNoMatch {
+			matches = make(map[string][]string)
+		}
+		return
+	}
+
+	if len(matchIndices) == 0 || len(matchIndices) == 1 {
+		/*
+			No (sub)matches whatsoever.
+			*technically* I don't think this condition can actually be reached;
+			matchIndices should ALWAYS either be `nil` or len will be at LEAST 2,
+			and modulo 2 thereafter since they're PAIRS of indices...
+			Why they didn't just return a [][]int or [][2]int or something
+			instead of an []int, who knows.
+			But we're correcting that poor design.
+			This is more of a safe-return before we chunk the indices.
+		*/
+		matches = make(map[string][]string)
+		if inclNoMatch {
+			for _, grpNm = range names {
+				if grpNm != "" {
+					matches[grpNm] = nil
+				}
+			}
+		}
+		return
+	}
+
+	/*
+		A reslice of `matchIndices` could technically start at 2 (as long as `names` is sliced [1:])
+		because they're in pairs: []int{<start>, <end>, <start>, <end>, ...}
+		and the first pair is the entire pattern match (un-resliced names[0]).
+		Thus the len(matchIndices) == 2*len(names), *even* if you
+		Keep in mind that since the first element of names is removed,
+		the first pair here is skipped.
+		This provides a bit more consistent readability, though.
+	*/
+	idxChunks = make([][]int, len(names))
+	chunkIdx = 0
+	endIdx = 0
+	for startIdx = 0; endIdx < len(matchIndices); startIdx += 2 {
+		endIdx = startIdx + 2
+		// This technically should never happen.
+		if endIdx > len(matchIndices) {
+			endIdx = len(matchIndices)
+		}
+
+		chunkIndices = matchIndices[startIdx:endIdx]
+
+		if chunkIndices[0] == -1 || chunkIndices[1] == -1 {
+			// group did not match
+			chunkIndices = nil
+		} else {
+			if chunkIndices[0] == chunkIndices[1] {
+				chunkIndices = []int{chunkIndices[0]}
+			} else {
+				chunkIndices = matchIndices[startIdx:endIdx]
+			}
+		}
+		idxChunks[chunkIdx] = chunkIndices
+		chunkIdx++
+	}
+
+	// Now associate with names and pull the string sequence.
+	for chunkIdx, chunkIndices = range idxChunks {
+		grpNm = names[chunkIdx]
+		/*
+			Thankfully, it's actually a build error if a pattern specifies a named
+			capture group with an empty name.
+			So we don't need to worry about accounting for that,
+			and can just skip over grpNm == ""
+			(which is either an *unnamed* capture group
+			OR the first element in `names`, which is always
+			the entire match).
+		*/
+		if grpNm == "" {
+			continue
+		}
+
+		if chunkIndices == nil || len(chunkIndices) == 0 {
+			// group did not match
+			if !inclNoMatch {
+				continue
+			}
+			if _, ok = tmpMap[grpNm]; !ok {
+				if !inclNoMatchStrict {
+					tmpMap[grpNm] = nil
+				} else {
+					tmpMap[grpNm] = []string{""}
+				}
+			} else {
+				if inclNoMatchStrict {
+					tmpMap[grpNm] = append(tmpMap[grpNm], "")
+				}
+			}
+			continue
+		}
+
+		switch len(chunkIndices) {
+		case 1:
+			// Single character
+			matchStr = string(s[chunkIndices[0]])
+		case 2:
+			// Multiple characters
+			matchStr = s[chunkIndices[0]:chunkIndices[1]]
+		}
+
+		if _, ok = tmpMap[grpNm]; !ok {
+			tmpMap[grpNm] = make([]string, 0)
+		}
+		tmpMap[grpNm] = append(tmpMap[grpNm], matchStr)
+	}
+
+	// This *technically* should be completely handled above.
+	if inclNoMatch {
+		for _, grpNm = range names {
+			if _, ok = tmpMap[grpNm]; !ok {
+				tmpMap[grpNm] = nil
+			}
+		}
+	}
+
+	if len(tmpMap) > 0 {
+		matches = tmpMap
+	}
+
+	return
+}

remap/types.go

@@ -0,0 +1,27 @@
+package remap
+
+import (
+	"regexp"
+)
+
+type (
+	// ReMap provides some map-related functions around a regexp.Regexp.
+	ReMap struct {
+		*regexp.Regexp
+	}
+
+	// TODO?
+	/*
+		ExplicitStringMatch is used with ReMap.MapStringExplicit to indicate if a
+		capture group result is a hit (a group matched, but e.g. the match value is empty string)
+		or not (a group did not match).
+	*/
+	/*
+		ExplicitStringMatch struct {
+			Group   string
+			IsMatch bool
+			Value   string
+		}
+
+	*/
+)

structutils/consts.go

@@ -0,0 +1,5 @@
+package structutils
+
+const (
+	TagMapTrim tagMapOpt = iota
+)

structutils/funcs.go

@@ -0,0 +1,362 @@
+/*
+   GoUtils - a library to assist with various Golang-related functions
+   Copyright (C) 2020  Brent Saner
+
+   This program is free software: you can redistribute it and/or modify
+   it under the terms of the GNU General Public License as published by
+   the Free Software Foundation, either version 3 of the License, or
+   (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+
+package structutils
+
+import (
+	`reflect`
+	`strings`
+)
+
+/*
+	TagToBoolMap takes struct field `field` and tag name `tagName`,
+	 optionally with options `opts`, and returns a map of the tag values.
+	The tag value string is assumed to be in the form of:
+		option[,option,option...]
+	and returns a map[string]bool (map[option]true).
+
+	If field does not have tag tagName, m will be nil.
+
+	See the TagMap* constants for opts.
+*/
+func TagToBoolMap(field reflect.StructField, tagName string, opts ...tagMapOpt) (m map[string]bool) {
+
+	var s string
+	var optSplit []string
+	var tagOpts map[tagMapOpt]bool = getTagMapOpts(opts)
+
+	s = field.Tag.Get(tagName)
+
+	if strings.TrimSpace(s) == "" {
+		return
+	}
+
+	optSplit = strings.Split(s, ",")
+	if optSplit == nil || len(optSplit) == 0 {
+		return
+	}
+	m = make(map[string]bool)
+	for _, o := range optSplit {
+		if tagOpts[TagMapTrim] {
+			o = strings.TrimSpace(o)
+		}
+		m[o] = true
+	}
+
+	return
+}
+
+/*
+	TagToBoolMapWithValue is like TagToBoolMap but additionally assumes the first value is an "identifier".
+	The tag value string is assumed to be in the form of:
+		value,option[,option,option...]
+	and returns a map[string]bool (map[option]true) with the value.
+*/
+func TagToBoolMapWithValue(field reflect.StructField, tagName string, opts ...tagMapOpt) (value string, m map[string]bool) {
+
+	var s string
+	var optSplit []string
+	var tagOpts map[tagMapOpt]bool = getTagMapOpts(opts)
+
+	s = field.Tag.Get(tagName)
+
+	if strings.TrimSpace(s) == "" {
+		return
+	}
+
+	optSplit = strings.Split(s, ",")
+	if optSplit == nil || len(optSplit) == 0 {
+		return
+	}
+	m = make(map[string]bool)
+	for idx, o := range optSplit {
+		if idx == 0 {
+			if tagOpts[TagMapTrim] {
+				o = strings.TrimSpace(o)
+			}
+			value = o
+			continue
+		}
+		if tagOpts[TagMapTrim] {
+			o = strings.TrimSpace(o)
+		}
+		m[o] = true
+	}
+
+	return
+}
+
+/*
+	TagToMixedMap combines TagToBoolMap and TagToStringMap.
+	It takes struct field `field` and tag name `tagName`,
+	and returns all single-value options in mapBool, and all key/value options in mapString.
+
+	If field does not have tag tagName, m will be nil.
+
+	See the TagMap* constants for opts.
+*/
+func TagToMixedMap(field reflect.StructField, tagName string, opts ...tagMapOpt) (mapBool map[string]bool, mapString map[string]string) {
+
+	var s string
+	var valStr string
+	var split []string
+	var kvSplit []string
+	var valSplit []string
+	var k string
+	var v string
+	var tagOpts map[tagMapOpt]bool = getTagMapOpts(opts)
+
+	s = field.Tag.Get(tagName)
+
+	if strings.TrimSpace(s) == "" {
+		return
+	}
+
+	split = strings.Split(s, ",")
+	if split == nil || len(split) == 0 {
+		return
+	}
+	mapBool = make(map[string]bool)
+	mapString = make(map[string]string)
+	for _, valStr = range split {
+		if strings.Contains(valStr, "=") {
+			kvSplit = strings.SplitN(valStr, "=", 2)
+			if kvSplit == nil || len(kvSplit) == 0 {
+				continue
+			}
+			k = valSplit[0]
+			switch len(valSplit) {
+			case 1:
+				v = ""
+			case 2:
+				v = kvSplit[1]
+			}
+			if tagOpts[TagMapTrim] {
+				k = strings.TrimSpace(k)
+				v = strings.TrimSpace(v)
+			}
+			mapString[k] = v
+		} else {
+			if tagOpts[TagMapTrim] {
+				valStr = strings.TrimSpace(valStr)
+			}
+			mapBool[valStr] = true
+		}
+	}
+
+	return
+}
+
+/*
+	TagToMixedMapWithValue combines TagToBoolMapWithValue and TagToStringMapWithValue.
+	It takes struct field `field` and tag name `tagName`,
+	and returns all single-value options in mapBool, and all key/value options in mapString
+	along with the first single-value option as value..
+
+	If field does not have tag tagName, m will be nil.
+
+	See the TagMap* constants for opts.
+*/
+func TagToMixedMapWithValue(field reflect.StructField, tagName string, opts ...tagMapOpt) (value string, mapBool map[string]bool, mapString map[string]string) {
+
+	var s string
+	var idx int
+	var valStr string
+	var split []string
+	var kvSplit []string
+	var valSplit []string
+	var k string
+	var v string
+	var tagOpts map[tagMapOpt]bool = getTagMapOpts(opts)
+
+	s = field.Tag.Get(tagName)
+
+	if strings.TrimSpace(s) == "" {
+		return
+	}
+
+	split = strings.Split(s, ",")
+	if split == nil || len(split) == 0 {
+		return
+	}
+	mapBool = make(map[string]bool)
+	mapString = make(map[string]string)
+	for idx, valStr = range split {
+		if idx == 0 {
+			if tagOpts[TagMapTrim] {
+				valStr = strings.TrimSpace(valStr)
+			}
+			value = valStr
+			continue
+		}
+		if strings.Contains(valStr, "=") {
+			kvSplit = strings.SplitN(valStr, "=", 2)
+			if kvSplit == nil || len(kvSplit) == 0 {
+				continue
+			}
+			k = valSplit[0]
+			switch len(valSplit) {
+			case 1:
+				v = ""
+			case 2:
+				v = kvSplit[1]
+			}
+			if tagOpts[TagMapTrim] {
+				k = strings.TrimSpace(k)
+				v = strings.TrimSpace(v)
+			}
+			mapString[k] = v
+		} else {
+			if tagOpts[TagMapTrim] {
+				valStr = strings.TrimSpace(valStr)
+			}
+			mapBool[valStr] = true
+		}
+	}
+
+	return
+}
+
+/*
+	TagToStringMap takes struct field `field` and tag name `tagName`,
+	 optionally with options `opts`, and returns a map of the tag values.
+	The tag value string is assumed to be in the form of:
+		key=value[,key=value,key=value...]
+	and returns a map[string]string (map[key]value).
+	It is proccessed in order; later duplicate keys overwrite previous ones.
+
+	If field does not have tag tagName, m will be nil.
+
+	If only a key is provided with no value, the value in the map will be an empty string.
+	(e.g. "foo,bar=baz" => map[string]string{"foo": "", "bar: "baz"}
+
+	See the TagMap* constants for opts.
+*/
+func TagToStringMap(field reflect.StructField, tagName string, opts ...tagMapOpt) (m map[string]string) {
+
+	var s string
+	var kvSplit []string
+	var valSplit []string
+	var k string
+	var v string
+	var tagOpts map[tagMapOpt]bool = getTagMapOpts(opts)
+
+	s = field.Tag.Get(tagName)
+
+	if strings.TrimSpace(s) == "" {
+		return
+	}
+
+	kvSplit = strings.Split(s, ",")
+	if kvSplit == nil || len(kvSplit) == 0 {
+		return
+	}
+	for _, kv := range kvSplit {
+		valSplit = strings.SplitN(kv, "=", 2)
+		if valSplit == nil || len(valSplit) == 0 {
+			continue
+		}
+		k = valSplit[0]
+		switch len(valSplit) {
+		case 1:
+			v = ""
+		case 2:
+			v = valSplit[1]
+			// It's not possible to have more than 2.
+		}
+		if m == nil {
+			m = make(map[string]string)
+		}
+		if tagOpts[TagMapTrim] {
+			k = strings.TrimSpace(k)
+			v = strings.TrimSpace(v)
+		}
+		m[k] = v
+	}
+
+	return
+}
+
+/*
+	TagToStringMapWithValue is like TagToStringMap but additionally assumes the first value is an "identifier".
+	The tag value string is assumed to be in the form of:
+		value,key=value[,key=value,key=value...]
+	and returns a map[string]string (map[key]value) with the value.
+*/
+func TagToStringMapWithValue(field reflect.StructField, tagName string, opts ...tagMapOpt) (value string, m map[string]string) {
+
+	var s string
+	var kvSplit []string
+	var valSplit []string
+	var k string
+	var v string
+	var tagOpts map[tagMapOpt]bool = getTagMapOpts(opts)
+
+	s = field.Tag.Get(tagName)
+
+	if strings.TrimSpace(s) == "" {
+		return
+	}
+
+	kvSplit = strings.Split(s, ",")
+	if kvSplit == nil || len(kvSplit) == 0 {
+		return
+	}
+	for idx, kv := range kvSplit {
+		if idx == 0 {
+			if tagOpts[TagMapTrim] {
+				kv = strings.TrimSpace(kv)
+			}
+			value = kv
+			continue
+		}
+		valSplit = strings.SplitN(kv, "=", 2)
+		if valSplit == nil || len(valSplit) == 0 {
+			continue
+		}
+		k = valSplit[0]
+		switch len(valSplit) {
+		case 1:
+			v = ""
+		case 2:
+			v = valSplit[1]
+			// It's not possible to have more than 2.
+		}
+		if m == nil {
+			m = make(map[string]string)
+		}
+		if tagOpts[TagMapTrim] {
+			k = strings.TrimSpace(k)
+			v = strings.TrimSpace(v)
+		}
+		m[k] = v
+	}
+
+	return
+}
+
+func getTagMapOpts(opts []tagMapOpt) (optMap map[tagMapOpt]bool) {
+
+	optMap = make(map[tagMapOpt]bool)
+
+	if opts == nil {
+		return
+	}
+
+	return
+}

structutils/types.go

@@ -0,0 +1,5 @@
+package structutils
+
+type (
+	tagMapOpt uint8
+)