gsu_getopts: Abort on programming errors and add documentation.

diff --git a/funcs/gsu b/funcs/gsu
index abe64ce434187839f6fa97fb4bff87f8d28207b7..673605e43bbca8e66940722b7c587b72ba84964b 100644 (file)
--- a/funcs/gsu
+++ b/funcs/gsu
@@ -398,24 +398,49 @@ _gsu_check_options()
 }
 export -f _gsu_check_options
 
+# Wrapper for bash's getopts.
+#
+# Aborts on programming errors such as missing or invalid option string.  On
+# success $result contains shell code that can be eval'ed. For each defined
+# option x, the local variable o_x will be created when calling eval "$result".
+# o_x contains true/false for options without an argument or the emtpy string/the
+# given argument, depending on whether this option was contained in the "$@"
+# array.
+#
+# Example:
+#      gsu_getopts abc:x:y
+#      eval "$result"
+#      [[ $ret -lt 0 ]] && return
+#
+#      [[ "$o_a" = "true ]] && echo "The -a flag was given"
+#      [[ -n "$o_c" ]] && echo "The -c option was given with arg $o_c"
 gsu_getopts()
 {
        local i c tab=' ' cr='
 '
 
        gsu_check_arg_count $# 1 1
-       [[ $ret -lt 0 ]] && return
+       if [[ $ret -lt 0 ]]; then
+               gsu_err_msg
+               exit 1
+       fi
 
        ret=-$E_GSU_GETOPTS
        result="invalid optstring $1"
-       [[ -z "$1" || "$1" =~ "::" ]] && return
+       if [[ -z "$1" || "$1" =~ "::" ]]; then
+               gsu_err_msg
+               exit 1
+       fi
+
        for ((i=0; i < ${#1}; i++)); do
                c=${1:$i:1}
                case "$c" in
                [a-zA-Z:]);;
                *)
+                       ret=-$E_GSU_GETOPTS
                        result="invalid character $c in optstring"
-                       return
+                       gsu_err_msg
+                       exit 1
                esac
        done
        result="local opt"