about summary refs log tree commit diff
path: root/lib/asserts.nix
blob: c7900c5d6c634075b141a8e976f0265835093fc1 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
{ lib }:

rec {

  /**
    Throw if pred is false, else return pred.
    Intended to be used to augment asserts with helpful error messages.

    # Inputs

    `pred`

    : Predicate that needs to succeed, otherwise `msg` is thrown

    `msg`

    : Message to throw in case `pred` fails

    # Type

    ```
    assertMsg :: Bool -> String -> Bool
    ```

    # Examples
    :::{.example}
    ## `lib.asserts.assertMsg` usage example

    ```nix
    assertMsg false "nope"
    stderr> error: nope
    assert assertMsg ("foo" == "bar") "foo is not bar, silly"; ""
    stderr> error: foo is not bar, silly
    ```

    :::
  */
  # TODO(Profpatsch): add tests that check stderr
  assertMsg =
    pred:
    msg:
    pred || builtins.throw msg;

  /**
    Specialized `assertMsg` for checking if `val` is one of the elements
    of the list `xs`. Useful for checking enums.

    # Inputs

    `name`

    : The name of the variable the user entered `val` into, for inclusion in the error message

    `val`

    : The value of what the user provided, to be compared against the values in `xs`

    `xs`

    : The list of valid values

    # Type

    ```
    assertOneOf :: String -> ComparableVal -> List ComparableVal -> Bool
    ```

    # Examples
    :::{.example}
    ## `lib.asserts.assertOneOf` usage example

    ```nix
    let sslLibrary = "libressl";
    in assertOneOf "sslLibrary" sslLibrary [ "openssl" "bearssl" ]
    stderr> error: sslLibrary must be one of [
    stderr>   "openssl"
    stderr>   "bearssl"
    stderr> ], but is: "libressl"
    ```

    :::
  */
  assertOneOf =
    name:
    val:
    xs:
    assertMsg
    (lib.elem val xs)
    "${name} must be one of ${
      lib.generators.toPretty {} xs}, but is: ${
        lib.generators.toPretty {} val}";

  /**
    Specialized `assertMsg` for checking if every one of `vals` is one of the elements
    of the list `xs`. Useful for checking lists of supported attributes.

    # Inputs

    `name`

    : The name of the variable the user entered `val` into, for inclusion in the error message

    `vals`

    : The list of values of what the user provided, to be compared against the values in `xs`

    `xs`

    : The list of valid values

    # Type

    ```
    assertEachOneOf :: String -> List ComparableVal -> List ComparableVal -> Bool
    ```

    # Examples
    :::{.example}
    ## `lib.asserts.assertEachOneOf` usage example

    ```nix
    let sslLibraries = [ "libressl" "bearssl" ];
    in assertEachOneOf "sslLibraries" sslLibraries [ "openssl" "bearssl" ]
    stderr> error: each element in sslLibraries must be one of [
    stderr>   "openssl"
    stderr>   "bearssl"
    stderr> ], but is: [
    stderr>   "libressl"
    stderr>   "bearssl"
    stderr> ]
    ```

    :::
  */
  assertEachOneOf =
    name:
    vals:
    xs:
    assertMsg
    (lib.all (val: lib.elem val xs) vals)
    "each element in ${name} must be one of ${
      lib.generators.toPretty {} xs}, but is: ${
        lib.generators.toPretty {} vals}";
}