Skip to content

Commit

Permalink
clarify :id, :required for missing long option with argument
Browse files Browse the repository at this point in the history
Signed-off-by: Sean Corfield <[email protected]>
  • Loading branch information
seancorfield committed Dec 4, 2024
1 parent 4831a7c commit 4b7d57b
Show file tree
Hide file tree
Showing 4 changed files with 30 additions and 17 deletions.
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -19,3 +19,4 @@
bin/
obj/
target
.rebel_readline_history
18 changes: 14 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

Expand Down Expand Up @@ -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"]])
Expand Down
23 changes: 12 additions & 11 deletions doc/parse-opts.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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]
Expand All @@ -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:
Expand All @@ -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]
Expand Down
5 changes: 3 additions & 2 deletions src/main/clojure/clojure/tools/cli.cljc
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand Down

0 comments on commit 4b7d57b

Please sign in to comment.