lib/asserts.nix

   1 { lib }:
   2
   3 rec {
   4
   5   /**
   6     Throw if pred is false, else return pred.
   7     Intended to be used to augment asserts with helpful error messages.
   8
   9     # Inputs
  10
  11     `pred`
  12
  13     : Predicate that needs to succeed, otherwise `msg` is thrown
  14
  15     `msg`
  16
  17     : Message to throw in case `pred` fails
  18
  19     # Type
  20
  21     ```
  22     assertMsg :: Bool -> String -> Bool
  23     ```
  24
  25     # Examples
  26     :::{.example}
  27     ## `lib.asserts.assertMsg` usage example
  28
  29     ```nix
  30     assertMsg false "nope"
  31     stderr> error: nope
  32     assert assertMsg ("foo" == "bar") "foo is not bar, silly"; ""
  33     stderr> error: foo is not bar, silly
  34     ```
  35
  36     :::
  37   */
  38   # TODO(Profpatsch): add tests that check stderr
  39   assertMsg =
  40     pred:
  41     msg:
  42     pred || builtins.throw msg;
  43
  44   /**
  45     Specialized `assertMsg` for checking if `val` is one of the elements
  46     of the list `xs`. Useful for checking enums.
  47
  48     # Inputs
  49
  50     `name`
  51
  52     : The name of the variable the user entered `val` into, for inclusion in the error message
  53
  54     `val`
  55
  56     : The value of what the user provided, to be compared against the values in `xs`
  57
  58     `xs`
  59
  60     : The list of valid values
  61
  62     # Type
  63
  64     ```
  65     assertOneOf :: String -> ComparableVal -> List ComparableVal -> Bool
  66     ```
  67
  68     # Examples
  69     :::{.example}
  70     ## `lib.asserts.assertOneOf` usage example
  71
  72     ```nix
  73     let sslLibrary = "libressl";
  74     in assertOneOf "sslLibrary" sslLibrary [ "openssl" "bearssl" ]
  75     stderr> error: sslLibrary must be one of [
  76     stderr>   "openssl"
  77     stderr>   "bearssl"
  78     stderr> ], but is: "libressl"
  79     ```
  80
  81     :::
  82   */
  83   assertOneOf =
  84     name:
  85     val:
  86     xs:
  87     assertMsg
  88     (lib.elem val xs)
  89     "${name} must be one of ${
  90       lib.generators.toPretty {} xs}, but is: ${
  91         lib.generators.toPretty {} val}";
  92
  93   /**
  94     Specialized `assertMsg` for checking if every one of `vals` is one of the elements
  95     of the list `xs`. Useful for checking lists of supported attributes.
  96
  97     # Inputs
  98
  99     `name`
 100
 101     : The name of the variable the user entered `val` into, for inclusion in the error message
 102
 103     `vals`
 104
 105     : The list of values of what the user provided, to be compared against the values in `xs`
 106
 107     `xs`
 108
 109     : The list of valid values
 110
 111     # Type
 112
 113     ```
 114     assertEachOneOf :: String -> List ComparableVal -> List ComparableVal -> Bool
 115     ```
 116
 117     # Examples
 118     :::{.example}
 119     ## `lib.asserts.assertEachOneOf` usage example
 120
 121     ```nix
 122     let sslLibraries = [ "libressl" "bearssl" ];
 123     in assertEachOneOf "sslLibraries" sslLibraries [ "openssl" "bearssl" ]
 124     stderr> error: each element in sslLibraries must be one of [
 125     stderr>   "openssl"
 126     stderr>   "bearssl"
 127     stderr> ], but is: [
 128     stderr>   "libressl"
 129     stderr>   "bearssl"
 130     stderr> ]
 131     ```
 132
 133     :::
 134   */
 135   assertEachOneOf =
 136     name:
 137     vals:
 138     xs:
 139     assertMsg
 140     (lib.all (val: lib.elem val xs) vals)
 141     "each element in ${name} must be one of ${
 142       lib.generators.toPretty {} xs}, but is: ${
 143         lib.generators.toPretty {} vals}";
 144 }