features: envs.GetFirst{,WithRef}, paths.GetFirst{,WithRef}

paths/funcs.go

@@ -82,10 +82,81 @@ func ExpandHome(path *string) (err error) {
 	return
 }
 
+/*
+	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).
+
+	If no path exists, ok will be false.
+
+	As always, results are not guaranteed due to permissions, etc.
+	potentially returning an inaccurate result.
+
+	This is a thin wrapper around GetFirstWithRef.
+*/
+func GetFirst(paths []string) (content []byte, isDir, ok bool) {
+
+	content, isDir, ok, _ = GetFirstWithRef(paths)
+
+	return
+}
+
+/*
+	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.
+
+	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) {
+
+	var locPaths []string
+	var exists bool
+	var stat os.FileInfo
+	var err error
+
+	idx = -1
+	// We have to be a little less cavalier about this.
+	if paths == nil {
+		return
+	}
+	locPaths = make([]string, len(paths))
+	locPaths = paths[:] // Create an explicit copy so we don't modify paths.
+	for i, p := range locPaths {
+		if exists, stat, err = RealPathExistsStat(&p); err != nil {
+			err = nil
+			continue
+		}
+		if !exists {
+			continue
+		}
+		isDir = stat.IsDir()
+		if !isDir {
+			if content, err = os.ReadFile(p); err != nil {
+				continue
+			}
+		}
+		ok = true
+		idx = i
+		return
+	}
+
+	return
+}
+
 /*
 MakeDirIfNotExist will create a directory at a given path if it doesn't exist.
 
 See also the documentation for RealPath.
+
+This is a bit more sane option than os.MkdirAll as it will normalize paths a little better.
 */
 func MakeDirIfNotExist(path string) (err error) {