nordic-dev.net/nixpkgs
nordic-dev.net/nixpkgs
2
0
Fork 0
mirror of https://github.com/NixOS/nixpkgs.git synced 2024-11-25 16:33:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

lib.warn: Update docs

Browse Source 
- Bring up to date
- Give meaning to the metavariables
- Use italics for metavariables (just like the Nix manual)
- Don't abbreviate
  - No hard feelings, Val.
This commit is contained in:
Robert Hensing 2024-07-23 12:48:01 +02:00
parent 7d4a9a5772
commit bc556c5686
1 changed files with 29 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
lib/trivial.nix
View File

@ -661,47 +661,33 @@ in {
importTOML = path:
builtins.fromTOML (builtins.readFile path);
## Warnings
# See https://github.com/NixOS/nix/issues/749. Eventually we'd like these
# to expand to Nix builtins that carry metadata so that Nix can filter out
# the INFO messages without parsing the message string.
#
# Usage:
# {
# foo = lib.warn "foo is deprecated" oldFoo;
# bar = lib.warnIf (bar == "") "Empty bar is deprecated" bar;
# }
#
# TODO: figure out a clever way to integrate location information from
# something like __unsafeGetAttrPos.
/**
Print a warning before returning the second argument. This function behaves
like `builtins.trace`, but requires a string message and formats it as a
warning, including the `warning: ` prefix.
To get a call stack trace and abort evaluation, set the environment variable
`NIX_ABORT_ON_WARN=true` and set the Nix options `--option pure-eval false --show-trace`
`warn` *`message`* *`value`*
Print a warning before returning the second argument.
See [`builtins.warn`](https://nix.dev/manual/nix/latest/language/builtins.html#builtins-warn) (Nix >= 2.23).
On older versions, the Nix 2.23 behavior is emulated with [`builtins.trace`](https://nix.dev/manual/nix/latest/language/builtins.html#builtins-warn), including the [`NIX_ABORT_ON_WARN`](https://nix.dev/manual/nix/latest/command-ref/conf-file#conf-abort-on-warn) behavior, but not the `nix.conf` setting or command line option.
# Inputs
`msg`
*`message`* (String)
: Warning message to print.
: Warning message to print before evaluating *`value`*.
`val`
*`value`* (any value)
: Value to return as-is.
# Type
```
string -> a -> a
String -> a -> a
```
*/
warn =
# Since https://github.com/NixOS/nix/pull/10592
# Since Nix 2.23, https://github.com/NixOS/nix/pull/10592
builtins.warn or (
let mustAbort = lib.elem (builtins.getEnv "NIX_ABORT_ON_WARN") ["1" "true" "yes"];
in
@ -715,53 +701,57 @@ in {
);
/**
Like warn, but only warn when the first argument is `true`.
`warnIf` *`condition`* *`message`* *`value`*
Like `warn`, but only warn when the first argument is `true`.
# Inputs
`cond`
*`condition`* (Boolean)
: 1\. Function argument
: `true` to trigger the warning before continuing with *`value`*.
`msg`
*`message`* (String)
: 2\. Function argument
: Warning message to print before evaluating
`val`
*`value`* (any value)
: Value to return as-is.
# Type
```
bool -> string -> a -> a
Bool -> String -> a -> a
```
*/
warnIf = cond: msg: if cond then warn msg else x: x;
/**
Like warnIf, but negated (warn if the first argument is `false`).
`warnIfNot` *`condition`* *`message`* *`value`*
Like `warnIf`, but negated: warn if the first argument is `false`.
# Inputs
`cond`
*`condition`*
: 1\. Function argument
: `false` to trigger the warning before continuing with `val`.
`msg`
*`message`*
: 2\. Function argument
: Warning message to print before evaluating *`value`*.
`val`
*`value`*
: Value to return as-is.
# Type
```
bool -> string -> a -> a
Boolean -> String -> a -> a
```
*/
warnIfNot = cond: msg: if cond then x: x else warn msg;