mirror of
https://github.com/ilyakooo0/nixpkgs.git
synced 2024-08-17 11:10:57 +03:00
doc: lib.asserts migrate to doc-comments (#292310)
This commit is contained in:
parent
a35b03f5ed
commit
00f00e0663
146
lib/asserts.nix
146
lib/asserts.nix
@ -2,47 +2,87 @@
|
||||
|
||||
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:
|
||||
assertMsg false "nope"
|
||||
stderr> error: nope
|
||||
# Inputs
|
||||
|
||||
assert assertMsg ("foo" == "bar") "foo is not bar, silly"; ""
|
||||
stderr> error: foo is not bar, silly
|
||||
`pred`
|
||||
|
||||
Type:
|
||||
assertMsg :: Bool -> String -> Bool
|
||||
: 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 =
|
||||
# Predicate that needs to succeed, otherwise `msg` is thrown
|
||||
pred:
|
||||
# Message to throw in case `pred` fails
|
||||
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:
|
||||
let sslLibrary = "libressl";
|
||||
in assertOneOf "sslLibrary" sslLibrary [ "openssl" "bearssl" ]
|
||||
stderr> error: sslLibrary must be one of [
|
||||
stderr> "openssl"
|
||||
stderr> "bearssl"
|
||||
stderr> ], but is: "libressl"
|
||||
# Inputs
|
||||
|
||||
Type:
|
||||
assertOneOf :: String -> ComparableVal -> List ComparableVal -> Bool
|
||||
`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 =
|
||||
# The name of the variable the user entered `val` into, for inclusion in the error message
|
||||
name:
|
||||
# The value of what the user provided, to be compared against the values in `xs`
|
||||
val:
|
||||
# The list of valid values
|
||||
xs:
|
||||
assertMsg
|
||||
(lib.elem val xs)
|
||||
@ -50,29 +90,51 @@ rec {
|
||||
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.
|
||||
/**
|
||||
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:
|
||||
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> ]
|
||||
# Inputs
|
||||
|
||||
Type:
|
||||
assertEachOneOf :: String -> List ComparableVal -> List ComparableVal -> Bool
|
||||
`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 =
|
||||
# The name of the variable the user entered `val` into, for inclusion in the error message
|
||||
name:
|
||||
# The list of values of what the user provided, to be compared against the values in `xs`
|
||||
vals:
|
||||
# The list of valid values
|
||||
xs:
|
||||
assertMsg
|
||||
(lib.all (val: lib.elem val xs) vals)
|
||||
|
Loading…
Reference in New Issue
Block a user