diff --git a/API.md b/API.md
index 4e99d5e..1c1be9b 100644
--- a/API.md
+++ b/API.md
@@ -10,10 +10,10 @@
- [`opts->table`](#babashka.cli/opts->table)
- [`pad`](#babashka.cli/pad)
- [`pad-cells`](#babashka.cli/pad-cells)
- - [`parse-args`](#babashka.cli/parse-args) - Same as [parse-opts](#babashka.cli/parse-opts) but separates parsed opts into :opts and adds :cmds and :rest-args on the top level instead of metadata.
- - [`parse-cmds`](#babashka.cli/parse-cmds) - Parses sub-commands (arguments not starting with an option prefix) and returns a map with: * :cmds - The parsed subcommands * :args - The remaining (unparsed) arguments.
+ - [`parse-args`](#babashka.cli/parse-args) - Same as [parse-opts](#babashka.cli/parse-opts) with return data reshaped.
+ - [`parse-cmds`](#babashka.cli/parse-cmds) - Parses sub-commands (arguments not starting with an option prefix).
- [`parse-keyword`](#babashka.cli/parse-keyword) - Parse keyword from s.
- - [`parse-opts`](#babashka.cli/parse-opts) - Parse the command line arguments args, a seq of strings.
+ - [`parse-opts`](#babashka.cli/parse-opts) - Returns a map of options parsed from command line arguments args, a seq of strings.
- [`spec->opts`](#babashka.cli/spec->opts) - Converts spec into opts format.
- [`babashka.cli.exec`](#babashka.cli.exec)
- [`-main`](#babashka.cli.exec/-main) - Main entrypoint for command line usage.
@@ -86,21 +86,21 @@ Subcommand dispatcher.
Each entry in the table may have additional [`parse-args`](#babashka.cli/parse-args) options.
For more information and examples, see [README.md](README.md#subcommands).
-Source
+Source
## `format-opts`
``` clojure
(format-opts {:as cfg, :keys [indent], :or {indent 2}})
```
Function.
-Source
+Source
## `format-table`
``` clojure
(format-table {:keys [rows indent], :or {indent 2}})
```
Function.
-Source
+Source
## `merge-opts`
``` clojure
@@ -123,21 +123,21 @@ Function.
(opts->table {:keys [spec order]})
```
Function.
-Source
+Source
## `pad`
``` clojure
(pad len s)
```
Function.
-Source
+Source
## `pad-cells`
``` clojure
(pad-cells rows)
```
Function.
-Source
+Source
## `parse-args`
``` clojure
@@ -146,9 +146,12 @@ Function.
```
Function.
-Same as [`parse-opts`](#babashka.cli/parse-opts) but separates parsed opts into `:opts` and adds
- `:cmds` and `:rest-args` on the top level instead of metadata.
-Source
+Same as [`parse-opts`](#babashka.cli/parse-opts) with return data reshaped.
+
+ Returns a map with:
+ * `:opts` parsed opts
+ * `:args` remaining unparsed `args`
+Source
## `parse-cmds`
``` clojure
@@ -157,7 +160,7 @@ Same as [`parse-opts`](#babashka.cli/parse-opts) but separates parsed opts into
```
Function.
-Parses sub-commands (arguments not starting with an option prefix) and returns a map with:
+Parses sub-commands (arguments not starting with an option prefix). Returns a map with:
* `:cmds` - The parsed subcommands
* `:args` - The remaining (unparsed) arguments
Source
@@ -178,15 +181,13 @@ Parse keyword from `s`. Ignores leading `:`.
```
Function.
-Parse the command line arguments `args`, a seq of strings.
+Returns a map of options parsed from command line arguments `args`, a seq of strings.
Instead of a leading `:` either `--` or `-` may be used as well.
- Return value: a map with parsed opts.
-
- Additional data such as arguments (not corresponding to any options)
- are available under the `:org.babashka/cli` key in the metadata.
+ Metadata on returned map, under `:org.babashka/cli`:
+ * `:args` remaining unparsed `args` (not corresponding to any options)
- Supported options:
+ Supported `opts`:
* `:coerce` - a map of option (keyword) names to type keywords (optionally wrapped in a collection.)
* `:alias` - a map of short names to long names.
* `:spec` - a spec of options. See [spec](https://github.com/babashka/cli#spec).
@@ -203,14 +204,14 @@ Parse the command line arguments `args`, a seq of strings.
```clojure
(parse-opts ["foo" ":bar" "1"])
- ;; => {:bar "1", :org.babashka/cli {:cmds ["foo"]}}
+ ;; => ^{:org.babashka/cli {:args ["foo"]}} {:bar 1}
(parse-opts [":b" "1"] {:aliases {:b :bar} :coerce {:bar parse-long}})
;; => {:bar 1}
(parse-opts ["--baz" "--qux"] {:spec {:baz {:desc "Baz"}} :restrict true})
;; => throws 'Unknown option --qux' exception b/c there is no :qux key in the spec
```
-
-Source
+ See also: [`parse-args`](#babashka.cli/parse-args)
+Source
## `spec->opts`
``` clojure
diff --git a/src/babashka/cli.cljc b/src/babashka/cli.cljc
index 9bec57a..a6d2471 100644
--- a/src/babashka/cli.cljc
+++ b/src/babashka/cli.cljc
@@ -205,7 +205,7 @@
spec)))
(defn parse-cmds
- "Parses sub-commands (arguments not starting with an option prefix) and returns a map with:
+ "Parses sub-commands (arguments not starting with an option prefix). Returns a map with:
* `:cmds` - The parsed subcommands
* `:args` - The remaining (unparsed) arguments"
([args] (parse-cmds args nil))
@@ -265,15 +265,13 @@
:fst-colon fst-colon?}))
(defn parse-opts
- "Parse the command line arguments `args`, a seq of strings.
+ "Returns a map of options parsed from command line arguments `args`, a seq of strings.
Instead of a leading `:` either `--` or `-` may be used as well.
- Return value: a map with parsed opts.
+ Metadata on returned map, under `:org.babashka/cli`:
+ * `:args` remaining unparsed `args` (not corresponding to any options)
- Additional data such as arguments (not corresponding to any options)
- are available under the `:org.babashka/cli` key in the metadata.
-
- Supported options:
+ Supported `opts`:
* `:coerce` - a map of option (keyword) names to type keywords (optionally wrapped in a collection.)
* `:alias` - a map of short names to long names.
* `:spec` - a spec of options. See [spec](https://github.com/babashka/cli#spec).
@@ -290,13 +288,13 @@
```clojure
(parse-opts [\"foo\" \":bar\" \"1\"])
- ;; => {:bar \"1\", :org.babashka/cli {:cmds [\"foo\"]}}
+ ;; => ^{:org.babashka/cli {:args [\"foo\"]}} {:bar 1}
(parse-opts [\":b\" \"1\"] {:aliases {:b :bar} :coerce {:bar parse-long}})
;; => {:bar 1}
(parse-opts [\"--baz\" \"--qux\"] {:spec {:baz {:desc \"Baz\"}} :restrict true})
;; => throws 'Unknown option --qux' exception b/c there is no :qux key in the spec
```
- "
+ See also: [[parse-args]]"
([args] (parse-opts args {}))
([args opts]
(let [spec (:spec opts)
@@ -513,24 +511,17 @@
opts)))
(defn parse-args
- "Same as [[parse-opts]] but separates parsed opts into `:opts` and adds
- `:cmds` and `:rest-args` on the top level instead of metadata."
+ "Same as [[parse-opts]] with return data reshaped.
+
+ Returns a map with:
+ * `:opts` parsed opts
+ * `:args` remaining unparsed `args`"
([args] (parse-args args {}))
([args opts]
(let [opts (parse-opts args opts)
cli-opts (-> opts meta :org.babashka/cli)]
(assoc cli-opts :opts (dissoc opts :org.babashka/cli)))))
-#_(defn commands
- "Returns commands, i.e. non-option arguments passed before the first option argument."
- [parsed-opts]
- (-> parsed-opts meta :org.babashka/cli :cmds))
-
-#_(defn remaining
- "Returns remaining arguments, i.e. arguments after `--`"
- [parsed-opts]
- (-> parsed-opts meta :org.babashka/cli :rest-args))
-
(defn- kw->str [kw]
(subs (str kw) 1))