[RFC][PATCH] Try calling command with help flags in run-help

[Marlon Richert <marlon.richert@xxxxxxxxx>]

When there isn't a man page, try calling the command with --help or -h.
Additionally, be a bit smarter about showing function source code.

From ba0fa464c73b10decb33582156aa214953cdd861 Mon Sep 17 00:00:00 2001
From: Marlon Richert <marlon.richert@xxxxxxxxx>
Date: Tue, 25 May 2021 23:45:28 +0300
Subject: [PATCH] Try calling command with help flags in run-help

When there isn't a man page, try calling the command with --help or -h.
Additionally, be a bit smarter about showing function source code.
---
 Functions/Misc/run-help | 108 ++++++++++++++++++++++++++++++----------
 1 file changed, 81 insertions(+), 27 deletions(-)

diff --git a/Functions/Misc/run-help b/Functions/Misc/run-help
index e351dd6a6..dc0490342 100644
--- a/Functions/Misc/run-help
+++ b/Functions/Misc/run-help
@@ -8,6 +8,17 @@
 #	autoload -Uz run-help
 #
 
+.run-help.eval() {
+  output="$( eval "COLUMNS=$COLUMNS $1" 2>&1 )" ||
+      return
+
+  [[ -n $output ]] ||
+      return
+
+  print "$output" | ${=PAGER:-more}
+}
+
+run-help() {
 emulate -RL zsh
 
 local HELPDIR="${HELPDIR:-@runhelpdir@}"
@@ -64,13 +75,6 @@ do
 	[[ ${what[(w)6]:t} != ${what[(w)1]} ]] &&
 	  run_help_orig_cmd=${what[(w)1]} run-help ${what[(w)6]:t}
 	;;
-    (*( is a * function))
-	case ${what[(w)1]} in
-	(comp*) man zshcompsys;;
-	(zf*) man zshftpsys;;
-	(run-help) man zshcontrib;;
-	(*) builtin functions ${what[(w)1]} | ${=PAGER:-more};;
-	esac;;
     (*( is a * builtin))
 	case ${what[(w)1]} in
 	(compctl) man zshcompctl;;
@@ -92,26 +96,73 @@ do
     (*( is a reserved word))
 	man zshmisc
 	;;
-    (*)
-	if ((! didman++))
-	then
-	    if whence "run-help-$1:t" >/dev/null
-	    then
-		local cmd_args
-		builtin getln cmd_args
-		builtin print -z "$cmd_args"
-		cmd_args=( ${(z)cmd_args} )
-		# Discard environment assignments, etc.
-		while [[ $cmd_args[1] != ${run_help_orig_cmd:-$1} ]]
-		do
-		    shift cmd_args || return 1
-		done
-		eval "run-help-$1:t ${(q@)cmd_args[2,-1]}"
-	    else
-		POSIXLY_CORRECT=1 man $@:t
-	    fi
-	fi
-	;;
+    ( comp*( is a* function)* )
+      man zshcompsys
+    ;;
+    ( zf*( is a* function)* )
+      man zshzftpsys
+    ;;
+    ( ((run-help*|which-command) is a* function)* )
+      man zshcontrib
+    ;;
+    ( * )
+      if (( ! didman++ )); then
+        local cmd_args help
+        builtin read -zr cmd_args     # Get the original command line.
+        builtin print -z "$cmd_args"  # Put it back on the buffer stack.
+
+        # Retain only subcommands & options.
+        cmd_args=( ${${(z)cmd_args}[(r)${run_help_orig_cmd:-$1},(r)(-|--)]} )
+        (( $#cmd_args )) &&
+            shift cmd_args
+
+        whence "run-help-$1:t" >/dev/null &&
+            eval "run-help-$1:t ${(@q)cmd_args}" &&
+            return
+
+        # For safety, skip all option flags & anything that looks like a file.
+        while [[ $#cmd_args -gt 0 &&
+            ( -e $~cmd_args[1] || $cmd_args[1] == [-+]* ) ]]; do
+          shift cmd_args
+        done
+
+        # Try if we're dealing with a subcommand and can get help on that.
+        if [[ -n $cmd_args[1] ]]; then
+          # The order in which we try these matters.
+          for help in "$cmd_args[1] "{--help,-h} {-h,--help}" $cmd_args[1]"; do
+            .run-help.eval "$1:t $help" &&
+                return
+          done
+        fi
+
+        # Try the man page.
+        POSIXLY_CORRECT=1 man $1:t 2>/dev/null &&
+            return
+
+        # Try getting help on the main command.
+        for help in -h --help; do
+          .run-help.eval "$1:t $help" &&
+              return
+        done
+
+        if [[ $what = *( is a* function)* ]]; then
+          local func=$what[(w)1]
+
+          # Try to show function source from file, because parsed functions
+          # don't contain comments.
+          autoload +X -Uz $func
+          [[ -n $functions_source[$func] ]] &&
+              ${=PAGER:-more} -- $functions_source[$func] &&
+              return
+
+          builtin functions $func | ${=PAGER:-more} &&
+              return
+        fi
+
+        print -u2 "run-help: no help found for '$what[(w)1]'"
+        return 1
+      fi
+    ;;
     esac
     if ((i < $#places && ! didman))
     then
@@ -124,3 +175,6 @@ done
 } always {
   unset run_help_orig_cmd
 }
+}
+
+run-help "$@"
-- 
2.31.1