Merge pull request #306481 from hercules-ci/lib-builtins-warn

    version

    versionSuffix

    warn;

  inherit (lib)

    isString

    ;

in {

  ## Simple (higher order) functions

  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 =

    if lib.elem (builtins.getEnv "NIX_ABORT_ON_WARN") ["1" "true" "yes"]

    then msg: builtins.trace "warning: ${msg}" (abort "NIX_ABORT_ON_WARN=true; warnings are treated as unrecoverable errors.")

    else msg: builtins.trace "warning: ${msg}";

    # 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

        # Do not eta reduce v, so that we have the same strictness as `builtins.warn`.

        msg: v:

          # `builtins.warn` requires a string message, so we enforce that in our implementation, so that callers aren't accidentally incompatible with newer Nix versions.

          assert isString msg;

          if mustAbort

          then builtins.trace "evaluation warning: ${msg}" (abort "NIX_ABORT_ON_WARN=true; warnings are treated as unrecoverable errors.")

          else builtins.trace "evaluation warning: ${msg}" v

    );

  /**

    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;