Skip to content

docstrings: use wikilinks to reference vars #135

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
borkdude merged 1 commit into from
Mar 6, 2026
Merged

docstrings: use wikilinks to reference vars #135

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
193 changes: 97 additions & 96 deletions API.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,62 +1,63 @@
# Table of contents
- [`babashka.cli`](#babashkacli)
- [`auto-coerce`](#auto-coerce) - Auto-coerces <code>s</code> to data
- [`coerce`](#coerce) - Coerce string <code>s</code> using <code>f</code>
- [`dispatch`](#dispatch) - Subcommand dispatcher.
- [`format-opts`](#format-opts)
- [`format-table`](#format-table)
- [`merge-opts`](#merge-opts) - Merges babashka CLI options.
- [`number-char?`](#number-char?)
- [`opts->table`](#opts->table)
- [`pad`](#pad)
- [`pad-cells`](#pad-cells)
- [`parse-args`](#parse-args) - Same as <code>parse-opts</code> but separates parsed opts into <code>:opts</code> and adds
- [`parse-cmds`](#parse-cmds) - Parses sub-commands (arguments not starting with an option prefix) and returns a
- [`parse-keyword`](#parse-keyword) - Parse keyword from <code>s</code>
- [`parse-opts`](#parse-opts) - Parse the command line arguments <code>args</code>, a seq of strings.
- [`rows`](#rows)
- [`spec->opts`](#spec->opts) - Converts spec into opts format
- [`babashka.cli.exec`](#babashkacliexec)
- [`-main`](#-main) - Main entrypoint for command line usage.
- [`main`](#main)
# babashka.cli





## `auto-coerce`
``` clojure
- [`babashka.cli`](#babashka.cli)
- [`auto-coerce`](#babashka.cli/auto-coerce) - Auto-coerces <code>s</code> to data.
- [`coerce`](#babashka.cli/coerce) - Coerce string <code>s</code> using <code>f</code>.
- [`dispatch`](#babashka.cli/dispatch) - Subcommand dispatcher.
- [`format-opts`](#babashka.cli/format-opts)
- [`format-table`](#babashka.cli/format-table)
- [`merge-opts`](#babashka.cli/merge-opts) - Merges babashka CLI options.
- [`number-char?`](#babashka.cli/number-char?)
- [`opts->table`](#babashka.cli/opts->table)
- [`pad`](#babashka.cli/pad)
- [`pad-cells`](#babashka.cli/pad-cells)
- [`parse-args`](#babashka.cli/parse-args) - Same as [<code>parse-opts</code>](#babashka.cli/parse-opts) but separates parsed opts into <code>:opts</code> and adds <code>:cmds</code> and <code>:rest-args</code> 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: * <code>:cmds</code> - The parsed subcommands * <code>:args</code> - The remaining (unparsed) arguments.
- [`parse-keyword`](#babashka.cli/parse-keyword) - Parse keyword from <code>s</code>.
- [`parse-opts`](#babashka.cli/parse-opts) - Parse the command line arguments <code>args</code>, 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.
- [`main`](#babashka.cli.exec/main)

-----
# <a name="babashka.cli">babashka.cli</a>






## <a name="babashka.cli/auto-coerce">`auto-coerce`</a>
``` clojure
(auto-coerce s)
```

Function.

Auto-coerces `s` to data. Does not coerce when `s` is not a string.
If `s`:
* is `true` or `false`, it is coerced as boolean
* starts with number, it is coerced as a number (through `edn/read-string`)
* starts with `:`, it is coerced as a keyword (through `parse-keyword`)
<br><sub>[source](https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L77-L103)</sub>
## `coerce`
``` clojure
* starts with number, it is coerced as a number (through Clojure's `edn/read-string`)
* starts with `:`, it is coerced as a keyword (through [`parse-keyword`](#babashka.cli/parse-keyword))
<p><sub><a href="https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L77-L103">Source</a></sub></p>

## <a name="babashka.cli/coerce">`coerce`</a>
``` clojure
(coerce s f)
```

Function.

Coerce string `s` using `f`. Does not coerce when `s` is not a string.
`f` may be a keyword (`:boolean`, `:int`, `:double`, `:symbol`,
`:keyword`) or a function. When `f` return `nil`, this is
interpreted as a parse failure and throws.
<br><sub>[source](https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L143-L149)</sub>
## `dispatch`
``` clojure
<p><sub><a href="https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L143-L149">Source</a></sub></p>

## <a name="babashka.cli/dispatch">`dispatch`</a>
``` clojure
(dispatch table args)
(dispatch table args opts)
```

Function.

Subcommand dispatcher.

Expand All @@ -72,7 +73,7 @@ Subcommand dispatcher.
```

When a match is found, `:fn` called with the return value of
[`parse-args`](#parse-args) applied to `args` enhanced with:
[`parse-args`](#babashka.cli/parse-args) applied to `args` enhanced with:

* `:dispatch` - the matching commands
* `:args` - concatenation of unparsed commands and args
Expand All @@ -82,100 +83,100 @@ Subcommand dispatcher.

Provide an `:error-fn` to deal with non-matches.

Each entry in the table may have additional [`parse-args`](#parse-args) options.
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).
<br><sub>[source](https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L729-L761)</sub>
## `format-opts`
``` clojure
<p><sub><a href="https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L729-L761">Source</a></sub></p>

## <a name="babashka.cli/format-opts">`format-opts`</a>
``` clojure
(format-opts {:as cfg, :keys [indent], :or {indent 2}})
```
Function.
<p><sub><a href="https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L628-L632">Source</a></sub></p>

<sub>[source](https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L628-L632)</sub>
## `format-table`
## <a name="babashka.cli/format-table">`format-table`</a>
``` clojure

(format-table {:keys [rows indent], :or {indent 2}})
```
Function.
<p><sub><a href="https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L566-L579">Source</a></sub></p>

<sub>[source](https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L566-L579)</sub>
## `merge-opts`
## <a name="babashka.cli/merge-opts">`merge-opts`</a>
``` clojure

(merge-opts m & ms)
```

Function.

Merges babashka CLI options.
<br><sub>[source](https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L12-L15)</sub>
## `number-char?`
``` clojure
<p><sub><a href="https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L12-L15">Source</a></sub></p>

## <a name="babashka.cli/number-char?">`number-char?`</a>
``` clojure
(number-char? c)
```
Function.
<p><sub><a href="https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L53-L55">Source</a></sub></p>

<sub>[source](https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L53-L55)</sub>
## `opts->table`
## <a name="babashka.cli/opts->table">`opts->table`</a>
``` clojure

(opts->table {:keys [spec order]})
```
Function.
<p><sub><a href="https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L609-L626">Source</a></sub></p>

<sub>[source](https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L609-L626)</sub>
## `pad`
## <a name="babashka.cli/pad">`pad`</a>
``` clojure

(pad len s)
```
Function.
<p><sub><a href="https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L544-L544">Source</a></sub></p>

<sub>[source](https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L544-L544)</sub>
## `pad-cells`
## <a name="babashka.cli/pad-cells">`pad-cells`</a>
``` clojure

(pad-cells rows)
```
Function.
<p><sub><a href="https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L546-L552">Source</a></sub></p>

<sub>[source](https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L546-L552)</sub>
## `parse-args`
## <a name="babashka.cli/parse-args">`parse-args`</a>
``` clojure

(parse-args args)
(parse-args args opts)
```
Function.


Same as [`parse-opts`](#parse-opts) but separates parsed opts into `:opts` and adds
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.
<br><sub>[source](https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L515-L522)</sub>
## `parse-cmds`
``` clojure
<p><sub><a href="https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L515-L522">Source</a></sub></p>

## <a name="babashka.cli/parse-cmds">`parse-cmds`</a>
``` clojure
(parse-cmds args)
(parse-cmds args {:keys [no-keyword-opts]})
```

Function.

Parses sub-commands (arguments not starting with an option prefix) and returns a map with:
* `:cmds` - The parsed subcommands
* `:args` - The remaining (unparsed) arguments
<br><sub>[source](https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L207-L217)</sub>
## `parse-keyword`
``` clojure
<p><sub><a href="https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L207-L217">Source</a></sub></p>

## <a name="babashka.cli/parse-keyword">`parse-keyword`</a>
``` clojure
(parse-keyword s)
```

Function.

Parse keyword from `s`. Ignores leading `:`.
<br><sub>[source](https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L65-L70)</sub>
## `parse-opts`
``` clojure
<p><sub><a href="https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L65-L70">Source</a></sub></p>

## <a name="babashka.cli/parse-opts">`parse-opts`</a>
``` clojure
(parse-opts args)
(parse-opts args opts)
```

Function.

Parse the command line arguments `args`, a seq of strings.
Instead of a leading `:` either `--` or `-` may be used as well.
Expand Down Expand Up @@ -209,31 +210,31 @@ Parse the command line arguments `args`, a seq of strings.
;; => throws 'Unknown option --qux' exception b/c there is no :qux key in the spec
```

<br><sub>[source](https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L267-L513)</sub>
## `rows`
<sub>[source](https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L582-L584)</sub>
## `spec->opts`
``` clojure
<p><sub><a href="https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L267-L513">Source</a></sub></p>

## <a name="babashka.cli/spec->opts">`spec->opts`</a>
``` clojure
(spec->opts spec)
(spec->opts spec {:keys [exec-args]})
```

Function.

Converts spec into opts format. Pass existing opts as optional second argument.
<br><sub>[source](https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L184-L205)</sub>
# babashka.cli.exec
<p><sub><a href="https://github.com/babashka/cli/blob/main/src/babashka/cli.cljc#L184-L205">Source</a></sub></p>

-----
# <a name="babashka.cli.exec">babashka.cli.exec</a>





## `-main`
``` clojure

## <a name="babashka.cli.exec/-main">`-main`</a>
``` clojure
(-main & args)
```

Function.

Main entrypoint for command line usage.
Expects a namespace and var name followed by zero or more key value
Expand All @@ -246,11 +247,11 @@ Main entrypoint for command line usage.
clojure -M:exec clojure.core prn :a 1 :b 2
;;=> {:a "1" :b "2"}
```
<br><sub>[source](https://github.com/babashka/cli/blob/main/src/babashka/cli/exec.clj#L97-L110)</sub>
## `main`
``` clojure
<p><sub><a href="https://github.com/babashka/cli/blob/main/src/babashka/cli/exec.clj#L97-L110">Source</a></sub></p>

## <a name="babashka.cli.exec/main">`main`</a>
``` clojure
(main & args)
```

<sub>[source](https://github.com/babashka/cli/blob/main/src/babashka/cli/exec.clj#L92-L95)</sub>
Function.
<p><sub><a href="https://github.com/babashka/cli/blob/main/src/babashka/cli/exec.clj#L92-L95">Source</a></sub></p>
5 changes: 3 additions & 2 deletions bb.edn
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{:pods {clj-kondo/clj-kondo {:version "2022.05.31"}}
:deps {io.github.borkdude/quickdoc
#_{:local/root "/Users/borkdude/dev/quickdoc"}
{:git/sha "ca5893c0d81f26443dd178a747d0851e75d39eca"}}
{:git/sha "026b4fab8570853e38c3097fe1f8619abc95b2e0"}}
:paths ["src" ".build"]

:tasks
Expand All @@ -26,7 +26,8 @@
:task (api/quickdoc (merge {:git/branch "main"
:github/repo "https://github.com/babashka/cli"
:toc true
:var-links true}
:var-links true
:var-pattern :wikilinks}
cmd-line-opts))}

bump-release {:doc "Bump release counter"
Expand Down
10 changes: 5 additions & 5 deletions src/babashka/cli.cljc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,8 +78,8 @@
"Auto-coerces `s` to data. Does not coerce when `s` is not a string.
If `s`:
* is `true` or `false`, it is coerced as boolean
* starts with number, it is coerced as a number (through `edn/read-string`)
* starts with `:`, it is coerced as a keyword (through `parse-keyword`)"
* starts with number, it is coerced as a number (through Clojure's `edn/read-string`)
* starts with `:`, it is coerced as a keyword (through [[parse-keyword]])"
[s]
(if (string? s)
(try
Expand Down Expand Up @@ -513,7 +513,7 @@
opts)))

(defn parse-args
"Same as `parse-opts` but separates parsed opts into `:opts` and adds
"Same as [[parse-opts]] but separates parsed opts into `:opts` and adds
`:cmds` and `:rest-args` on the top level instead of metadata."
([args] (parse-args args {}))
([args opts]
Expand Down Expand Up @@ -741,7 +741,7 @@
```

When a match is found, `:fn` called with the return value of
`parse-args` applied to `args` enhanced with:
[[parse-args]] applied to `args` enhanced with:

* `:dispatch` - the matching commands
* `:args` - concatenation of unparsed commands and args
Expand All @@ -751,7 +751,7 @@

Provide an `:error-fn` to deal with non-matches.

Each entry in the table may have additional `parse-args` options.
Each entry in the table may have additional [[parse-args]] options.

For more information and examples, see [README.md](README.md#subcommands)."
([table args]
Expand Down