+#hmmm: extract to core somewhere...
+# locates a parent directory of a certain name, if possible. returns success
+# (as zero) if the directory was found, and failure if there was no parent
+# named as requested. sets a global variable PARENT_DIR_FOUND to the full
+# directory name that matched, including the name being sought (but omitting
+# any deeper directories than that).
+function find_named_parent_dir()
+{
+ local dir_name_sought="$1"; shift
+ # clear any previous global result.
+ unset PARENT_DIR_FOUND
+ # check for degenerate case of parameter count.
+ if [ -z "$dir_name_sought" ]; then
+ echo "
+find_named_parent_dir: requires a directory name parameter, which will be
+sought out above the current directory. the return value indicates whether
+the requested name was found or not.
+"
+ return 1
+ fi
+ # loop upwards in dir hierarchy to find the name.
+ while true; do
+ local currdir="$(\pwd)"
+ if [ "$currdir" == "/" ]; then
+ # we climbed out of all subdirs. this is a failure case.
+ return 1
+ fi
+ # get the base part of our name to check on success.
+ local base="$(basename "$currdir")"
+ if [ "$base" == "$dir_name_sought" ]; then
+ # yes, that is the right name. success case. save our result.
+ export PARENT_DIR_FOUND="$currdir"
+ return 0
+ fi
+ done
+}
+