clarify :id, :required for missing long option with argument

Signed-off-by: Sean Corfield <[email protected]>

Author: seancorfield

.gitignore

@@ -19,3 +19,4 @@
 bin/
 obj/
 target
+.rebel_readline_history

README.md

@@ -28,17 +28,20 @@ org.clojure/tools.cli {:mvn/version "1.1.230"}
   <version>1.1.230</version>
  </dependency>
 ```
-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"]])

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,15 +142,15 @@ 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]
 
                   :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]
 

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