Merge branch 'refs/heads/t/help-a' into pu
[gsu.git] / subcommand
index c04f23f..1b204e0 100644 (file)
@@ -100,7 +100,7 @@ gsu_getopts()
 '
 
        gsu_check_arg_count $# 1 1
-       if (($ret < 0)); then
+       if ((ret < 0)); then
                gsu_err_msg
                exit 1
        fi
@@ -126,7 +126,7 @@ gsu_getopts()
        result="local _gsu_getopts_opt"
        for ((i=0; i < ${#1}; i++)); do
                c1=${1:$i:1}
-               c2=${1:$(($i + 1)):1}
+               c2=${1:$((i + 1)):1}
                result+=" o_$c1="
                if [[ "$c2" = ":" ]]; then
                        let i++
@@ -141,7 +141,7 @@ gsu_getopts()
 "
        for ((i=0; i < ${#1}; i++)); do
                c1=${1:$i:1}
-               c2=${1:$(($i + 1)):1}
+               c2=${1:$((i + 1)):1}
                result+="$tab$tab$c1) o_$c1="
                if [[ "$c2" = ":" ]]; then
                        result+="\"\$OPTARG\""
@@ -175,7 +175,7 @@ _gsu_print_available_commands()
        for cmd in $cmds; do
                printf '%s' "$cmd"
                let ++count
-               if (($count % 4)); then
+               if ((count % 4)); then
                        printf '\t'
                        ((${#cmd} < 8)) && printf '\t'
                else
@@ -187,6 +187,8 @@ _gsu_print_available_commands()
 
 # Print all options of the given optstring to stdout if the word in the current
 # command line begins with a hyphen character.
+#
+# Returns 0 if the current word does not start with a hyphen, one otherwise.
 gsu_complete_options()
 {
        local opts="$1" cword="$2" cur opt
@@ -198,18 +200,18 @@ gsu_complete_options()
        ret=0
        [[ ! "$cur" == -* ]] && return
 
-       ret=0
        for ((i=0; i < ${#opts}; i++)); do
                opt="${opts:$i:1}"
                [[ "$opt" == ":" ]] && continue
                printf "%s" "-$opt "
-               let ret++
        done
+       ret=1
 }
 
+declare -A _gsu_help_text=() # indexed by autocmd
 com_prefs_options='e'
 
-_gsu_prefs_txt="
+_gsu_help_text['prefs']='
 Print the current preferences.
 
 Usage: prefs [-e]
@@ -217,7 +219,7 @@ Usage: prefs [-e]
 If -e is given, the config file is opened with the default editor.
 Without options, the command prints out a list of all config variables,
 together with their current value and the default value.
-"
+'
 
 com_prefs()
 {
@@ -225,9 +227,9 @@ com_prefs()
 
        gsu_getopts "$com_prefs_options"
        eval "$result"
-       (($ret < 0)) && return
+       ((ret < 0)) && return
        gsu_check_arg_count $# 0 0
-       (($ret < 0)) && return
+       ((ret < 0)) && return
 
        if [[ "$o_e" == "true" ]]; then
                ret=-$E_GSU_MKDIR
@@ -255,7 +257,7 @@ com_prefs()
                        printf "# optional"
                        ;;
                esac
-               printf "%s: %s" "$option_type" "$description"
+               printf " %s: %s" "$option_type" "$description"
                if [[ "$required" != "yes" && "$required" != "true" ]]; then
                        printf " [%s]" "$default_value"
                fi
@@ -278,29 +280,307 @@ complete_prefs()
        gsu_complete_options "$com_prefs_options" "$@"
 }
 
-_gsu_man_txt='
+_gsu_man_options='m:b:'
+
+complete_man()
+{
+       gsu_complete_options "$_gsu_man_options" "$@"
+       ((ret > 0)) && return
+       gsu_cword_is_option_parameter "$_gsu_man_options" "$@"
+       [[ "$result" == 'm' ]] && printf 'roff\ntext\nhtml\n'
+}
+
+_gsu_help_text['man']='
 Print the manual.
 
-Usage: man
+Usage: man [-m <mode>] [-b <browser>]
+
+-m: Set output format (text, roff or html). Default: roff.
+-b: Use the specified browser. Implies html mode.
+
+If stdout is not associated with a terminal device, the command
+dumps the man page to stdout and exits.
+
+Otherwise, it tries to display the manual page as follows. In text
+mode, plain text is piped to $PAGER. In roff mode, the roff output
+is filtered through nroff, then piped to $PAGER. For both formats,
+if $PAGER is unset, less(1) is assumed.
 
-If stdout associated with a terminal device, output is piped to
-$PAGER. If $PAGER is unset, less(1) is assumed.
+In html mode, html output is written to a temporary file, and this
+file is displayed as a page in the web browser. If -b is not given,
+the command stored in the $BROWSER environment variable is executed
+with the path to the temporary file as an argument. If $BROWSER is
+unset, elinks(1) is assumed.
 '
 
+_gsu_read_line()
+{
+       local -n p="$1"
+       local l OIFS="$IFS"
+
+       IFS=
+       read -r l || return
+       IFS="$OIFS"
+       p="$l"
+}
+
+_gsu_change_roffify_state()
+{
+       local -n statep="$1"
+       local new_state="$2"
+       local old_state="$statep"
+
+       [[ "$old_state" == "$new_state" ]] && return 0
+
+       case "$old_state" in
+       text);;
+       example) printf '.EE\n';;
+       enum) printf '.RE\n';;
+       esac
+       case "$new_state" in
+       text);;
+       example) printf '.EX\n';;
+       enum) printf '.RS 2\n';;
+       esac
+
+       statep="$new_state"
+       return 1
+}
+
+_gsu_print_protected_roff_line()
+{
+       local line="$1"
+       local -i n=0
+
+       while [[ "${line:$n:1}" == ' ' ]]; do
+               let n++
+       done
+       line="${line:$n}"
+       printf '\\&%s\n' "${line//\\/\\\\}"
+}
+
+_gsu_roffify_maindoc()
+{
+       local state='text' TAB='        '
+       local line next_line
+       local -i n
+
+       _gsu_read_line 'line' || return
+       while _gsu_read_line next_line; do
+               if [[ "$next_line" =~ ^(----|====|~~~~) ]]; then # heading
+                       printf '.SS %s\n' "$line"
+                       _gsu_read_line line || return
+                       _gsu_change_roffify_state 'state' 'text'
+                       continue
+               fi
+               if [[ "${line:0:1}" == "$TAB" ]]; then # example
+                       _gsu_change_roffify_state 'state' 'example'
+                       printf '%s\n' "$line"
+                       line="$next_line"
+                       continue
+               fi
+               n=0
+               while [[ "${line:$n:1}" == ' ' ]]; do
+                       let n++
+               done
+               line=${line:$n};
+               if [[ "${line:0:1}" == '*' ]]; then # enum
+                       line=${line#\*}
+                       _gsu_change_roffify_state 'state' 'enum'
+                       printf '\n\(bu %s\n' "$line"
+                       line="$next_line"
+                       continue
+               fi
+               if [[ "$line" =~ ^$ ]]; then # new paragraph
+                       _gsu_change_roffify_state 'state' 'text'
+                       printf '.PP\n'
+               else
+                       _gsu_print_protected_roff_line "$line"
+               fi
+               line="$next_line"
+       done
+       _gsu_print_protected_roff_line "$line"
+}
+
+_gsu_extract_maindoc()
+{
+       sed -e '1,/^#\{70,\}/d' -e '/^#\{70,\}/,$d' -e 's/^# *//' -e 's/^#//g' "$0"
+}
+
+_gsu_roffify_cmds()
+{
+       local line cmd= desc= state='text' TAB='        '
+
+       while _gsu_read_line line; do
+               if [[ "${line:0:1}" != '#' ]]; then # com_foo()
+                       line="${line#com_}"
+                       cmd="${line%()}"
+                       continue
+               fi
+               line="${line####}"
+               if [[ "$line" =~ ^[[:space:]]*$ ]]; then
+                       printf '.PP\n'
+                       _gsu_change_roffify_state 'state' 'text'
+                       continue
+               fi
+               if [[ -n "$cmd" ]]; then # desc or usage
+                       if [[ -z "$desc" ]]; then # desc
+                               desc="$line"
+                               continue
+                       fi
+                       # usage
+                       _gsu_change_roffify_state 'state' 'text'
+                       printf '\n.SS %s \\- %s\n' "$cmd" "$desc"
+                       printf '\n.I %s\n'  "$line"
+                       cmd=
+                       desc=
+                       continue
+               fi
+               line="${line# }"
+               if [[ "${line:0:1}" == "$TAB" ]]; then
+                       _gsu_change_roffify_state 'state' 'example'
+                       _gsu_print_protected_roff_line "$line"
+                       continue
+               fi
+               if [[ "$line" == -*:* ]]; then
+                       _gsu_change_roffify_state 'state' 'enum'
+                       printf '.PP\n.B %s:\n' "${line%%:*}"
+                       _gsu_print_protected_roff_line "${line#*:}"
+                       continue
+               fi
+               _gsu_print_protected_roff_line "$line"
+       done
+}
+
+_gsu_roffify_autocmds()
+{
+       local cmd help_txt
+
+       for cmd in "${!_gsu_help_text[@]}"; do
+               help_txt="${_gsu_help_text["$cmd"]}"
+               {
+                       printf 'com_%s()\n' "$cmd"
+                       sed -e 's/^/## /g' <<< "$help_txt"
+               } | _gsu_roffify_cmds
+       done
+}
+
+_gsu_roff_man()
+{
+       local name="$1" sect_num="$2" month_year="$3" pkg="$4" sect_name="$5"
+       local purpose="$6"
+       local ere
+
+       cat << EOF
+.TH "${name^^}" "$sect_num" "$month_year" "$pkg" "$sect_name"
+.SH NAME
+$name \- $purpose
+.SH SYNOPSIS
+.B $name
+\fI\,<subcommand>\/\fR [\fI\,<options>\/\fR] [\fI\,<arguments>\/\fR]
+.SH DESCRIPTION
+EOF
+       _gsu_extract_maindoc | _gsu_roffify_maindoc
+
+       printf '\n.SH "GENERIC SUBCOMMANDS"\n'
+       printf 'The following commands are automatically created by gsu\n'
+       _gsu_roffify_autocmds
+
+       printf '\n.SH "LIST OF SUBCOMMANDS"\n'
+       printf 'Each command has its own set of options as described below.\n'
+
+       _gsu_get_command_regex
+       ere="$result"
+       # only consider lines in the comment of the function
+       sed -nEe '/'"$ere"'/,/^[^#]/p' "$0" | _gsu_roffify_cmds
+}
+
+_gsu_file_mtime()
+{
+       local file="$1"
+       result="$(find "$file" -printf '%TB %TY' 2>/dev/null)" # GNU
+       (($? == 0)) && [[ -n "$result" ]] && return
+       result="$(stat -f %Sm -t '%B %Y' "$file" 2>/dev/null)" # BSD
+       (($? == 0)) && [[ -n "$result" ]] && return
+       result="$(date '+%B %Y' 2>/dev/null)" # POSIX
+       (($? == 0)) && [[ -n "$result" ]] && return
+       result='[unknown date]'
+}
+
 com_man()
 {
        local equal_signs="=================================================="
        local minus_signs="--------------------------------------------------"
-       local com num pager='cat'
+       local filter='cat' pager='cat' browser=${BROWSER:-elinks} tmpfile=
+       local com num isatty pipeline
 
-       _gsu_isatty && pager="${PAGER:-less}"
+       gsu_getopts "$_gsu_man_options"
+       eval "$result"
+       ((ret < 0)) && return
+       if [[ -n "$o_b" ]]; then
+               o_m='html'
+               browser="$o_b"
+       elif [[ -z "$o_m" ]]; then
+               o_m='roff'
+       fi
+
+       _gsu_isatty && isatty='true' || isatty='false'
+       if [[ "$o_m" == 'roff' ]]; then
+               if [[ "$isatty" == 'true' ]]; then
+                       filter='nroff -Tutf8 -mandoc'
+                       pager="${PAGER:-less}"
+               fi
+       elif [[ "$o_m" == 'text' ]]; then
+               if [[ "$isatty" == 'true' ]]; then
+                       pager="${PAGER:-less}"
+               fi
+       elif [[ "$o_m" == 'html' ]]; then
+               filter='groff -T html -m man'
+               if [[ "$isatty" == 'true' ]]; then
+                       gsu_make_tempfile "gsu_html_man.XXXXXX.html"
+                       ((ret < 0)) && return || tmpfile="$result"
+                       trap "rm -f $tmpfile" RETURN EXIT
+               fi
+       fi
        [[ "$pager" == 'less' ]] && export LESS=${LESS-RI}
+       case "$o_m" in
+       roff|html)
+               _gsu_file_mtime "$0"
+               _gsu_roff_man "$gsu_name" '1' "$result" \
+                       "${gsu_package-${gsu_name^^}(1)}" \
+                       "User Commands" "${gsu_banner_txt}" \
+               | $filter | {
+                       if [[ -n "$tmpfile" ]]; then
+                               cat > "$tmpfile"
+                       else
+                               $pager
+                       fi
+               }
+               if (($? != 0)); then
+                       ret=-$E_GSU_XCMD
+                       result="filter: $filter"
+                       return
+               fi
+               if [[ -n "$tmpfile" ]]; then
+                       ret=-$E_GSU_XCMD
+                       result="$browser"
+                       "$browser" "$tmpfile" || return
+               fi
+               ret=$GSU_SUCCESS
+               return
+               ;;
+       text) ;;
+       "") ;;
+       *)
+               ret=-$E_GSU_INVAL
+               result="$o_m"
+               return
+       esac
        {
        echo "$gsu_name (_${gsu_banner_txt}_) manual"
        echo "${equal_signs:0:${#gsu_name} + ${#gsu_banner_txt} + 16}"
        echo
-
-       sed -e '1,/^#\{70,\}/d' -e '/^#\{70,\}/,$d' "$0" -e 's/^# *//'
+       _gsu_extract_maindoc
        echo "----"
        echo
        echo "$gsu_name usage"
@@ -316,7 +596,7 @@ com_man()
        _gsu_available_commands
        for com in $result; do
                num=${#com}
-               (($num < 4)) && num=4
+               ((num < 4)) && num=4
                echo "${minus_signs:0:$num}"
                echo "$com"
                echo "${minus_signs:0:$num}"
@@ -327,15 +607,18 @@ com_man()
        ret=$GSU_SUCCESS
 }
 
-_gsu_help_txt="
+_gsu_help_text['help']='
 Print online help.
 
-Usage: help [command]
+Usage: help [-a] [command]
 
 Without arguments, print the list of available commands. Otherwise,
-print the help text for the given command."
+print the help text for the given command.
 
-_gsu_complete_txt="
+-a: Also show the help of automatic commands. Ignored if a command
+is given.'
+
+_gsu_help_text['complete']='
 Command line completion.
 
 Usage: complete [<cword> <word>...]
@@ -347,11 +630,16 @@ completion.
 If at least one argument is given, all possible completions are
 written to stdout. This can be used from the completion function of
 the subcommand.
-"
+'
 
+com_help_options='a'
 com_help()
 {
-       local ere tab=' '
+       local ere tab=' ' txt
+
+       gsu_getopts "$com_help_options"
+       eval "$result"
+       ((ret < 0)) && return
 
        _gsu_get_command_regex
        ere="$result"
@@ -360,10 +648,15 @@ com_help()
                gsu_short_msg "### $gsu_name -- $gsu_banner_txt ###"
                _gsu_usage 2>&1
                {
-                       printf "com_help()\n%s" "$_gsu_help_txt" | head -n 4; echo "--"
-                       printf "com_man()\n%s" "$_gsu_man_txt" | head -n 4; echo "--"
-                       printf "com_prefs()\n%s" "$_gsu_prefs_txt" | head -n 4; echo "--"
-                       printf "com_complete()\n%s" "$_gsu_complete_txt" | head -n 4; echo "--"
+                       if [[ "$o_a" == 'true' ]]; then
+                               _gsu_mfcb() { printf '%s\n' "$2"; }
+                               for cmd in "${!_gsu_help_text[@]}"; do
+                                       printf "com_%s()" "$cmd"
+                                       txt="${_gsu_help_text["$cmd"]}"
+                                       mapfile -n 3 -c 1 -C _gsu_mfcb <<< "$txt"
+                               printf -- '--\n'
+                               done
+                       fi
                        grep -EA 2 "$ere" "$0"
                } | grep -v -- '--' \
                        | sed -En "/$ere/"'!d
@@ -391,27 +684,12 @@ com_help()
                ret=$GSU_SUCCESS
                return
        fi
-       if test "$1" = "help"; then
-               echo "$_gsu_help_txt"
+       for cmd in "${!_gsu_help_text[@]}"; do
+               [[ "$1" != "$cmd" ]] && continue
+               printf '%s\n' "${_gsu_help_text["$cmd"]}"
                ret=$GSU_SUCCESS
                return
-       fi
-       if test "$1" = "man"; then
-               echo "$_gsu_man_txt"
-               ret=$GSU_SUCCESS
-               return
-       fi
-       if test "$1" = "prefs"; then
-               echo "$_gsu_prefs_txt"
-               ret=$GSU_SUCCESS
-               return
-       fi
-       if test "$1" = "complete"; then
-               echo "$_gsu_complete_txt"
-               ret=$GSU_SUCCESS
-               return
-       fi
-       ret=$GSU_SUCCESS
+       done
        _gsu_get_command_regex "$1"
        ere="$result"
        if ! grep -Eq "$ere" "$0"; then
@@ -438,6 +716,7 @@ com_help()
                        p
                }
        ' "$0"
+       ret=$GSU_SUCCESS
 }
 
 complete_help()
@@ -457,7 +736,12 @@ com_complete()
                local -a candidates;
 
                candidates=(\$($0 complete "\$COMP_CWORD" "\${COMP_WORDS[@]}"));
-               COMPREPLY=(\$(compgen -W "\${candidates[*]}" -- "\$cur"));
+               if ((\$? == 0)); then
+                       COMPREPLY=(\$(compgen -W "\${candidates[*]}" -- "\$cur"));
+               else
+                       compopt -o filenames;
+                       COMPREPLY=(\$(compgen -fd -- "\$cur"));
+               fi
 EOF
                ret=$GSU_SUCCESS
                return
@@ -465,8 +749,8 @@ EOF
 
        cword="$1"
        gsu_is_a_number "$cword"
-       (($ret < 0)) && return
-       if (($cword <= 1)); then
+       ((ret < 0)) && return
+       if ((cword <= 1)); then
                _gsu_available_commands
                echo "${result}"
                ret=$GSU_SUCCESS
@@ -475,8 +759,9 @@ EOF
        shift
        words=("$@")
        cmd="${words[1]}"
-       ret=$GSU_SUCCESS # It's not an error if no completer was defined
-       [[ "$(type -t "complete_$cmd")" != "function" ]] && return
+       # if no completer is defined for this subcommand we exit unsuccessfully
+       # to let the generic completer above fall back to file name completion.
+       [[ "$(type -t "complete_$cmd")" != "function" ]] && exit 1
        "complete_$cmd" "$cword" "${words[@]}"
        # ignore errors, they would only clutter the completion output
        ret=$GSU_SUCCESS
@@ -493,22 +778,23 @@ EOF
 #
 gsu_cword_is_option_parameter()
 {
-       local opts="$1" cword="$2" prev i n
+       local opts="$1" cword="$2"
+       local opt prev i n
        local -a words
 
        result=
-       (($cword == 0)) && return
+       ((cword == 0)) && return
        ((${#opts} < 2)) && return
 
        shift 2
        words=("$@")
-       prev="${words[$(($cword - 1))]}"
+       prev="${words[$((cword - 1))]}"
        [[ ! "$prev" == -* ]] && return
 
        n=$((${#opts} - 1))
        for ((i=0; i <= $n; i++)); do
                opt="${opts:$i:1}"
-               [[ "${opts:$(($i + 1)):1}" != ":" ]] && continue
+               [[ "${opts:$((i + 1)):1}" != ":" ]] && continue
                let i++
                [[ ! "$prev" =~ ^-.*$opt$ ]] && continue
                result="$opt"
@@ -539,13 +825,13 @@ gsu_get_unnamed_arg_num()
        shift 2
        words=("$@")
        cur="${words[$cword]}"
-       prev="${words[$(($cword - 1))]}"
+       prev="${words[$((cword - 1))]}"
        result=-1
        [[ "$cur" == -* ]] && return
        [[ "$prev" == -* ]] && [[ "$opts" == *${prev#-}:* ]] && return
 
        for ((i=1; i <= $cword; i++)); do
-               prev="${words[$(($i - 1))]}"
+               prev="${words[$((i - 1))]}"
                cur="${words[$i]}"
                [[ "$cur" == -* ]] && continue
                if [[ "$prev" == -* ]]; then
@@ -555,7 +841,7 @@ gsu_get_unnamed_arg_num()
                fi
                let n++
        done
-       result="$(($n - 1))"
+       result="$((n - 1))"
 }
 
 # Entry point for all gsu-based scripts.
@@ -586,7 +872,7 @@ gsu()
        shift
        if [[ "$(type -t "com_$arg")" == 'function' ]]; then
                "com_$arg" "$@"
-               if (("$ret" < 0)); then
+               if ((ret < 0)); then
                        gsu_err_msg
                        exit 1
                fi
@@ -595,6 +881,6 @@ gsu()
        ret=-$E_GSU_BAD_COMMAND
        result="$arg"
        gsu_err_msg
-       _gsu_print_available_commands
+       _gsu_print_available_commands 1>&2
        exit 1
 }