lib/trivial.nix

   1 { lib }:
   2
   3 rec {
   4
   5   ## Simple (higher order) functions
   6
   7   /* The identity function
   8      For when you need a function that does “nothing”.
   9
  10      Type: id :: a -> a
  11   */
  12   id =
  13     # The value to return
  14     x: x;
  15
  16   /* The constant function
  17
  18      Ignores the second argument. If called with only one argument,
  19      constructs a function that always returns a static value.
  20
  21      Type: const :: a -> b -> a
  22      Example:
  23        let f = const 5; in f 10
  24        => 5
  25   */
  26   const =
  27     # Value to return
  28     x:
  29     # Value to ignore
  30     y: x;
  31
  32   /* Pipes a value through a list of functions, left to right.
  33
  34      Type: pipe :: a -> [<functions>] -> <return type of last function>
  35      Example:
  36        pipe 2 [
  37          (x: x + 2)  # 2 + 2 = 4
  38          (x: x * 2)  # 4 * 2 = 8
  39        ]
  40        => 8
  41
  42        # ideal to do text transformations
  43        pipe [ "a/b" "a/c" ] [
  44
  45          # create the cp command
  46          (map (file: ''cp "${src}/${file}" $out\n''))
  47
  48          # concatenate all commands into one string
  49          lib.concatStrings
  50
  51          # make that string into a nix derivation
  52          (pkgs.runCommand "copy-to-out" {})
  53
  54        ]
  55        => <drv which copies all files to $out>
  56
  57      The output type of each function has to be the input type
  58      of the next function, and the last function returns the
  59      final value.
  60   */
  61   pipe = val: functions:
  62     let reverseApply = x: f: f x;
  63     in builtins.foldl' reverseApply val functions;
  64
  65   # note please don’t add a function like `compose = flip pipe`.
  66   # This would confuse users, because the order of the functions
  67   # in the list is not clear. With pipe, it’s obvious that it
  68   # goes first-to-last. With `compose`, not so much.
  69
  70   ## Named versions corresponding to some builtin operators.
  71
  72   /* Concatenate two lists
  73
  74      Type: concat :: [a] -> [a] -> [a]
  75
  76      Example:
  77        concat [ 1 2 ] [ 3 4 ]
  78        => [ 1 2 3 4 ]
  79   */
  80   concat = x: y: x ++ y;
  81
  82   /* boolean “or” */
  83   or = x: y: x || y;
  84
  85   /* boolean “and” */
  86   and = x: y: x && y;
  87
  88   /* bitwise “and” */
  89   bitAnd = builtins.bitAnd
  90     or (import ./zip-int-bits.nix
  91         (a: b: if a==1 && b==1 then 1 else 0));
  92
  93   /* bitwise “or” */
  94   bitOr = builtins.bitOr
  95     or (import ./zip-int-bits.nix
  96         (a: b: if a==1 || b==1 then 1 else 0));
  97
  98   /* bitwise “xor” */
  99   bitXor = builtins.bitXor
 100     or (import ./zip-int-bits.nix
 101         (a: b: if a!=b then 1 else 0));
 102
 103   /* bitwise “not” */
 104   bitNot = builtins.sub (-1);
 105
 106   /* Convert a boolean to a string.
 107
 108      This function uses the strings "true" and "false" to represent
 109      boolean values. Calling `toString` on a bool instead returns "1"
 110      and "" (sic!).
 111
 112      Type: boolToString :: bool -> string
 113   */
 114   boolToString = b: if b then "true" else "false";
 115
 116   /* Merge two attribute sets shallowly, right side trumps left
 117
 118      mergeAttrs :: attrs -> attrs -> attrs
 119
 120      Example:
 121        mergeAttrs { a = 1; b = 2; } { b = 3; c = 4; }
 122        => { a = 1; b = 3; c = 4; }
 123   */
 124   mergeAttrs =
 125     # Left attribute set
 126     x:
 127     # Right attribute set (higher precedence for equal keys)
 128     y: x // y;
 129
 130   /* Flip the order of the arguments of a binary function.
 131
 132      Type: flip :: (a -> b -> c) -> (b -> a -> c)
 133
 134      Example:
 135        flip concat [1] [2]
 136        => [ 2 1 ]
 137   */
 138   flip = f: a: b: f b a;
 139
 140   /* Apply function if the supplied argument is non-null.
 141
 142      Example:
 143        mapNullable (x: x+1) null
 144        => null
 145        mapNullable (x: x+1) 22
 146        => 23
 147   */
 148   mapNullable =
 149     # Function to call
 150     f:
 151     # Argument to check for null before passing it to `f`
 152     a: if a == null then a else f a;
 153
 154   # Pull in some builtins not included elsewhere.
 155   inherit (builtins)
 156     pathExists readFile isBool
 157     isInt isFloat add sub lessThan
 158     seq deepSeq genericClosure;
 159
 160
 161   ## nixpkgs version strings
 162
 163   /* Returns the current full nixpkgs version number. */
 164   version = release + versionSuffix;
 165
 166   /* Returns the current nixpkgs release number as string. */
 167   release = lib.strings.fileContents ../.version;
 168
 169   /* The latest release that is supported, at the time of release branch-off,
 170      if applicable.
 171
 172      Ideally, out-of-tree modules should be able to evaluate cleanly with all
 173      supported Nixpkgs versions (master, release and old release until EOL).
 174      So if possible, deprecation warnings should take effect only when all
 175      out-of-tree expressions/libs/modules can upgrade to the new way without
 176      losing support for supported Nixpkgs versions.
 177
 178      This release number allows deprecation warnings to be implemented such that
 179      they take effect as soon as the oldest release reaches end of life. */
 180   oldestSupportedRelease =
 181     # Update on master only. Do not backport.
 182     2305;
 183
 184   /* Whether a feature is supported in all supported releases (at the time of
 185      release branch-off, if applicable). See `oldestSupportedRelease`. */
 186   isInOldestRelease =
 187     /* Release number of feature introduction as an integer, e.g. 2111 for 21.11.
 188        Set it to the upcoming release, matching the nixpkgs/.version file.
 189     */
 190     release:
 191       release <= lib.trivial.oldestSupportedRelease;
 192
 193   /* Returns the current nixpkgs release code name.
 194
 195      On each release the first letter is bumped and a new animal is chosen
 196      starting with that new letter.
 197   */
 198   codeName = "Tapir";
 199
 200   /* Returns the current nixpkgs version suffix as string. */
 201   versionSuffix =
 202     let suffixFile = ../.version-suffix;
 203     in if pathExists suffixFile
 204     then lib.strings.fileContents suffixFile
 205     else "pre-git";
 206
 207   /* Attempts to return the the current revision of nixpkgs and
 208      returns the supplied default value otherwise.
 209
 210      Type: revisionWithDefault :: string -> string
 211   */
 212   revisionWithDefault =
 213     # Default value to return if revision can not be determined
 214     default:
 215     let
 216       revisionFile = "${toString ./..}/.git-revision";
 217       gitRepo      = "${toString ./..}/.git";
 218     in if lib.pathIsGitRepo gitRepo
 219        then lib.commitIdFromGitRepo gitRepo
 220        else if lib.pathExists revisionFile then lib.fileContents revisionFile
 221        else default;
 222
 223   nixpkgsVersion = builtins.trace "`lib.nixpkgsVersion` is deprecated, use `lib.version` instead!" version;
 224
 225   /* Determine whether the function is being called from inside a Nix
 226      shell.
 227
 228      Type: inNixShell :: bool
 229   */
 230   inNixShell = builtins.getEnv "IN_NIX_SHELL" != "";
 231
 232   /* Determine whether the function is being called from inside pure-eval mode
 233      by seeing whether `builtins` contains `currentSystem`. If not, we must be in
 234      pure-eval mode.
 235
 236      Type: inPureEvalMode :: bool
 237   */
 238   inPureEvalMode = ! builtins ? currentSystem;
 239
 240   ## Integer operations
 241
 242   /* Return minimum of two numbers. */
 243   min = x: y: if x < y then x else y;
 244
 245   /* Return maximum of two numbers. */
 246   max = x: y: if x > y then x else y;
 247
 248   /* Integer modulus
 249
 250      Example:
 251        mod 11 10
 252        => 1
 253        mod 1 10
 254        => 1
 255   */
 256   mod = base: int: base - (int * (builtins.div base int));
 257
 258
 259   ## Comparisons
 260
 261   /* C-style comparisons
 262
 263      a < b,  compare a b => -1
 264      a == b, compare a b => 0
 265      a > b,  compare a b => 1
 266   */
 267   compare = a: b:
 268     if a < b
 269     then -1
 270     else if a > b
 271          then 1
 272          else 0;
 273
 274   /* Split type into two subtypes by predicate `p`, take all elements
 275      of the first subtype to be less than all the elements of the
 276      second subtype, compare elements of a single subtype with `yes`
 277      and `no` respectively.
 278
 279      Type: (a -> bool) -> (a -> a -> int) -> (a -> a -> int) -> (a -> a -> int)
 280
 281      Example:
 282        let cmp = splitByAndCompare (hasPrefix "foo") compare compare; in
 283
 284        cmp "a" "z" => -1
 285        cmp "fooa" "fooz" => -1
 286
 287        cmp "f" "a" => 1
 288        cmp "fooa" "a" => -1
 289        # while
 290        compare "fooa" "a" => 1
 291   */
 292   splitByAndCompare =
 293     # Predicate
 294     p:
 295     # Comparison function if predicate holds for both values
 296     yes:
 297     # Comparison function if predicate holds for neither value
 298     no:
 299     # First value to compare
 300     a:
 301     # Second value to compare
 302     b:
 303     if p a
 304     then if p b then yes a b else -1
 305     else if p b then 1 else no a b;
 306
 307
 308   /* Reads a JSON file.
 309
 310      Type: importJSON :: path -> any
 311   */
 312   importJSON = path:
 313     builtins.fromJSON (builtins.readFile path);
 314
 315   /* Reads a TOML file.
 316
 317      Type: importTOML :: path -> any
 318   */
 319   importTOML = path:
 320     builtins.fromTOML (builtins.readFile path);
 321
 322   ## Warnings
 323
 324   # See https://github.com/NixOS/nix/issues/749. Eventually we'd like these
 325   # to expand to Nix builtins that carry metadata so that Nix can filter out
 326   # the INFO messages without parsing the message string.
 327   #
 328   # Usage:
 329   # {
 330   #   foo = lib.warn "foo is deprecated" oldFoo;
 331   #   bar = lib.warnIf (bar == "") "Empty bar is deprecated" bar;
 332   # }
 333   #
 334   # TODO: figure out a clever way to integrate location information from
 335   # something like __unsafeGetAttrPos.
 336
 337   /*
 338     Print a warning before returning the second argument. This function behaves
 339     like `builtins.trace`, but requires a string message and formats it as a
 340     warning, including the `warning: ` prefix.
 341
 342     To get a call stack trace and abort evaluation, set the environment variable
 343     `NIX_ABORT_ON_WARN=true` and set the Nix options `--option pure-eval false --show-trace`
 344
 345     Type: string -> a -> a
 346   */
 347   warn =
 348     if lib.elem (builtins.getEnv "NIX_ABORT_ON_WARN") ["1" "true" "yes"]
 349     then msg: builtins.trace "\e[1;31mwarning: ${msg}\e[0m" (abort "NIX_ABORT_ON_WARN=true; warnings are treated as unrecoverable errors.")
 350     else msg: builtins.trace "\e[1;31mwarning: ${msg}\e[0m";
 351
 352   /*
 353     Like warn, but only warn when the first argument is `true`.
 354
 355     Type: bool -> string -> a -> a
 356   */
 357   warnIf = cond: msg: if cond then warn msg else x: x;
 358
 359   /*
 360     Like warnIf, but negated (warn if the first argument is `false`).
 361
 362     Type: bool -> string -> a -> a
 363   */
 364   warnIfNot = cond: msg: if cond then x: x else warn msg;
 365
 366   /*
 367     Like the `assert b; e` expression, but with a custom error message and
 368     without the semicolon.
 369
 370     If true, return the identity function, `r: r`.
 371
 372     If false, throw the error message.
 373
 374     Calls can be juxtaposed using function application, as `(r: r) a = a`, so
 375     `(r: r) (r: r) a = a`, and so forth.
 376
 377     Type: bool -> string -> a -> a
 378
 379     Example:
 380
 381         throwIfNot (lib.isList overlays) "The overlays argument to nixpkgs must be a list."
 382         lib.foldr (x: throwIfNot (lib.isFunction x) "All overlays passed to nixpkgs must be functions.") (r: r) overlays
 383         pkgs
 384
 385   */
 386   throwIfNot = cond: msg: if cond then x: x else throw msg;
 387
 388   /*
 389     Like throwIfNot, but negated (throw if the first argument is `true`).
 390
 391     Type: bool -> string -> a -> a
 392   */
 393   throwIf = cond: msg: if cond then throw msg else x: x;
 394
 395   /* Check if the elements in a list are valid values from a enum, returning the identity function, or throwing an error message otherwise.
 396
 397      Example:
 398        let colorVariants = ["bright" "dark" "black"]
 399        in checkListOfEnum "color variants" [ "standard" "light" "dark" ] colorVariants;
 400        =>
 401        error: color variants: bright, black unexpected; valid ones: standard, light, dark
 402
 403      Type: String -> List ComparableVal -> List ComparableVal -> a -> a
 404   */
 405   checkListOfEnum = msg: valid: given:
 406     let
 407       unexpected = lib.subtractLists valid given;
 408     in
 409       lib.throwIfNot (unexpected == [])
 410         "${msg}: ${builtins.concatStringsSep ", " (builtins.map builtins.toString unexpected)} unexpected; valid ones: ${builtins.concatStringsSep ", " (builtins.map builtins.toString valid)}";
 411
 412   info = msg: builtins.trace "INFO: ${msg}";
 413
 414   showWarnings = warnings: res: lib.foldr (w: x: warn w x) res warnings;
 415
 416   ## Function annotations
 417
 418   /* Add metadata about expected function arguments to a function.
 419      The metadata should match the format given by
 420      builtins.functionArgs, i.e. a set from expected argument to a bool
 421      representing whether that argument has a default or not.
 422      setFunctionArgs : (a → b) → Map String Bool → (a → b)
 423
 424      This function is necessary because you can't dynamically create a
 425      function of the { a, b ? foo, ... }: format, but some facilities
 426      like callPackage expect to be able to query expected arguments.
 427   */
 428   setFunctionArgs = f: args:
 429     { # TODO: Should we add call-time "type" checking like built in?
 430       __functor = self: f;
 431       __functionArgs = args;
 432     };
 433
 434   /* Extract the expected function arguments from a function.
 435      This works both with nix-native { a, b ? foo, ... }: style
 436      functions and functions with args set with 'setFunctionArgs'. It
 437      has the same return type and semantics as builtins.functionArgs.
 438      setFunctionArgs : (a → b) → Map String Bool.
 439   */
 440   functionArgs = f:
 441     if f ? __functor
 442     then f.__functionArgs or (lib.functionArgs (f.__functor f))
 443     else builtins.functionArgs f;
 444
 445   /* Check whether something is a function or something
 446      annotated with function args.
 447   */
 448   isFunction = f: builtins.isFunction f ||
 449     (f ? __functor && isFunction (f.__functor f));
 450
 451   /*
 452     `mirrorFunctionArgs f g` creates a new function `g'` with the same behavior as `g` (`g' x == g x`)
 453     but its function arguments mirroring `f` (`lib.functionArgs g' == lib.functionArgs f`).
 454
 455     Type:
 456       mirrorFunctionArgs :: (a -> b) -> (a -> c) -> (a -> c)
 457
 458     Example:
 459       addab = {a, b}: a + b
 460       addab { a = 2; b = 4; }
 461       => 6
 462       lib.functionArgs addab
 463       => { a = false; b = false; }
 464       addab1 = attrs: addab attrs + 1
 465       addab1 { a = 2; b = 4; }
 466       => 7
 467       lib.functionArgs addab1
 468       => { }
 469       addab1' = lib.mirrorFunctionArgs addab addab1
 470       addab1' { a = 2; b = 4; }
 471       => 7
 472       lib.functionArgs addab1'
 473       => { a = false; b = false; }
 474   */
 475   mirrorFunctionArgs =
 476     # Function to provide the argument metadata
 477     f:
 478     let
 479       fArgs = functionArgs f;
 480     in
 481     # Function to set the argument metadata to
 482     g:
 483     setFunctionArgs g fArgs;
 484
 485   /*
 486     Turns any non-callable values into constant functions.
 487     Returns callable values as is.
 488
 489     Example:
 490
 491       nix-repl> lib.toFunction 1 2
 492       1
 493
 494       nix-repl> lib.toFunction (x: x + 1) 2
 495       3
 496   */
 497   toFunction =
 498     # Any value
 499     v:
 500     if isFunction v
 501     then v
 502     else k: v;
 503
 504   /* Convert the given positive integer to a string of its hexadecimal
 505      representation. For example:
 506
 507      toHexString 0 => "0"
 508
 509      toHexString 16 => "10"
 510
 511      toHexString 250 => "FA"
 512   */
 513   toHexString = i:
 514     let
 515       toHexDigit = d:
 516         if d < 10
 517         then toString d
 518         else
 519           {
 520             "10" = "A";
 521             "11" = "B";
 522             "12" = "C";
 523             "13" = "D";
 524             "14" = "E";
 525             "15" = "F";
 526           }.${toString d};
 527     in
 528       lib.concatMapStrings toHexDigit (toBaseDigits 16 i);
 529
 530   /* `toBaseDigits base i` converts the positive integer i to a list of its
 531      digits in the given base. For example:
 532
 533      toBaseDigits 10 123 => [ 1 2 3 ]
 534
 535      toBaseDigits 2 6 => [ 1 1 0 ]
 536
 537      toBaseDigits 16 250 => [ 15 10 ]
 538   */
 539   toBaseDigits = base: i:
 540     let
 541       go = i:
 542         if i < base
 543         then [i]
 544         else
 545           let
 546             r = i - ((i / base) * base);
 547             q = (i - r) / base;
 548           in
 549             [r] ++ go q;
 550     in
 551       assert (isInt base);
 552       assert (isInt i);
 553       assert (base >= 2);
 554       assert (i >= 0);
 555       lib.reverseList (go i);
 556 }