TCLI-96 add :multi true to modify :update-fn behavior

Author: seancorfield

CHANGELOG.md

@@ -1,7 +1,7 @@
 # Change Log
 
-* Release 1.0.next
-  * Planning to add `:multi true` to modify behavior of `:update-fn` [TCLI-96](https://clojure.atlassian.net/browse/TCLI-96).
+* Release 1.0.next (on **master**)
+  * Add `:multi true` to modify behavior of `:update-fn` [TCLI-96](https://clojure.atlassian.net/browse/TCLI-96).
 
 * Release 1.0.194 2020-02-20
   * Switch to 1.0.x versioning.

README.md

@@ -102,7 +102,7 @@ http://clojure.github.io/tools.cli/index.html#clojure.tools.cli/parse-opts
 An interesting library built on top of `tool.cli` that provides a more compact,
 higher-level API is [cli-matic](https://github.com/l3nz/cli-matic).
 
-## New Features in 0.3.x
+## Since Release 0.3.x
 
 ### Better Option Tokenization
 
@@ -249,6 +249,12 @@ only `parse-opts` and `summarize` were available.
     :default 0
     ;; Use :update-fn to create non-idempotent options (:default is applied first)
     :update-fn inc]
+   ["-f" "--file NAME" "File names to read"
+    :multi true ; use :update-fn to combine multiple instance of -f/--file
+    :default []
+    ;; with :multi true, the :update-fn is passed both the existing parsed
+    ;; value(s) and the new parsed value from each option
+    :update-fn conj]
    ;; A boolean option that can explicitly be set to false
    ["-d" "--[no-]daemon" "Daemonize the process" :default true]
    ["-h" "--help"]])

src/main/clojure/clojure/tools/cli.cljc

@@ -57,7 +57,7 @@
   "Given a sequence of column widths, return a string suitable for use in
   format to print a sequences of strings in those columns."
   [lens]
-  (s/join (map #(str "  %" (if-not (zero? %) (str "-" %)) "s") lens)))
+  (s/join (map #(str "  %" (when-not (zero? %) (str "-" %)) "s") lens)))
 ;;
 ;; Legacy API
 ;;
@@ -148,7 +148,7 @@
                 extra-args
                 (drop 2 args))
 
-         :default
+         :else
          (recur options (conj extra-args (first args)) (rest args)))))))
 
 (defn- switches-for
@@ -160,7 +160,7 @@
               (and flag (s/starts-with? s "--"))
               [(s/replace s #"--" "--no-") s]
 
-              :default
+              :else
               [s]))
       flatten))
 
@@ -218,18 +218,18 @@
                        [(first specs) (rest specs)]
                        [nil specs])
         specs (map generate-spec specs)
-        args (normalize-args specs args)]
-    (let [[options extra-args] (apply-specs specs args)
-          banner  (with-out-str (banner-for desc specs))]
-      [options extra-args banner])))
+        args (normalize-args specs args)
+        [options extra-args] (apply-specs specs args)
+        banner (with-out-str (banner-for desc specs))]
+    [options extra-args banner]))
 
 ;;
 ;; New API
 ;;
 
 (def ^{:private true} spec-keys
   [:id :short-opt :long-opt :required :desc :default :default-desc :default-fn
-   :parse-fn :assoc-fn :update-fn :validate-fn :validate-msg :missing])
+   :parse-fn :assoc-fn :update-fn :multi :validate-fn :validate-msg :missing])
 
 (defn- select-spec-keys
   "Select only known spec entries from map and warn the user about unknown
@@ -381,7 +381,7 @@
   (let [{:keys [validate-fn validate-msg]} spec]
     (or (loop [[vfn & vfns] validate-fn [msg & msgs] validate-msg]
           (when vfn
-            (if (try (vfn value) (catch #?(:clj Throwable :cljs :default) e))
+            (if (try (vfn value) (catch #?(:clj Throwable :cljs :default) _))
               (recur vfns msgs)
               [::error (validation-error opt optarg msg)])))
         [value nil])))
@@ -444,7 +444,9 @@
                                (find-spec specs :long-opt optarg)))
                     [m ids (conj errors (missing-required-error opt (:required spec)))]
                     [(if-let [update-fn (:update-fn spec)]
-                       (update-in m [id] update-fn)
+                       (if (:multi spec)
+                         (update m id update-fn value)
+                         (update m id update-fn))
                        ((:assoc-fn spec assoc) m id value))
                      (conj ids id)
                      errors])
@@ -641,7 +643,9 @@
                   You cannot specify both :assoc-fn and :update-fn for an
                   option.
 
-    :update-fn    A function that receives the the current parsed option value,
+    :update-fn    Without :multi true:
+
+                  A function that receives just the existing parsed option value,
                   and returns a new option value, for each option :id present.
                   The default is 'identity'.
 
@@ -659,8 +663,31 @@
                   [\"-v\" \"--verbose\"
                    :update-fn (fnil inc 0)]
 
-                  You cannot specify both :assoc-fn and :update-fn for an
-                  option.
+                  With :multi true:
+
+                  A function that receives both the existing parsed option value,
+                  and the parsed option value from each instance of the option,
+                  and returns a new option value, for each option :id present.
+                  The :multi option is ignored if you do not specify :update-fn.
+
+                  For non-idempotent options, where you need to compute a option
+                  value based on the current value and a new value from the
+                  command line. This can sometimes be easier than use :assoc-fn.
+
+                  [\"-f\" \"--file NAME\"
+                   :default []
+                   :update-fn conj
+                   :multi true]
+
+                  :default is applied first. If you wish to omit the :default
+                  option value, use fnil in your :update-fn as follows:
+
+                  [\"-f\" \"--file NAME\"
+                   :update-fn (fnil conj [])
+                   :multi true]
+
+                  Regardless of :multi, you cannot specify both :assoc-fn
+                  and :update-fn for an option.
 
     :validate     A vector of [validate-fn validate-msg ...]. Multiple pairs
                   of validation functions and error messages may be provided.

src/test/clojure/clojure/tools/cli_test.cljc

@@ -193,23 +193,31 @@
                     :update-fn not]
                    ["-v" "--verbose"
                     :default 0
-                    :update-fn inc]])]
+                    :update-fn inc]
+                   ["-f" "--file NAME"
+                    :multi true
+                    :default []
+                    :update-fn conj]])]
       (is (= (parse-option-tokens specs [])
-             [{:alpha true :verbose 0} []]))
+             [{:alpha true :verbose 0 :file []} []]))
       (is (= (parse-option-tokens specs [[:short-opt "-a"]])
-             [{:alpha false :verbose 0} []]))
+             [{:alpha false :verbose 0 :file []} []]))
+      (is (= (parse-option-tokens specs [[:short-opt "-f" "ONE"]
+                                         [:short-opt "-f" "TWO"]
+                                         [:long-opt "--file" "THREE"]])
+             [{:alpha true :verbose 0 :file ["ONE" "TWO" "THREE"]} []]))
       (is (= (parse-option-tokens specs [[:short-opt "-v"]
                                          [:short-opt "-v"]
                                          [:long-opt "--verbose"]])
-             [{:alpha true :verbose 3} []]))
+             [{:alpha true :verbose 3 :file []} []]))
       (is (= (parse-option-tokens specs [[:short-opt "-v"]] :no-defaults true)
              [{:verbose 1} []]))))
   (testing "associates :id and value with :assoc-fn, without :default"
     (let [specs (compile-option-specs
                   [["-a" nil
                     :id :alpha
                     ;; use fnil to have an implied :default true
-                    :assoc-fn (fn [m k v] (update-in m [k] (fnil not true)))]
+                    :assoc-fn (fn [m k _] (update-in m [k] (fnil not true)))]
                    ["-v" "--verbose"
                     ;; use fnil to have an implied :default 0
                     :assoc-fn (fn [m k _] (update-in m [k] (fnil inc 0)))]])]
@@ -231,11 +239,19 @@
                     :update-fn (fnil not true)]
                    ["-v" "--verbose"
                     ;; use fnil to have an implied :default 0
-                    :update-fn (fnil inc 0)]])]
+                    :update-fn (fnil inc 0)]
+                   ["-f" "--file NAME"
+                    :multi true
+                    ;; use fnil to have an implied :default []
+                    :update-fn (fnil conj [])]])]
       (is (= (parse-option-tokens specs [])
              [{} []]))
       (is (= (parse-option-tokens specs [[:short-opt "-a"]])
              [{:alpha false} []]))
+      (is (= (parse-option-tokens specs [[:short-opt "-f" "A"]
+                                         [:short-opt "-f" "B"]
+                                         [:long-opt "--file" "C"]])
+             [{:file ["A" "B" "C"]} []]))
       (is (= (parse-option-tokens specs [[:short-opt "-v"]
                                          [:short-opt "-v"]
                                          [:long-opt "--verbose"]])