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

envs/funcs.go

@@ -61,6 +61,59 @@ func GetEnvMapNative() (envMap map[string]interface{}) {
 	return
 }
 
+/*
+	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:
+
+		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:
+
+		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.
+
+	It is a thin wrapper around GetFirstWithRef.
+*/
+func GetFirst(varNames []string) (val string, ok bool) {
+
+	val, ok, _ = GetFirstWithRef(varNames)
+
+	return
+}
+
+/*
+	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"})
+
+	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.
+*/
+func GetFirstWithRef(varNames []string) (val string, ok bool, idx int) {
+
+	idx = -1
+
+	for i, vn := range varNames {
+		if HasEnv(vn) {
+			ok = true
+			idx = i
+			val = os.Getenv(vn)
+			return
+		}
+	}
+
+	return
+}
+
 /*
 	GetPidEnvMap will only work on *NIX-like systems with procfs.
 	It gets the environment variables of a given process' PID.