v1.13.3

ADDED:
* envs.GetEnvErr(), envs.GetEnvErrNoBlank(), envs.EnvErrNoVal
  This allows error-returned env vars for nonexistent/empty values.

envs/funcs.go

@@ -1,27 +1,27 @@
 package envs
 
 import (
-	`bytes`
-	`errors`
-	`fmt`
-	`io/ioutil`
-	`os`
-	`reflect`
-	`strings`
-	`sync`
+	"bytes"
+	"errors"
+	"fmt"
+	"io/ioutil"
+	"os"
+	"reflect"
+	"strings"
+	"sync"
 
-	`r00t2.io/goutils/multierr`
-	`r00t2.io/goutils/structutils`
-	`r00t2.io/sysutils/errs`
-	`r00t2.io/sysutils/internal`
-	`r00t2.io/sysutils/paths`
+	"r00t2.io/goutils/multierr"
+	"r00t2.io/goutils/structutils"
+	"r00t2.io/sysutils/errs"
+	"r00t2.io/sysutils/internal"
+	"r00t2.io/sysutils/paths"
 )
 
 /*
-	DefEnv operates like Python's .get() method on dicts (maps);
-	if the environment variable specified by key does not exist/is not specified,
-	then the value specified by fallback will be returned instead
-	otherwise key's value is returned.
+DefEnv operates like Python's .get() method on dicts (maps);
+if the environment variable specified by key does not exist/is not specified,
+then the value specified by fallback will be returned instead
+otherwise key's value is returned.
 */
 func DefEnv(key, fallback string) (value string) {
 
@@ -45,6 +45,54 @@ func DefEnvBlank(key, fallback string) (value string) {
 	return
 }
 
+// GetEnvErr returns the value of key if it exists. If it does not exist, err will be an EnvErrNoVal.
+func GetEnvErr(key string) (value string, err error) {
+
+	var exists bool
+
+	if value, exists = os.LookupEnv(key); !exists {
+		err = &EnvErrNoVal{
+			VarName: key,
+		}
+		return
+	}
+
+	return
+}
+
+/*
+GetEnvErrNoBlank behaves exactly like GetEnvErr with the
+additional stipulation that the value must not be empty.
+
+An error for a value that is non-empty but whitespace only (e.g. VARNM="\t")
+can be returned if ignoreWhitespace == true.
+
+(If it is, an EnvErrNoVal will also be returned.)
+*/
+func GetEnvErrNoBlank(key string, ignoreWhitespace bool) (value string, err error) {
+
+	var exists bool
+	var e *EnvErrNoVal = &EnvErrNoVal{
+		VarName:             key,
+		WasRequiredNonEmpty: true,
+		IgnoreWhiteSpace:    ignoreWhitespace,
+	}
+
+	if value, exists = os.LookupEnv(key); !exists {
+		err = e
+		return
+	} else {
+		e.WasFound = true
+		e.WasWhitespace = (strings.TrimSpace(value) == "") && (value != "")
+		if ignoreWhitespace && e.WasWhitespace {
+			err = e
+			return
+		}
+	}
+
+	return
+}
+
 // GetEnvMap returns a map of all environment variables. All values are strings.
 func GetEnvMap() (envVars map[string]string) {
 
@@ -56,18 +104,18 @@ func GetEnvMap() (envVars map[string]string) {
 }
 
 /*
-	GetEnvMapNative returns a map of all environment variables, but attempts to "nativize" them.
-	All values are interfaces. It is up to the caller to typeswitch them to proper types.
+GetEnvMapNative returns a map of all environment variables, but attempts to "nativize" them.
+All values are interfaces. It is up to the caller to typeswitch them to proper types.
 
-	Note that the PATH/Path environment variable (for *Nix and Windows, respectively) will be
-	a []string (as per GetPathEnv). No other env vars, even if they contain os.PathListSeparator,
-	will be transformed to a slice or the like.
-	If an error occurs during parsing the path env var, it will be rendered	as a string.
+Note that the PATH/Path environment variable (for *Nix and Windows, respectively) will be
+a []string (as per GetPathEnv). No other env vars, even if they contain os.PathListSeparator,
+will be transformed to a slice or the like.
+If an error occurs during parsing the path env var, it will be rendered	as a string.
 
-	All number types will attempt to be their 64-bit version (i.e. int64, uint64, float64, etc.).
+All number types will attempt to be their 64-bit version (i.e. int64, uint64, float64, etc.).
 
-	If a type cannot be determined for a value, its string form will be used
-	(as it would be found in GetEnvMap).
+If a type cannot be determined for a value, its string form will be used
+(as it would be found in GetEnvMap).
 */
 func GetEnvMapNative() (envMap map[string]interface{}) {
 
@@ -79,24 +127,24 @@ func GetEnvMapNative() (envMap map[string]interface{}) {
 }
 
 /*
-	GetFirst gets the first instance if populated/set occurrence of varNames.
+GetFirst gets the first instance if populated/set occurrence of varNames.
 
-	For example, if you have three potential env vars, FOO, FOOBAR, FOOBARBAZ,
-	and want to follow the logic flow of:
+For example, if you have three potential env vars, FOO, FOOBAR, FOOBARBAZ,
+and want to follow the logic flow of:
 
-		1.) Check if FOO is set. If not,
-		2.) Check if FOOBAR is set. If not,
-		3.) Check if FOOBARBAZ is set.
+	1.) Check if FOO is set. If not,
+	2.) Check if FOOBAR is set. If not,
+	3.) Check if FOOBARBAZ is set.
 
-	Then this would be specified as:
+Then this would be specified as:
 
-		GetFirst([]string{"FOO", "FOOBAR", "FOOBARBAZ"})
+	GetFirst([]string{"FOO", "FOOBAR", "FOOBARBAZ"})
 
-	If val is "" and ok is true, this means that one of the specified variable names IS
-	set but is set to an empty value. If ok is false, none of the specified variables
-	are set.
+If val is "" and ok is true, this means that one of the specified variable names IS
+set but is set to an empty value. If ok is false, none of the specified variables
+are set.
 
-	It is a thin wrapper around GetFirstWithRef.
+It is a thin wrapper around GetFirstWithRef.
 */
 func GetFirst(varNames []string) (val string, ok bool) {
 
@@ -106,14 +154,14 @@ func GetFirst(varNames []string) (val string, ok bool) {
 }
 
 /*
-	GetFirstWithRef behaves exactly like GetFirst, but with an additional returned value, idx,
-	which specifies the index in varNames in which a set variable was found. e.g. if:
+GetFirstWithRef behaves exactly like GetFirst, but with an additional returned value, idx,
+which specifies the index in varNames in which a set variable was found. e.g. if:
 
-		GetFirstWithRef([]string{"FOO", "FOOBAR", "FOOBAZ"})
+	GetFirstWithRef([]string{"FOO", "FOOBAR", "FOOBAZ"})
 
-	is called and FOO is not set but FOOBAR is, idx will be 1.
+is called and FOO is not set but FOOBAR is, idx will be 1.
 
-	If ok is false, idx will always be -1 and should be ignored.
+If ok is false, idx will always be -1 and should be ignored.
 */
 func GetFirstWithRef(varNames []string) (val string, ok bool, idx int) {
 
@@ -148,8 +196,8 @@ func GetPathEnv() (pathList []string, err error) {
 }
 
 /*
-	GetPidEnvMap will only work on *NIX-like systems with procfs.
-	It gets the environment variables of a given process' PID.
+GetPidEnvMap will only work on *NIX-like systems with procfs.
+It gets the environment variables of a given process' PID.
 */
 func GetPidEnvMap(pid uint32) (envMap map[string]string, err error) {
 
@@ -187,10 +235,10 @@ func GetPidEnvMap(pid uint32) (envMap map[string]string, err error) {
 }
 
 /*
-	GetPidEnvMapNative, like GetEnvMapNative, returns a map of all environment variables, but attempts to "nativize" them.
-	All values are interfaces. It is up to the caller to typeswitch them to proper types.
+GetPidEnvMapNative, like GetEnvMapNative, returns a map of all environment variables, but attempts to "nativize" them.
+All values are interfaces. It is up to the caller to typeswitch them to proper types.
 
-	See the documentation for GetEnvMapNative for details.
+See the documentation for GetEnvMapNative for details.
 */
 func GetPidEnvMapNative(pid uint32) (envMap map[string]interface{}, err error) {
 
@@ -206,11 +254,11 @@ func GetPidEnvMapNative(pid uint32) (envMap map[string]interface{}, err error) {
 }
 
 /*
-	HasEnv is much like os.LookupEnv, but only returns a boolean for
-	if the environment variable key exists or not.
+HasEnv is much like os.LookupEnv, but only returns a boolean for
+if the environment variable key exists or not.
 
-	This is useful anywhere you may need to set a boolean in a func call
-	depending on the *presence* of an env var or not.
+This is useful anywhere you may need to set a boolean in a func call
+depending on the *presence* of an env var or not.
 */
 func HasEnv(key string) (envIsSet bool) {
 
@@ -220,28 +268,28 @@ func HasEnv(key string) (envIsSet bool) {
 }
 
 /*
-	Interpolate takes one of:
+Interpolate takes one of:
 
-		- a string (pointer only)
-		- a struct (pointer only)
-		- a map (applied to both keys *and* values)
-		- a slice
+  - a string (pointer only)
+  - a struct (pointer only)
+  - a map (applied to both keys *and* values)
+  - a slice
 
-	and performs variable substitution on strings from environment variables.
+and performs variable substitution on strings from environment variables.
 
-	It supports both UNIX/Linux/POSIX syntax formats (e.g. $VARNAME, ${VARNAME}) and,
-	if on Windows, it *additionally* supports the EXPAND_SZ format (e.g. %VARNAME%).
+It supports both UNIX/Linux/POSIX syntax formats (e.g. $VARNAME, ${VARNAME}) and,
+if on Windows, it *additionally* supports the EXPAND_SZ format (e.g. %VARNAME%).
 
-	For structs, the tag name used can be changed by setting the StructTagInterpolate
-	variable in this submodule; the default is `envsub`.
-	If the tag value is "-", the field will be skipped.
-	For map fields within structs etc., the default is to apply interpolation to both keys and values.
-	All other tag value(s) are ignored.
+For structs, the tag name used can be changed by setting the StructTagInterpolate
+variable in this submodule; the default is `envsub`.
+If the tag value is "-", the field will be skipped.
+For map fields within structs etc., the default is to apply interpolation to both keys and values.
+All other tag value(s) are ignored.
 
-	For maps and slices, Interpolate will recurse into values (e.g. [][]string will work as expected).
+For maps and slices, Interpolate will recurse into values (e.g. [][]string will work as expected).
 
-	If s is nil, no interpolation will be performed. No error will be returned.
-	If s is not a valid/supported type, no interpolation will be performed. No error will be returned.
+If s is nil, no interpolation will be performed. No error will be returned.
+If s is not a valid/supported type, no interpolation will be performed. No error will be returned.
 */
 func Interpolate[T any](s T) (err error) {
 
@@ -293,16 +341,16 @@ func Interpolate[T any](s T) (err error) {
 }
 
 /*
-	InterpolateString takes (a pointer to) a struct or string and performs variable substitution on it
-	from environment variables.
+InterpolateString takes (a pointer to) a struct or string and performs variable substitution on it
+from environment variables.
 
-	It supports both UNIX/Linux/POSIX syntax formats (e.g. $VARNAME, ${VARNAME}) and,
-	if on Windows, it *additionally* supports the EXPAND_SZ format (e.g. %VARNAME%).
+It supports both UNIX/Linux/POSIX syntax formats (e.g. $VARNAME, ${VARNAME}) and,
+if on Windows, it *additionally* supports the EXPAND_SZ format (e.g. %VARNAME%).
 
-	If s is nil, nothing will be done and err will be ErrNilPtr.
+If s is nil, nothing will be done and err will be ErrNilPtr.
 
-	This is a standalone function that is much more performant than Interpolate
-	at the cost of rigidity.
+This is a standalone function that is much more performant than Interpolate
+at the cost of rigidity.
 */
 func InterpolateString(s *string) (err error) {
 

envs/funcs_enverrnoval.go

@@ -0,0 +1,27 @@
+package envs
+
+import (
+	"strings"
+)
+
+// Error conforms to a stdlib error interface.
+func (e *EnvErrNoVal) Error() (errStr string) {
+
+	var sb *strings.Builder = new(strings.Builder)
+
+	sb.WriteString("the variable '")
+	sb.WriteString(e.VarName)
+	sb.WriteString("' was ")
+	if sb.WasFound {
+		sb.WriteString("found")
+	} else {
+		sb.WriteString("not found")
+	}
+	if e.WasRequiredNonEmpty && e.WasFound {
+		sb.WriteString(" but is empty and was required to be non-empty") 
+	}
+
+	errStr = sb.String()
+
+	return
+}

envs/types.go

@@ -0,0 +1,20 @@
+package envs
+
+type (
+	/*
+		EnvErrNoVal is an error containing the variable that does not exist
+		(and information surrounding the errored state).
+	*/
+	EnvErrNoVal struct {
+		// VarName is the variable name/key name originally specified in the function call.
+		VarName             string `json:"var" toml:"VariableName" yaml:"Variable Name/Key" xml:"key,attr"`
+		// WasFound is only used for GetEnvErrNoBlank(). It is true if the variable was found/populated.
+		WasFound            bool   `json:"found" toml:"Found" yaml:"Found" xml:"found,attr"`
+		// WasRequiredNonEmpty indicates that this error was returned in a context where a variable was required to be non-empty (e.g. via GetEnvErrNoBlank()) but was empty.
+		WasRequiredNonEmpty bool   `json:"reqd_non_empty" toml:"RequiredNonEmpty" yaml:"Required Non-Empty" xml:"reqNonEmpty,attr"`
+		// IgnoreWhitespace is true if the value was found but its evaluation was done against a whitestripped version.
+		IgnoreWhitespace    bool   `json:"ignore_ws" toml:"IgnoreWhitespace" yaml:"Ignore Whitespace" xml:"ignoreWhitespace,attr"`
+		// WasWhitespace is true if the value was whitespace-only.
+		WasWhitespace       bool   `json:"was_ws" toml:"WasWhitespace" yaml:"Was Whitespace Only" xml:"wasWhitespace,attr"`
+	}
+)

paths/funcs.go

@@ -19,22 +19,23 @@
 package paths
 
 import (
-	`context`
+	"context"
 	"errors"
 	"fmt"
 	"io/fs"
 	"os"
 	"os/user"
+	"path"
 	"path/filepath"
-	`sort`
+	"sort"
 	"strings"
-	`sync`
-	`time`
+	"sync"
+	"time"
 
 	// "syscall"
 
-	`github.com/djherbis/times`
-	`r00t2.io/goutils/bitmask`
+	"github.com/djherbis/times"
+	"r00t2.io/goutils/bitmask"
 )
 
 /*
@@ -91,21 +92,21 @@ func ExpandHome(path *string) (err error) {
 }
 
 /*
-	GetFirst is the file equivalent of envs.GetFirst.
+GetFirst is the file equivalent of envs.GetFirst.
 
-	It iterates through paths, normalizing them along the way
-	(so abstracted paths such as ~/foo/bar.txt and relative paths
-	such as bar/baz.txt will still work), and returns the content
-	of the first found existing file. If the first found path
-	is a directory, content will be nil but isDir will be true
-	(as will ok).
+It iterates through paths, normalizing them along the way
+(so abstracted paths such as ~/foo/bar.txt and relative paths
+such as bar/baz.txt will still work), and returns the content
+of the first found existing file. If the first found path
+is a directory, content will be nil but isDir will be true
+(as will ok).
 
-	If no path exists, ok will be false.
+If no path exists, ok will be false.
 
-	As always, results are not guaranteed due to permissions, etc.
-	potentially returning an inaccurate result.
+As always, results are not guaranteed due to permissions, etc.
+potentially returning an inaccurate result.
 
-	This is a thin wrapper around GetFirstWithRef.
+This is a thin wrapper around GetFirstWithRef.
 */
 func GetFirst(paths []string) (content []byte, isDir, ok bool) {
 
@@ -115,13 +116,13 @@ func GetFirst(paths []string) (content []byte, isDir, ok bool) {
 }
 
 /*
-	GetFirstWithRef is the file equivalent of envs.GetFirstWithRef.
+GetFirstWithRef is the file equivalent of envs.GetFirstWithRef.
 
-	It behaves exactly like GetFirst, but with an additional returned value, idx,
-	which specifies the index in paths in which a path was found.
+It behaves exactly like GetFirst, but with an additional returned value, idx,
+which specifies the index in paths in which a path was found.
 
-	As always, results are not guaranteed due to permissions, etc.
-	potentially returning an inaccurate result.
+As always, results are not guaranteed due to permissions, etc.
+potentially returning an inaccurate result.
 */
 func GetFirstWithRef(paths []string) (content []byte, isDir, ok bool, idx int) {
 
@@ -221,6 +222,68 @@ func RealPath(path *string) (err error) {
 	return
 }
 
+/*
+RealPathJoin combines RealPath with (path).Join.
+
+If dst is nil, then rootPath will be updated with the new value.
+You probably don't want that.
+*/
+func RealPathJoin(rootPath, dst *string, subPaths ...string) (err error) {
+
+	var newPath string
+	var realDst *string
+
+	if err = RealPath(rootPath); err != nil {
+		return
+	}
+
+	if dst == nil {
+		realDst = rootPath
+	} else {
+		realDst = dst
+	}
+
+	newPath = path.Join(append([]string{*rootPath}, subPaths...)...)
+	if err = RealPath(&newPath); err != nil {
+		return
+	}
+
+	*realDst = newPath
+
+	return
+}
+
+/*
+RealPathJoinSys combines RealPath with (path/filepath).Join.
+
+If dst is nil, then path will be updated with the new value.
+You probably don't want that.
+*/
+func RealPathJoinSys(path, dst *string, subPaths ...string) (err error) {
+
+	var newPath string
+	var realDst *string
+
+	if err = RealPath(path); err != nil {
+		return
+	}
+
+	if dst == nil {
+		realDst = path
+	} else {
+		realDst = dst
+	}
+
+	newPath = filepath.Join(append([]string{*path}, subPaths...)...)
+	if err = RealPath(&newPath); err != nil {
+		return
+	}
+
+	*realDst = newPath
+
+	return
+}
+
 /*
 RealPathExists is like RealPath, but will also return a boolean as to whether the path
 actually exists or not.
@@ -327,14 +390,14 @@ func SearchFsPaths(matcher FsSearchCriteria) (found, miss []*FsSearchResult, err
 }
 
 /*
-	SearchFsPathsAsync is exactly like SearchFsPaths, but dispatches off concurrent
-	workers for the filtering logic instead of performing iteratively/recursively.
-	It may, in some cases, be *slightly more* performant and *slightly less* in others.
-	Note that unlike SearchFsPaths, the results written to the
-	FsSearchCriteriaAsync.ResChan are not guaranteed to be in any predictable order.
+SearchFsPathsAsync is exactly like SearchFsPaths, but dispatches off concurrent
+workers for the filtering logic instead of performing iteratively/recursively.
+It may, in some cases, be *slightly more* performant and *slightly less* in others.
+Note that unlike SearchFsPaths, the results written to the
+FsSearchCriteriaAsync.ResChan are not guaranteed to be in any predictable order.
 
-	All channels are expected to have already been initialized by the caller.
-	They will not be closed by this function.
+All channels are expected to have already been initialized by the caller.
+They will not be closed by this function.
 */
 func SearchFsPathsAsync(matcher FsSearchCriteriaAsync) {
 
@@ -436,11 +499,11 @@ func SearchFsPathsAsync(matcher FsSearchCriteriaAsync) {
 }
 
 /*
-	filterTimes checks a times.Timespec of a file using:
-		* an age specified by the caller
-		* an ageType bitmask for types of times to compare
-		* an olderThan bool (if false, the file must be younger than)
-		* an optional "now" timestamp for the age derivation.
+filterTimes checks a times.Timespec of a file using:
+  - an age specified by the caller
+  - an ageType bitmask for types of times to compare
+  - an olderThan bool (if false, the file must be younger than)
+  - an optional "now" timestamp for the age derivation.
 */
 func filterTimes(tspec times.Timespec, age *time.Duration, ageType *pathTimeType, olderThan bool, now *time.Time) (include bool) {