Rewrite charmenu.sh (docstring and style improvements)

src/include-bash/charmenu.sh

@@ -8,31 +8,88 @@ charmenu() {
     #
     # Present "1-char-menu" (but actually N-char) or its parts
     #
-    # Read file in CHARMENU_FILE or given as -f parameter,
-    # and do what either `full` menu, `prompt`, or just terse
-    # list of `items` (like "y,n,q,?").
+    # Usage:
+    #     CHARMENU_FILE=/path/to/file
+    #     charmenu [options] full [ARG]...
+    #     charmenu [options] items
+    #     charmenu [options] prompt
+    #     charmenu [options] has ITEM
+    #
+    # Read file in $CHARMENU_FILE and display either `full`
+    # menu, `items` menu (e.g. "y,n,q,?") or just `prompt`.
+    #
+    # Options:
+    #
+    #     -f FILE, --file FILE   Read contents of menu freom FILE
+    #         instead of variable `$CHARMENU_FILE`.
+    #
+    #     -p PROMPT, --prompt PROMPT   Set prompt string to PROMPT.
+    #         If PROMPT contains '%s', it will be replaced by 'items'
+    #         menu (eg. "y,n,q").  Note that you most probably want
+    #         to include space as last character.  Default: "What
+    #         next [%s]? ".
+    #
+    #     -i, --ignore-case   Ignore case of user reply.  Default:
+    #         case is respected.
+    #
+    #     -d DLM, --delimiter DLM   Use delimiter DLM when printing
+    #         'items' menu.  Default: "," (comma).
     #
     # Format of menu file is one item per line, where item is
     # delimited from its description by single colon. Leading
     # and trailing spaces and spaces around the colon are
     # stripped.
     #
+    # Simple example menu file:
+    #
+    #     a: abort
+    #     r: retry
+    #     f: fail
+    #
     # You can use printf symbols like `%s` in menu and then
     # call `charmenu full arg1 arg2...` to have your arguments
-    # expanded in the full menu.
+    # expanded in the full menu.  More fleshed out example:
+    #
+    #     . "$(shellfu-get path)" || exit 3
+    #     shellfu import charmenu
+    #     shellfu import pretty
     #
-    # Similarly, you can specify single `%s` in the prompt
-    # parameter like `charmenu -p "choose from %s" and it will
-    # be replaced by list of items read from menu file,
-    # delimited either by comma or character provided as `-d`
-    # parameter.
+    #     cat <<EOM >menu
+    #     r: re-run test %s
+    #     c: clean screen
+    #     d: download results to %s
+    #     q: quit
+    #     EOM
     #
-    # `has` checks if given string is a valid menu item.
+    #     CHARMENU_FILE=menu
+    #     running=true
+    #     while $running; do
+    #         charmenu full "mytest" "some storage"
+    #         read -r response
+    #         case $response in
+    #             r)  rerun_test ;;
+    #             c)  reset ;;
+    #             d)  download_results ;;
+    #             q)  running=false ;;
+    #             *)  warn "invalid response: $response"
+    #         esac
+    #     done
+    #     clean_up
     #
-    local mfile="$CHARMENU_FILE"
-    local prompt="What to do next [%s]? "
-    local delim=","
-    local cmd cases
+    # `charmenu has ITEM` exits with zero if ITEM is a valid
+    # menu item.  With abort/retry/fail example above, calling
+    # `if charmenu has a; echo OK; fi` would print "OK"..
+    #
+    local mfile     # path to menu file
+    local prompt    # prompt text
+    local delim     # delimiter (in 'items' menu)
+    local cmd       # command do execute
+    local cases     # "-i" in case-insensitive mode
+    local menu      # loaded menu text
+    local alist     # loaded list of items
+    mfile=$CHARMENU_FILE
+    prompt="What next [%s]? "
+    delim=,
     while true; do case $1 in
         -d|--delimiter)         delim="$2";     shift 2 || return 2 ;;
         -f|--file)              mfile="$2";     shift 2 || return 2 ;;
@@ -44,11 +101,10 @@ charmenu() {
                     "prompt [PRINTF_FMT]"  \
                     "has ITEM"                                      ;;
     esac done
-
-    local menu="$(cat "$mfile")"
-    local alist="$(echo "$menu" | cut -d: -f1 | sed -re 's/^ +//; s/ +$//')"
+    menu="$(cat "$mfile")"
+    alist="$(echo "$menu" | cut -d: -f1 | sed -re 's/^ +//; s/ +$//')"
     debug -v alist
-
+    #shellcheck disable=SC2059
     case $cmd in
         full)   # print the full menu, with any printf notation expanded
             printf "$menu\n" "$@"