Something went wrong. Try again.
lol
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463{ lib }:
{ /** Automatically convert an attribute set to command-line options.
This helps protect against malformed command lines and also to reduce boilerplate related to command-line construction for simple use cases.
`toGNUCommandLineShell` returns an escaped shell string.
# Inputs
`options`
: How to format the arguments, see `toGNUCommandLine`
`attrs`
: The attributes to transform into arguments.
# Examples
:::{.example} ## `lib.cli.toGNUCommandLineShell` usage example
```nix 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 = lib.warnIf (lib.oldestSupportedReleaseIsAtLeast 2511) "lib.cli.toGNUCommandLineShell is deprecated, please use lib.cli.toCommandLineShell or lib.cli.toCommandLineShellGNU instead." (options: attrs: lib.escapeShellArgs (lib.cli.toGNUCommandLine options attrs));
/** Automatically convert an attribute set to a list of command-line options.
`toGNUCommandLine` returns a list of string arguments.
# Inputs
`options`
: How to format the arguments, see below.
`attrs`
: The attributes to transform into arguments.
## Options
`mkOptionName`
: How to string-format the option name; By default one character is a short option (`-`), more than one characters a long option (`--`).
`mkBool`
: How to format a boolean value to a command list; By default it’s a flag option (only the option name if true, left out completely if false).
`mkList`
: How to format a list value to a command list; By default the option name is repeated for each value and `mkOption` is applied to the values themselves.
`mkOption`
: How to format any remaining value to a command list; On the toplevel, booleans and lists are handled by `mkBool` and `mkList`, though they can still appear as values of a list. By default, everything is printed verbatim and complex types are forbidden (lists, attrsets, functions). `null` values are omitted.
`optionValueSeparator`
: How to separate an option from its flag; By default, there is no separator, so option `-c` and value `5` would become `["-c" "5"]`. This is useful if the command requires equals, for example, `-c=5`.
# Examples
:::{.example} ## `lib.cli.toGNUCommandLine` 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" ] ```
::: */ toGNUCommandLine = lib.warnIf (lib.oldestSupportedReleaseIsAtLeast 2511) "lib.cli.toGNUCommandLine is deprecated, please use lib.cli.toCommandLine or lib.cli.toCommandLineShellGNU instead." ( { mkOptionName ? k: if builtins.stringLength k == 1 then "-${k}" else "--${k}",
mkBool ? k: v: lib.optional v (mkOptionName k),
mkList ? k: v: lib.concatMap (mkOption k) v,
mkOption ? k: v: if v == null then [ ] else if optionValueSeparator == null then [ (mkOptionName k) (lib.generators.mkValueStringDefault { } v) ] else [ "${mkOptionName k}${optionValueSeparator}${lib.generators.mkValueStringDefault { } v}" ],
optionValueSeparator ? null, }: options: let render = k: v: if builtins.isBool v then mkBool k v else if builtins.isList v then mkList k v else mkOption k v;
in builtins.concatLists (lib.mapAttrsToList render options) );
/** Converts the given attributes into a single shell-escaped command-line string. Similar to `toCommandLineGNU`, but returns a single escaped string instead of a list of arguments. For further reference see: [`lib.cli.toCommandLineGNU`](#function-library-lib.cli.toCommandLineGNU) */ toCommandLineShellGNU = options: attrs: lib.escapeShellArgs (lib.cli.toCommandLineGNU options attrs);
/** Converts an attribute set into a list of GNU-style command-line arguments.
`toCommandLineGNU` returns a list of string arguments.
# Inputs
`options`
: Options, see below.
`attrs`
: The attributes to transform into arguments.
## Options
`isLong`
: A function that determines whether an option is long or short.
`explicitBool`
: Whether or not boolean option arguments should be formatted explicitly.
`formatArg`
: A function that turns the option argument into a string.
# Examples
:::{.example} ## `lib.cli.toCommandLineGNU` usage example
```nix lib.cli.toCommandLineGNU {} { v = true; verbose = [true true false null]; i = ".bak"; testsuite = ["unit" "integration"]; e = ["s/a/b/" "s/b/c/"]; n = false; data = builtins.toJSON {id = 0;}; } => [ "--data={\"id\":0}" "-es/a/b/" "-es/b/c/" "-i.bak" "--testsuite=unit" "--testsuite=integration" "-v" "--verbose" "--verbose" ] ```
::: */ toCommandLineGNU = { isLong ? optionName: builtins.stringLength optionName > 1, explicitBool ? false, formatArg ? lib.generators.mkValueStringDefault { }, }: let optionFormat = optionName: { option = if isLong optionName then "--${optionName}" else "-${optionName}"; sep = if isLong optionName then "=" else ""; inherit explicitBool formatArg; }; in lib.cli.toCommandLine optionFormat;
/** Converts the given attributes into a single shell-escaped command-line string. Similar to `toCommandLine`, but returns a single escaped string instead of a list of arguments. For further reference see: [`lib.cli.toCommandLine`](#function-library-lib.cli.toCommandLine) */ toCommandLineShell = optionFormat: attrs: lib.escapeShellArgs (lib.cli.toCommandLine optionFormat attrs);
/** Converts an attribute set into a list of command-line arguments.
This is the most general command-line construction helper in `lib.cli`. It is parameterized by an `optionFormat` function, which defines how each option name and its value are rendered.
All other helpers in this file are thin wrappers around this function.
`toCommandLine` returns a *flat list of strings*, suitable for use as `argv` arguments or for further processing (e.g. shell escaping).
# Inputs
`optionFormat`
: A function that takes the option name and returns an option spec, where the option spec is an attribute set describing how the option should be rendered.
The returned attribute set must contain:
- `option` (string): The option flag itself, e.g. `"-v"` or `"--verbose"`.
- `sep` (string or null): How to separate the option from its argument. If `null`, the option and its argument are returned as two separate list elements. If a string (e.g. `"="`), the option and argument are concatenated.
- `explicitBool` (bool): Controls how boolean values are handled: - `false`: `true` emits only the option flag, `false` emits nothing. - `true`: both `true` and `false` are rendered as explicit arguments via `formatArg`.
Optional fields:
- `formatArg`: Converts the option value to a string. Defaults to `lib.generators.mkValueStringDefault { }`.
`attrs`
: An attribute set mapping option names to values.
Supported value types: - null: omitted entirely - bool: handled according to `explicitBool` - list: each element is rendered as a separate occurrence of the option - any other value: rendered as a single option argument
Empty attribute names are rejected.
# Examples
:::{.example} ## `lib.cli.toCommandLine` basic usage example
```nix let optionFormat = optionName: { option = "-${optionName}"; sep = "="; explicitBool = true; }; in lib.cli.toCommandLine optionFormat { v = true; verbose = [ true true false null ]; i = ".bak"; testsuite = [ "unit" "integration" ]; e = [ "s/a/b/" "s/b/c/" ]; n = false; data = builtins.toJSON { id = 0; }; } => [ "-data={\"id\":0}" "-e=s/a/b/" "-e=s/b/c/" "-i=.bak" "-n=false" "-testsuite=unit" "-testsuite=integration" "-v=true" "-verbose=true" "-verbose=true" "-verbose=false" ] ``` :::
:::{.example} ## `lib.cli.toCommandLine` usage with a more complex option format
```nix let optionFormat = optionName: let isLong = builtins.stringLength optionName > 1; in { option = if isLong then "--${optionName}" else "-${optionName}"; sep = if isLong then "=" else null; explicitBool = true; formatArg = value: if builtins.isAttrs value then builtins.toJSON value else lib.generators.mkValueStringDefault { } value; }; in lib.cli.toCommandLine optionFormat { v = true; verbose = [ true true false null ]; n = false; output = "result.txt"; testsuite = [ "unit" "integration" ]; data = { id = 0; name = "test"; }; } => [ "--data={\"id\":0,\"name\":\"test\"}" "-n" "false" "--output=result.txt" "--testsuite=unit" "--testsuite=integration" "-v" "true" "--verbose=true" "--verbose=true" "--verbose=false" ] ``` :::
# See also
- `lib.cli.toCommandLineShell` - `lib.cli.toCommandLineGNU` - `lib.cli.toCommandLineShellGNU` */ toCommandLine = optionFormat: attrs: let handlePair = k: v: if k == "" then lib.throw "lib.cli.toCommandLine only accepts non-empty option names." else if builtins.isList v then builtins.concatMap (handleOption k) v else handleOption k v;
handleOption = k: renderOption (optionFormat k) k;
renderOption = { option, sep, explicitBool, formatArg ? lib.generators.mkValueStringDefault { }, }: k: v: if v == null || (!explicitBool && v == false) then [ ] else if !explicitBool && v == true then [ option ] else let arg = formatArg v; in if sep != null then [ "${option}${sep}${arg}" ] else [ option arg ]; in builtins.concatLists (lib.mapAttrsToList handlePair attrs);}