gsu: Improve documentation of _gsu_get_command_regex().

[gsu.git] / misc / gsu / subcommand

diff --git a/misc/gsu/subcommand b/misc/gsu/subcommand
index 4e363628adb29185fd6857a9fc50caf5a1fddada..a04b8dece11660f1b95946c8108f5f9ceacf8a76 100644 (file)
--- a/misc/gsu/subcommand
+++ b/misc/gsu/subcommand
@@ -2,7 +2,7 @@
 # (C) 2006-2011 Andre Noll
 
 if [[ $(type -t gsu_is_a_number) != "function" ]]; then
-       GSU_DIR=${GSU_DIR:=$HOME/.gsu}
+       GSU_DIR=${GSU_DIR:=${HOME-}/.gsu}
        . $GSU_DIR/common || exit 1
 fi
 
@@ -11,8 +11,16 @@ _gsu_usage()
        gsu_short_msg "# Usage: $_gsu_self command [options]"
 }
 
-# Each line matching this is recognized as a subcommand. The name of the may be
-# given as $1. In any case the subcommand is the first subexpression.
+# Return an extended regular expression to match against $0.
+#
+# When called without argument, the expression matches all lines which define a
+# subcommand.
+#
+# If an argument is given, the returned expression matches only the subcommand
+# passed as $1. This is useful to tell if a string is a valid subcommand.
+#
+# Regardless of whether an argument is given, the returned expression contains
+# exactly one parenthesized subexpression for matching the command name.
 _gsu_get_command_regex()
 {
        local cmd="${1:-[-a-zA-Z_0-9]+}"
@@ -90,7 +98,7 @@ options, the command prints out a list of all cmt config variables, together
 with their current value and the default value."
 _com_prefs()
 {
-       local i conf="${gsu_config_file:=$HOME/.$gsu_name.rc}"
+       local i conf="${gsu_config_file:=${HOME:-}/.$gsu_name.rc}"
 
        gsu_getopts "e"
        eval "$result"
@@ -308,21 +316,20 @@ complete_help()
        echo "$result"
 }
 
-# Wrapper for bash's getopts.
+# Wrapper for the bash getopts builtin.
 #
 # 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.
+# o_x contains true/false for options without argument and either the emtpy
+# string or the given argument for options that take an argument.
 #
 # Example:
 #      gsu_getopts abc:x:y
 #      eval "$result"
-#      [[ $ret -lt 0 ]] && return
+#      (($ret < 0)) && return
 #
-#      [[ "$o_a" = "true ]] && echo "The -a flag was given"
+#      [[ "$o_a" = 'true' ]] && echo 'The -a flag was given'
 #      [[ -n "$o_c" ]] && echo "The -c option was given with arg $o_c"
 gsu_getopts()
 {