Improved help, explain why we are showing help (no such command, missing args)

Author: plexus

CHANGELOG.md

@@ -2,9 +2,8 @@
 
 ## Added
 
-## Fixed
-
-## Changed
+- Better help messages: say why we are showing the help (no such command,
+  missing positional args)
 
 # 0.9.42 (2024-05-27 / 3b81e73)
 
@@ -100,4 +99,4 @@ approaching the envisioned scope for this library.
 
 - subcommand handling 
 - rudimentary flag handling
-- help text generation
+- help text generation

src/lambdaisland/cli.clj

@@ -306,7 +306,11 @@
           (recur (dissoc cmdspec :flags) cli-args args (conj seen-prefixes args) flags))
 
         :else
-        (recur (dissoc cmdspec :flags) cli-args (conj args (str/replace arg #"^\\(.)" (fn [[_ o]] o))) (conj seen-prefixes args) flags)))))
+        (recur (dissoc cmdspec :flags)
+               cli-args
+               (conj args (str/replace arg #"^\\(.)" (fn [[_ o]] o)))
+               (conj seen-prefixes args)
+               flags)))))
 
 (defn missing-flags
   "Return a set of required flags in `flagmap` not present in `opts`, or `nil` if
@@ -337,7 +341,7 @@
 
    (cond
      command
-     (if (or (:help opts) (< (count pos-args) (count argnames)))
+     (if (:help opts)
        (print-help program-name doc [] argnames flagpairs)
        (binding [*opts* (-> opts
                             (dissoc ::middleware)
@@ -359,7 +363,8 @@
            argnames         (:argnames command-match)
            arg-count        (count argnames)]
        (cond
-         command-match
+         (and command-match
+              (<= arg-count (count pos-args)))
          (dispatch*
           (-> cmdspec
               (dissoc :command :commands)
@@ -372,13 +377,25 @@
 
          (or (nil? command-match)
              (nil? commands)
-             (:help opts))
-         (print-help program-name doc (for [[k v] command-pairs]
-                                        [k (if (:commands v)
-                                             (update v :commands prepare-cmdpairs)
-                                             v)])
-                     argnames
-                     flagpairs)
+             (:help opts)
+             (< (count pos-args) arg-count))
+         (do
+           (cond
+             (or (nil? command-match) (nil? commands))
+             (println "No matching command found:" cmd "\n")
+             (< (count pos-args) arg-count)
+             (println "Positional arguments missing:"
+                      (->> argnames
+                           (drop (count pos-args))
+                           (map #(str "<" (name %) ">"))
+                           (str/join " "))
+                      "\n"))
+           (print-help program-name doc (for [[k v] command-pairs]
+                                          [k (if (:commands v)
+                                               (update v :commands prepare-cmdpairs)
+                                               v)])
+                       argnames
+                       flagpairs))
 
          :else
          (parse-error! "Expected either :command or :commands key in" cmdspec))))))