lib/cli.nix

   1 { lib }:
   2
   3 rec {
   4   /**
   5     Automatically convert an attribute set to command-line options.
   6
   7     This helps protect against malformed command lines and also to reduce
   8     boilerplate related to command-line construction for simple use cases.
   9
  10     `toGNUCommandLineShell` returns an escaped shell string.
  11
  12
  13     # Inputs
  14
  15     `options`
  16
  17     : How to format the arguments, see `toGNUCommandLine`
  18
  19     `attrs`
  20
  21     : The attributes to transform into arguments.
  22
  23
  24     # Examples
  25     :::{.example}
  26     ## `lib.cli.toGNUCommandLineShell` usage example
  27
  28     ```nix
  29     cli.toGNUCommandLineShell {} {
  30       data = builtins.toJSON { id = 0; };
  31       X = "PUT";
  32       retry = 3;
  33       retry-delay = null;
  34       url = [ "https://example.com/foo" "https://example.com/bar" ];
  35       silent = false;
  36       verbose = true;
  37     }
  38     => "'-X' 'PUT' '--data' '{\"id\":0}' '--retry' '3' '--url' 'https://example.com/foo' '--url' 'https://example.com/bar' '--verbose'";
  39     ```
  40
  41     :::
  42   */
  43   toGNUCommandLineShell =
  44     options: attrs: lib.escapeShellArgs (toGNUCommandLine options attrs);
  45
  46   /**
  47     Automatically convert an attribute set to a list of command-line options.
  48
  49     `toGNUCommandLine` returns a list of string arguments.
  50
  51
  52     # Inputs
  53
  54     `options`
  55
  56     : How to format the arguments, see below.
  57
  58     `attrs`
  59
  60     : The attributes to transform into arguments.
  61
  62     # Options
  63
  64     `mkOptionName`
  65
  66     : How to string-format the option name;
  67     By default one character is a short option (`-`), more than one characters a long option (`--`).
  68
  69     `mkBool`
  70
  71     : How to format a boolean value to a command list;
  72     By default it’s a flag option (only the option name if true, left out completely if false).
  73
  74     `mkList`
  75
  76     : How to format a list value to a command list;
  77     By default the option name is repeated for each value and `mkOption` is applied to the values themselves.
  78
  79
  80     `mkOption`
  81
  82     : How to format any remaining value to a command list;
  83     On the toplevel, booleans and lists are handled by `mkBool` and `mkList`, though they can still appear as values of a list.
  84     By default, everything is printed verbatim and complex types are forbidden (lists, attrsets, functions). `null` values are omitted.
  85
  86     `optionValueSeparator`
  87
  88     : How to separate an option from its flag;
  89     By default, there is no separator, so option `-c` and value `5` would become ["-c" "5"].
  90     This is useful if the command requires equals, for example, `-c=5`.
  91
  92
  93     # Examples
  94     :::{.example}
  95     ## `lib.cli.toGNUCommandLine` usage example
  96
  97     ```nix
  98     cli.toGNUCommandLine {} {
  99       data = builtins.toJSON { id = 0; };
 100       X = "PUT";
 101       retry = 3;
 102       retry-delay = null;
 103       url = [ "https://example.com/foo" "https://example.com/bar" ];
 104       silent = false;
 105       verbose = true;
 106     }
 107     => [
 108       "-X" "PUT"
 109       "--data" "{\"id\":0}"
 110       "--retry" "3"
 111       "--url" "https://example.com/foo"
 112       "--url" "https://example.com/bar"
 113       "--verbose"
 114     ]
 115     ```
 116
 117     :::
 118   */
 119   toGNUCommandLine = {
 120     mkOptionName ?
 121       k: if builtins.stringLength k == 1
 122           then "-${k}"
 123           else "--${k}",
 124
 125     mkBool ? k: v: lib.optional v (mkOptionName k),
 126
 127     mkList ? k: v: lib.concatMap (mkOption k) v,
 128
 129     mkOption ?
 130       k: v: if v == null
 131             then []
 132             else if optionValueSeparator == null then
 133               [ (mkOptionName k) (lib.generators.mkValueStringDefault {} v) ]
 134             else
 135               [ "${mkOptionName k}${optionValueSeparator}${lib.generators.mkValueStringDefault {} v}" ],
 136
 137     optionValueSeparator ? null
 138     }:
 139     options:
 140       let
 141         render = k: v:
 142           if      builtins.isBool v then mkBool k v
 143           else if builtins.isList v then mkList k v
 144           else mkOption k v;
 145
 146       in
 147         builtins.concatLists (lib.mapAttrsToList render options);
 148 }