Detect blank variable in trueorfalse

As a follow-on to I8cefb58f49dcd2cb2def8a5071d0892af520e7f7, put in
some detection around missing variable-to-test arguments in
trueorfalse.

Correct a couple of places where we were passing in blank strings,
resulting in the default always being applied.

Add test-cases and enhance the documentation a little.

Depends-On: I8cefb58f49dcd2cb2def8a5071d0892af520e7f7
Change-Id: Icc0eb3808a2b6583828d8c47f0af4181e7e2c75a
diff --git a/functions-common b/functions-common
index f9e0b5a..d506b84 100644
--- a/functions-common
+++ b/functions-common
@@ -106,16 +106,27 @@
         --os-project-name admin
 }
 
-# Normalize config values to True or False
-# Accepts as False: 0 no No NO false False FALSE
-# Accepts as True: 1 yes Yes YES true True TRUE
-# VAR=$(trueorfalse default-value test-value)
+# trueorfalse <True|False> <VAR>
+#
+# Normalize config-value provided in variable VAR to either "True" or
+# "False".  If VAR is unset (i.e. $VAR evaluates as empty), the value
+# of the second argument will be used as the default value.
+#
+#  Accepts as False: 0 no  No  NO  false False FALSE
+#  Accepts as True:  1 yes Yes YES true  True  TRUE
+#
+# usage:
+#  VAL=$(trueorfalse False VAL)
 function trueorfalse {
     local xtrace
     xtrace=$(set +o | grep xtrace)
     set +o xtrace
 
     local default=$1
+
+    if [ -z $2 ]; then
+        die $LINENO "variable to normalize required"
+    fi
     local testval=${!2:-}
 
     case "$testval" in