doc: lib.asserts migrate to doc-comments (#292310)

This commit is contained in:
Johannes Kirschbauer 2024-03-07 14:04:50 +01:00 committed by GitHub
parent a35b03f5ed
commit 00f00e0663
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -2,47 +2,87 @@
rec { rec {
/* Throw if pred is false, else return pred. /**
Intended to be used to augment asserts with helpful error messages. Throw if pred is false, else return pred.
Intended to be used to augment asserts with helpful error messages.
Example: # Inputs
assertMsg false "nope"
stderr> error: nope
assert assertMsg ("foo" == "bar") "foo is not bar, silly"; "" `pred`
stderr> error: foo is not bar, silly
Type: : Predicate that needs to succeed, otherwise `msg` is thrown
assertMsg :: Bool -> String -> Bool
`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 # TODO(Profpatsch): add tests that check stderr
assertMsg = assertMsg =
# Predicate that needs to succeed, otherwise `msg` is thrown
pred: pred:
# Message to throw in case `pred` fails
msg: msg:
pred || builtins.throw msg; pred || builtins.throw msg;
/* Specialized `assertMsg` for checking if `val` is one of the elements /**
of the list `xs`. Useful for checking enums. Specialized `assertMsg` for checking if `val` is one of the elements
of the list `xs`. Useful for checking enums.
Example: # Inputs
let sslLibrary = "libressl";
in assertOneOf "sslLibrary" sslLibrary [ "openssl" "bearssl" ]
stderr> error: sslLibrary must be one of [
stderr> "openssl"
stderr> "bearssl"
stderr> ], but is: "libressl"
Type: `name`
assertOneOf :: String -> ComparableVal -> List ComparableVal -> Bool
: 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 = assertOneOf =
# The name of the variable the user entered `val` into, for inclusion in the error message
name: name:
# The value of what the user provided, to be compared against the values in `xs`
val: val:
# The list of valid values
xs: xs:
assertMsg assertMsg
(lib.elem val xs) (lib.elem val xs)
@ -50,29 +90,51 @@ rec {
lib.generators.toPretty {} xs}, but is: ${ lib.generators.toPretty {} xs}, but is: ${
lib.generators.toPretty {} val}"; 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. 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.
Example: # Inputs
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> ]
Type: `name`
assertEachOneOf :: String -> List ComparableVal -> List ComparableVal -> Bool
: 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 = assertEachOneOf =
# The name of the variable the user entered `val` into, for inclusion in the error message
name: name:
# The list of values of what the user provided, to be compared against the values in `xs`
vals: vals:
# The list of valid values
xs: xs:
assertMsg assertMsg
(lib.all (val: lib.elem val xs) vals) (lib.all (val: lib.elem val xs) vals)