lib/cli: encodeGNUCommandLine -> toGNUCommandLineShell

The semantic difference between `encode` and `to` is not apparent.
Users are likely to confuse both functions (which leads to unexpected
error messages about the wrong types). Like in `generators.nix`, all
functions should be prefixed by `to`.

Furthermore, converting to a string depends on the target context. In
this case, it’s a POSIX shell, so we should name it that (compare
`escapeShellArg` in `strings.nix`).

We can later add versions that escape for embedding in e.g. python
scripts or similar.

1 files changed, 24 insertions, 2 deletions

diff --git a/lib/cli.nix b/lib/cli.nix
index f47625d2f537..32d24a00ceb0 100644
--- a/lib/cli.nix
+++ b/lib/cli.nix
@@ -6,8 +6,29 @@ rec {
      This helps protect against malformed command lines and also to reduce
      boilerplate related to command-line construction for simple use cases.
 
+     `toGNUCommandLine` returns a list of nix strings.
+     `toGNUCommandLineShell` returns an escaped shell string.
+
      Example:
-       encodeGNUCommandLine
+       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" ]
+
+       toGNUCommandLineShell
          { }
          { data = builtins.toJSON { id = 0; };
 
@@ -24,8 +45,9 @@ rec {
            verbose = true;
          };
        => "'-X' 'PUT' '--data' '{\"id\":0}' '--retry' '3' '--url' 'https://example.com/foo' '--url' 'https://example.com/bar' '--verbose'"
+
   */
-  encodeGNUCommandLine =
+  toGNUCommandLineShell =
     options: attrs: lib.escapeShellArgs (toGNUCommandLine options attrs);
 
   toGNUCommandLine =