+#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
+ # signal a failure by default with our return value.
+ local retval=1
+ # 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.
+ retval=1
+ break
+ 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"
+ retval=0
+ break
+ fi
+ # hop up a directory.
+ pushd .. &>/dev/null
+ done
+
+ # rollback any directories we pushed.
+ while popd &>/dev/null; do true; done
+
+ return $retval
+}
+