Improve completion of subcommand flags

Author: plexus

CHANGELOG.md

@@ -1,10 +1,8 @@
 # Unreleased
 
-## Added
-
 ## Fixed
 
-## Changed
+- Improve shell completion of flags tied to subcommands
 
 # 1.29.127 (2026-04-10 / c8d5d75)
 

README.md

@@ -437,11 +437,13 @@ must always be passed:
 
 - `:doc` docstring
 - `:default` default value
+- `:key` key to assoc into options map (defaults to flag name)
 - `:value` value to be associated with the key (for flags that don't take arguments)
 - `:handler` handler function, `(fn [opts & flag-args] ,,,)` 
 - `:middleware` function(s) which wrap the final command handler (function or sequence of functions)
 - `:coll?` flag can be specified  multiple times, will result in a vector 
 - `:parse` function used to coerce the flag argument
+- `:required` if true, flag must be provided
 
 ### How to Build a Multi-Command CLI Tool
 
@@ -723,4 +725,4 @@ line with the project's goals.
 Copyright © 2024-2025 Arne Brasseur and Contributors
 
 Licensed under the term of the Mozilla Public License 2.0, see LICENSE.
-<!-- /license -->
+<!-- /license -->

src/lambdaisland/cli.clj

@@ -39,11 +39,6 @@
        (doseq [row rows]
          (println (apply format (str (format (str "%" pad "s") "") fstr) row)))))))
 
-(defn coerce-to-pairs [o]
-  (if (vector? o)
-    (partition 2 o)
-    o))
-
 (defn short? [f]
   (re-find #"^-[^-]$" f))
 
@@ -221,70 +216,6 @@
      (map #(str "-" %) (next flag))
      [flag])))
 
-(def flag-re #"^(--?)(\[no-\])?(.+)$")
-
-(defn cmd->flags [cmdspec args]
-  (if (seq args)
-    (when-let [cmds (:commands cmdspec)]
-      (cmd->flags (get (into {} (cmdspec/prepare-cmdpairs (:commands cmdspec)))
-                       (first args))
-                  (rest args)))
-    (:flags cmdspec)))
-
-(defn parse-flagstr [flagstr flagopts]
-  (let [;; support "--foo=<hello>" and "--foo HELLO"
-        [flags argdoc argnames] (cmdspec/parse-arg-names flagstr)
-        argcnt                  (count argnames)
-        ;; e.g. "-i,--input, --[no-]foo ARG"
-        flagstrs                (map #(re-find flag-re %) flags)
-        flag-key                (keyword (or (some (fn [[_ dash no flag]]
-                                                     (when (= "--" dash) flag))
-                                                   flagstrs)
-                                             (last (first flagstrs))))]
-    (merge {:flagstr flagstr
-            :argdoc  argdoc
-            :flags   flags
-            :args    argnames
-            :key     flag-key
-            :argcnt  argcnt}
-           flagopts)))
-
-(defn prepare-flagpairs [flagstrs]
-  (when (seq flagstrs)
-    (map (fn [[flagstr flagopts]]
-           (let [flagopts (if (var? flagopts)
-                            {:doc (:doc (meta flagopts))
-                             :handler flagopts}
-                            flagopts)]
-             [flagstr (parse-flagstr flagstr (if (string? flagopts) {:doc flagopts} flagopts))]))
-         (coerce-to-pairs flagstrs))))
-
-(defn build-flagmap-entries [[flagstr flagopts]]
-  (let [{:keys [args key argcnt flags] :as parsed-flagstr} flagopts
-        flags                                              (map #(re-find flag-re %) flags)]
-    (for [[_ dash no flag] flags
-          negative?        (if no [true false] [false])]
-      (cond-> {:flag   (str dash (if negative? "no-") flag)
-               :key    key
-               :argcnt argcnt}
-        (= dash "-")
-        (assoc :short? true)
-        (seq args)
-        (assoc :args args)
-        no
-        (assoc :value (not negative?)
-               :boolean? true)
-        :->
-        (merge flagopts)))))
-
-(defn parse-flagstrs [flagpairs]
-  (into {"-h" {:key :help :value true}
-         "--help" {:key :help :value true}}
-        (comp
-         (mapcat build-flagmap-entries)
-         (map (juxt :flag identity)))
-        flagpairs))
-
 (defn add-defaults [init-opts flagpairs]
   (reduce (fn [opts flagspec]
             (if (some? (get opts (:key flagspec)))
@@ -302,24 +233,6 @@
           init-opts
           (map second flagpairs)))
 
-(defn add-processed-flags
-  "We process flag information for easier use, this results in
-  `:flagpairs` (ordered sequence of pairs, mainly used in printing help
-  information), and `:flagmap` (for easy lookup), added to the `cmdspec`. As we
-  process arguments we may need to add additional flags, based on the current
-  subcommand. This function is used both for the top-level as for subcommand
-  handling of flags."
-  [cmdspec extra-flags]
-  (let [flagpairs (prepare-flagpairs extra-flags)
-        flagmap   (parse-flagstrs flagpairs)]
-    (-> cmdspec
-        (update :flagpairs (fn [fp]
-                             (into (vec fp)
-                                   ;; This prevents duplicates. Yes, this is not pretty. I'm very sorry.
-                                   (remove #((into #{} (map first) fp) (first %)))
-                                   flagpairs)))
-        (update :flagmap merge flagmap))))
-
 (defn split-flags
   "Main processing loop, go over raw arguments, split into positional and flags,
   building up an argument vector, and flag/options map."
@@ -331,9 +244,9 @@
          opts             opts]
     ;; Handle additional flags by nested commands
     (let [extra-flags (when-not (seen-prefixes args)
-                        (cmd->flags cmdspec args))
-          opts        (add-defaults opts (prepare-flagpairs extra-flags))
-          cmdspec     (add-processed-flags cmdspec extra-flags)]
+                        (cmdspec/cmd->flags cmdspec args))
+          opts        (add-defaults opts (cmdspec/prepare-flagpairs extra-flags))
+          cmdspec     (cmdspec/add-processed-flags cmdspec extra-flags)]
       (cond
         (nil? arg)
         [cmdspec args opts]

src/lambdaisland/cli/cmdspec.clj

@@ -4,12 +4,15 @@
   (:require
    [clojure.string :as str]))
 
-(def args-re #" ([A-Z][A-Z_-]*)|[= ]<([^>]+)>")
+(def args-re #" ([A-Z][A-Z_-]*)|[= ]<([^>]+)>(\.\.\.)?")
 
 (defn parse-arg-names [str]
   [(str/split (str/replace str args-re "") #",\s*")
    (str/join (map first (re-seq args-re str)))
-   (mapv (fn [[_ u l]] (keyword (str/lower-case (or u l)))) (re-seq args-re str))])
+   (mapv (fn [[_ u l more]] (let [arg-kw (keyword (str/lower-case (or u l)))]
+                              (if more
+                                [:& arg-kw]
+                                arg-kw))) (re-seq args-re str))])
 
 (defn to-cmdspec [?var]
   (cond
@@ -34,3 +37,90 @@
                  [[cmd] doc argnames] (parse-arg-names k)]
              [cmd (assoc v :argdoc doc :argnames argnames)]))
          m)))
+
+(defn cmd->flags [cmdspec args]
+  (if (seq args)
+    (when-let [cmds (:commands cmdspec)]
+      (recur (get (into {} (prepare-cmdpairs (:commands cmdspec)))
+                  (first args))
+             (rest args)))
+    (:flags cmdspec)))
+
+(def flag-re #"^(--?)(\[no-\])?(.+)$")
+
+(defn parse-flagstr [flagstr flagopts]
+  (let [;; support "--foo=<hello>" and "--foo HELLO"
+        [flags argdoc argnames] (parse-arg-names flagstr)
+        argcnt                  (count argnames)
+        ;; e.g. "-i,--input, --[no-]foo ARG"
+        flagstrs                (map #(re-find flag-re %) flags)
+        flag-key                (keyword (or (some (fn [[_ dash no flag]]
+                                                     (when (= "--" dash) flag))
+                                                   flagstrs)
+                                             (last (first flagstrs))))]
+    (merge {:flagstr flagstr
+            :argdoc  argdoc
+            :flags   flags
+            :args    argnames
+            :key     flag-key
+            :argcnt  argcnt}
+           flagopts)))
+
+(defn coerce-to-pairs [o]
+  (if (vector? o)
+    (partition 2 o)
+    o))
+
+(defn prepare-flagpairs [flagstrs]
+  (when (seq flagstrs)
+    (map (fn [[flagstr flagopts]]
+           (let [flagopts (if (var? flagopts)
+                            {:doc (:doc (meta flagopts))
+                             :handler flagopts}
+                            flagopts)]
+             [flagstr (parse-flagstr flagstr (if (string? flagopts) {:doc flagopts} flagopts))]))
+         (coerce-to-pairs flagstrs))))
+
+(defn build-flagmap-entries [[flagstr flagopts]]
+  (let [{:keys [args key argcnt flags] :as parsed-flagstr} flagopts
+        flags                                              (map #(re-find flag-re %) flags)]
+    (for [[_ dash no flag] flags
+          negative?        (if no [true false] [false])]
+      (cond-> {:flag   (str dash (if negative? "no-") flag)
+               :key    key
+               :argcnt argcnt}
+        (= dash "-")
+        (assoc :short? true)
+        (seq args)
+        (assoc :args args)
+        no
+        (assoc :value (not negative?)
+               :boolean? true)
+        :->
+        (merge flagopts)))))
+
+(defn parse-flagstrs [flagpairs]
+  (into {"-h" {:doc "Show help text" :key :help :value true}
+         "--help" {:doc "Show help text" :key :help :value true}}
+        (comp
+         (mapcat build-flagmap-entries)
+         (map (juxt :flag identity)))
+        flagpairs))
+
+(defn add-processed-flags
+  "We process flag information for easier use, this results in
+  `:flagpairs` (ordered sequence of pairs, mainly used in printing help
+  information), and `:flagmap` (for easy lookup), added to the `cmdspec`. As we
+  process arguments we may need to add additional flags, based on the current
+  subcommand. This function is used both for the top-level as for subcommand
+  handling of flags."
+  [cmdspec extra-flags]
+  (let [flagpairs (prepare-flagpairs extra-flags)
+        flagmap   (parse-flagstrs flagpairs)]
+    (-> cmdspec
+        (update :flagpairs (fn [fp]
+                             (into (vec fp)
+                                   ;; This prevents duplicates. Yes, this is not pretty. I'm very sorry.
+                                   (remove #((into #{} (map first) fp) (first %)))
+                                   flagpairs)))
+        (update :flagmap merge flagmap))))

src/lambdaisland/cli/completions.clj

@@ -7,7 +7,9 @@
 (declare with-completions)
 
 (defn shell-completions [cmdspec {:lambdaisland.cli/keys [argv] :as opts}]
-  (let [cmdspec (reduce
+  (let [args    (butlast (next argv))
+        cmdspec (cmdspec/add-processed-flags cmdspec (cmdspec/cmd->flags cmdspec args))
+        cmdspec (reduce
                  (fn [cmdspec arg]
                    (let [commands (cmdspec/prepare-cmdpairs (:commands (with-completions cmdspec)))]
                      (if-let [command-match (get (into {} commands) arg)]
@@ -18,7 +20,7 @@
                                                   (:flagmap (cmdspec/to-cmdspec command-match)))))
                        cmdspec)))
                  cmdspec
-                 (butlast (next argv)))]
+                 args)]
     (doseq [[cmd {:keys [doc]}] (cmdspec/prepare-cmdpairs (:commands cmdspec))]
       (println (str cmd (when doc (str ":" (first (str/split doc #"\R")))))))
     (doseq [[flag {:keys [doc]}] (:flagmap cmdspec)]