doc: migrate lib.cli to use doc-comments

This commit is contained in:
Johannes Kirschbauer 2024-03-22 09:54:17 +01:00
parent 284dd64382
commit 6bcb2b90ed
No known key found for this signature in database

View file

@ -1,43 +1,64 @@
{ lib }: { lib }:
rec { rec {
/* Automatically convert an attribute set to command-line options. /**
Automatically convert an attribute set to command-line options.
This helps protect against malformed command lines and also to reduce This helps protect against malformed command lines and also to reduce
boilerplate related to command-line construction for simple use cases. boilerplate related to command-line construction for simple use cases.
`toGNUCommandLine` returns a list of nix strings. `toGNUCommandLine` returns a list of nix strings.
`toGNUCommandLineShell` returns an escaped shell string.
Example: `toGNUCommandLineShell` returns an escaped shell string.
cli.toGNUCommandLine {} {
data = builtins.toJSON { id = 0; };
X = "PUT";
retry = 3;
retry-delay = null;
url = [ "https://example.com/foo" "https://example.com/bar" ];
silent = false;
verbose = true;
}
=> [
"-X" "PUT"
"--data" "{\"id\":0}"
"--retry" "3"
"--url" "https://example.com/foo"
"--url" "https://example.com/bar"
"--verbose"
]
cli.toGNUCommandLineShell {} {
data = builtins.toJSON { id = 0; }; # Inputs
X = "PUT";
retry = 3; `options`
retry-delay = null;
url = [ "https://example.com/foo" "https://example.com/bar" ]; : 1\. Function argument
silent = false;
verbose = true; `attrs`
}
=> "'-X' 'PUT' '--data' '{\"id\":0}' '--retry' '3' '--url' 'https://example.com/foo' '--url' 'https://example.com/bar' '--verbose'"; : 2\. Function argument
# Examples
:::{.example}
## `lib.cli.toGNUCommandLineShell` usage example
```nix
cli.toGNUCommandLine {} {
data = builtins.toJSON { id = 0; };
X = "PUT";
retry = 3;
retry-delay = null;
url = [ "https://example.com/foo" "https://example.com/bar" ];
silent = false;
verbose = true;
}
=> [
"-X" "PUT"
"--data" "{\"id\":0}"
"--retry" "3"
"--url" "https://example.com/foo"
"--url" "https://example.com/bar"
"--verbose"
]
cli.toGNUCommandLineShell {} {
data = builtins.toJSON { id = 0; };
X = "PUT";
retry = 3;
retry-delay = null;
url = [ "https://example.com/foo" "https://example.com/bar" ];
silent = false;
verbose = true;
}
=> "'-X' 'PUT' '--data' '{\"id\":0}' '--retry' '3' '--url' 'https://example.com/foo' '--url' 'https://example.com/bar' '--verbose'";
```
:::
*/ */
toGNUCommandLineShell = toGNUCommandLineShell =
options: attrs: lib.escapeShellArgs (toGNUCommandLine options attrs); options: attrs: lib.escapeShellArgs (toGNUCommandLine options attrs);