Commit bc556c56 authored by Robert Hensing's avatar Robert Hensing
Browse files

lib.warn: Update docs 

- 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.
parent 7d4a9a57

lib/trivial.nix

+29 −39
Original line number Diff line number Diff line
@@ -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;