From 4b7d57b0f3aaaa656090f6bddf62e7b918efe945 Mon Sep 17 00:00:00 2001 From: Sean Corfield Date: Tue, 3 Dec 2024 21:56:54 -0800 Subject: [PATCH] clarify :id, :required for missing long option with argument Signed-off-by: Sean Corfield --- .gitignore | 1 + README.md | 18 ++++++++++++++---- doc/parse-opts.md | 23 ++++++++++++----------- src/main/clojure/clojure/tools/cli.cljc | 5 +++-- 4 files changed, 30 insertions(+), 17 deletions(-) diff --git a/.gitignore b/.gitignore index 38b6968..e053a03 100644 --- a/.gitignore +++ b/.gitignore @@ -19,3 +19,4 @@ bin/ obj/ target +.rebel_readline_history diff --git a/README.md b/README.md index 0c3ed38..e612d34 100644 --- a/README.md +++ b/README.md @@ -28,17 +28,20 @@ org.clojure/tools.cli {:mvn/version "1.1.230"} 1.1.230 ``` -The 0.4.x series of tools.cli supports use with `clj`/`deps.edn` and brings + +### Historical Release Notes + +Starting with 0.4.x, `tools.cli` supports use with `clj`/`deps.edn` and brings the legacy API to ClojureScript by switching to `.cljc` files. This means it requires Clojure(Script) 1.9 or later. -The 0.3.x series of tools.cli features a new flexible API, better adherence +The 0.3.x series of tools.cli introduced a new flexible API, better adherence to GNU option parsing conventions, and ClojureScript support. -The function `clojure.tools.cli/cli` has been superseded by +The old function `clojure.tools.cli/cli` was superseded by `clojure.tools.cli/parse-opts`, and should not be used in new programs. -The previous function will remain for the foreseeable future. It has also been +The older function will remain for the foreseeable future. It has also been adapted to use the new tokenizer, so upgrading is still worthwhile even if you are not ready to migrate to `parse-opts`. @@ -146,6 +149,13 @@ For detailed documentation, please see the docstring of `parse-opts`. ;; 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] + ["-t" nil "Timeout in seconds" + ;; Since there is no long option, :id is required... + :id :timeout + ;; ...and we require an argument to be provided: + :required "TIMEOUT" + ;; parse-long was added in Clojure 1.11: + :parse-fn parse-long] ;; A boolean option that can explicitly be set to false ["-d" "--[no-]daemon" "Daemonize the process" :default true] ["-h" "--help"]]) diff --git a/doc/parse-opts.md b/doc/parse-opts.md index cedbe00..8de7a06 100644 --- a/doc/parse-opts.md +++ b/doc/parse-opts.md @@ -24,7 +24,7 @@ this into complete documentation for the library, with examples, over time): By default, options are toggles that default to nil, but the second string parameter may be used to specify that an option requires an argument. - e.g. [\"-p\" \"--port PORT\"] specifies that --port requires an argument, + e.g. ["-p" "--port PORT"] specifies that --port requires an argument, of which PORT is a short description. The :property value pairs are optional and take precedence over the @@ -38,17 +38,18 @@ this into complete documentation for the library, with examples, over time): transform a value in different ways, but only one of these option entries may contain a :default(-fn) entry. - This option is mandatory. + This option is mandatory if no long option is provided. :short-opt The short format for this option, normally set by the first - positional string parameter: e.g. \"-p\". Must be unique. + positional string parameter: e.g. "-p". Must be unique. :long-opt The long format for this option, normally set by the second - positional string parameter; e.g. \"--port\". Must be unique. + positional string parameter; e.g. "--port". Must be unique. :required A description of the required argument for this option if one is required; normally set in the second positional - string parameter after the long option: \"--port PORT\". + string parameter after the long option: "--port PORT", + which would be equivalent to :required "PORT". The absence of this entry indicates that the option is a boolean toggle that is set to true when specified on the @@ -93,7 +94,7 @@ this into complete documentation for the library, with examples, over time): If this is a boolean option, parse-fn will receive the value true. This may be used to invert the logic of this option: - [\"-q\" \"--quiet\" + ["-q" "--quiet" :id :verbose :default true :parse-fn not] @@ -118,16 +119,16 @@ this into complete documentation for the library, with examples, over time): This may be used to create non-idempotent options where you only need the current value, like setting a verbosity level by - specifying an option multiple times. (\"-vvv\" -> 3) + specifying an option multiple times. ("-vvv" -> 3) - [\"-v\" \"--verbose\" + ["-v" "--verbose" :default 0 :update-fn inc] :default is applied first. If you wish to omit the :default option value, use fnil in your :update-fn as follows: - [\"-v\" \"--verbose\" + ["-v" "--verbose" :update-fn (fnil inc 0)] With :multi true: @@ -141,7 +142,7 @@ this into complete documentation for the library, with examples, over time): 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\" + ["-f" "--file NAME" :default [] :update-fn conj :multi true] @@ -149,7 +150,7 @@ this into complete documentation for the library, with examples, over time): :default is applied first. If you wish to omit the :default option value, use fnil in your :update-fn as follows: - [\"-f\" \"--file NAME\" + ["-f" "--file NAME" :update-fn (fnil conj []) :multi true] diff --git a/src/main/clojure/clojure/tools/cli.cljc b/src/main/clojure/clojure/tools/cli.cljc index 1e6284e..e392071 100644 --- a/src/main/clojure/clojure/tools/cli.cljc +++ b/src/main/clojure/clojure/tools/cli.cljc @@ -438,7 +438,7 @@ transform a value in different ways, but only one of these option entries may contain a :default(-fn) entry. - This option is mandatory. + This option is mandatory if no long option is provided. :short-opt The short format for this option, normally set by the first positional string parameter: e.g. \"-p\". Must be unique. @@ -448,7 +448,8 @@ :required A description of the required argument for this option if one is required; normally set in the second positional - string parameter after the long option: \"--port PORT\". + string parameter after the long option: \"--port PORT\", + which would be equivalent to :required \"PORT\". The absence of this entry indicates that the option is a boolean toggle that is set to true when specified on the