about summary refs log tree commit diff
path: root/lib/trivial.nix
blob: a89c1aa25b1f721e5f69039d10d36af2e4f746e0 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
{ lib }:

rec {

  ## Simple (higher order) functions

  /* The identity function
     For when you need a function that does “nothing”.

     Type: id :: a -> a
  */
  id =
    # The value to return
    x: x;

  /* The constant function

     Ignores the second argument. If called with only one argument,
     constructs a function that always returns a static value.

     Type: const :: a -> b -> a
     Example:
       let f = const 5; in f 10
       => 5
  */
  const =
    # Value to return
    x:
    # Value to ignore
    y: x;

  /* Pipes a value through a list of functions, left to right.

     Type: pipe :: a -> [<functions>] -> <return type of last function>
     Example:
       pipe 2 [
         (x: x + 2)  # 2 + 2 = 4
         (x: x * 2)  # 4 * 2 = 8
       ]
       => 8

       # ideal to do text transformations
       pipe [ "a/b" "a/c" ] [

         # create the cp command
         (map (file: ''cp "${src}/${file}" $out\n''))

         # concatenate all commands into one string
         lib.concatStrings

         # make that string into a nix derivation
         (pkgs.runCommand "copy-to-out" {})

       ]
       => <drv which copies all files to $out>

     The output type of each function has to be the input type
     of the next function, and the last function returns the
     final value.
  */
  pipe = val: functions:
    let reverseApply = x: f: f x;
    in builtins.foldl' reverseApply val functions;

  # note please don’t add a function like `compose = flip pipe`.
  # This would confuse users, because the order of the functions
  # in the list is not clear. With pipe, it’s obvious that it
  # goes first-to-last. With `compose`, not so much.

  ## Named versions corresponding to some builtin operators.

  /* Concatenate two lists

     Type: concat :: [a] -> [a] -> [a]

     Example:
       concat [ 1 2 ] [ 3 4 ]
       => [ 1 2 3 4 ]
  */
  concat = x: y: x ++ y;

  /* boolean “or” */
  or = x: y: x || y;

  /* boolean “and” */
  and = x: y: x && y;

  /* bitwise “and” */
  bitAnd = builtins.bitAnd
    or (import ./zip-int-bits.nix
        (a: b: if a==1 && b==1 then 1 else 0));

  /* bitwise “or” */
  bitOr = builtins.bitOr
    or (import ./zip-int-bits.nix
        (a: b: if a==1 || b==1 then 1 else 0));

  /* bitwise “xor” */
  bitXor = builtins.bitXor
    or (import ./zip-int-bits.nix
        (a: b: if a!=b then 1 else 0));

  /* bitwise “not” */
  bitNot = builtins.sub (-1);

  /* Convert a boolean to a string.

     This function uses the strings "true" and "false" to represent
     boolean values. Calling `toString` on a bool instead returns "1"
     and "" (sic!).

     Type: boolToString :: bool -> string
  */
  boolToString = b: if b then "true" else "false";

  /* Merge two attribute sets shallowly, right side trumps left

     mergeAttrs :: attrs -> attrs -> attrs

     Example:
       mergeAttrs { a = 1; b = 2; } { b = 3; c = 4; }
       => { a = 1; b = 3; c = 4; }
  */
  mergeAttrs =
    # Left attribute set
    x:
    # Right attribute set (higher precedence for equal keys)
    y: x // y;

  /* Flip the order of the arguments of a binary function.

     Type: flip :: (a -> b -> c) -> (b -> a -> c)

     Example:
       flip concat [1] [2]
       => [ 2 1 ]
  */
  flip = f: a: b: f b a;

  /* Apply function if the supplied argument is non-null.

     Example:
       mapNullable (x: x+1) null
       => null
       mapNullable (x: x+1) 22
       => 23
  */
  mapNullable =
    # Function to call
    f:
    # Argument to check for null before passing it to `f`
    a: if a == null then a else f a;

  # Pull in some builtins not included elsewhere.
  inherit (builtins)
    pathExists readFile isBool
    isInt isFloat add sub lessThan
    seq deepSeq genericClosure;


  ## nixpkgs version strings

  /* Returns the current full nixpkgs version number. */
  version = release + versionSuffix;

  /* Returns the current nixpkgs release number as string. */
  release = lib.strings.fileContents ../.version;

  /* The latest release that is supported, at the time of release branch-off,
     if applicable.

     Ideally, out-of-tree modules should be able to evaluate cleanly with all
     supported Nixpkgs versions (master, release and old release until EOL).
     So if possible, deprecation warnings should take effect only when all
     out-of-tree expressions/libs/modules can upgrade to the new way without
     losing support for supported Nixpkgs versions.

     This release number allows deprecation warnings to be implemented such that
     they take effect as soon as the oldest release reaches end of life. */
  oldestSupportedRelease =
    # Update on master only. Do not backport.
    2305;

  /* Whether a feature is supported in all supported releases (at the time of
     release branch-off, if applicable). See `oldestSupportedRelease`. */
  isInOldestRelease =
    /* Release number of feature introduction as an integer, e.g. 2111 for 21.11.
       Set it to the upcoming release, matching the nixpkgs/.version file.
    */
    release:
      release <= lib.trivial.oldestSupportedRelease;

  /* Returns the current nixpkgs release code name.

     On each release the first letter is bumped and a new animal is chosen
     starting with that new letter.
  */
  codeName = "Tapir";

  /* Returns the current nixpkgs version suffix as string. */
  versionSuffix =
    let suffixFile = ../.version-suffix;
    in if pathExists suffixFile
    then lib.strings.fileContents suffixFile
    else "pre-git";

  /* Attempts to return the the current revision of nixpkgs and
     returns the supplied default value otherwise.

     Type: revisionWithDefault :: string -> string
  */
  revisionWithDefault =
    # Default value to return if revision can not be determined
    default:
    let
      revisionFile = "${toString ./..}/.git-revision";
      gitRepo      = "${toString ./..}/.git";
    in if lib.pathIsGitRepo gitRepo
       then lib.commitIdFromGitRepo gitRepo
       else if lib.pathExists revisionFile then lib.fileContents revisionFile
       else default;

  nixpkgsVersion = builtins.trace "`lib.nixpkgsVersion` is deprecated, use `lib.version` instead!" version;

  /* Determine whether the function is being called from inside a Nix
     shell.

     Type: inNixShell :: bool
  */
  inNixShell = builtins.getEnv "IN_NIX_SHELL" != "";

  /* Determine whether the function is being called from inside pure-eval mode
     by seeing whether `builtins` contains `currentSystem`. If not, we must be in
     pure-eval mode.

     Type: inPureEvalMode :: bool
  */
  inPureEvalMode = ! builtins ? currentSystem;

  ## Integer operations

  /* Return minimum of two numbers. */
  min = x: y: if x < y then x else y;

  /* Return maximum of two numbers. */
  max = x: y: if x > y then x else y;

  /* Integer modulus

     Example:
       mod 11 10
       => 1
       mod 1 10
       => 1
  */
  mod = base: int: base - (int * (builtins.div base int));


  ## Comparisons

  /* C-style comparisons

     a < b,  compare a b => -1
     a == b, compare a b => 0
     a > b,  compare a b => 1
  */
  compare = a: b:
    if a < b
    then -1
    else if a > b
         then 1
         else 0;

  /* Split type into two subtypes by predicate `p`, take all elements
     of the first subtype to be less than all the elements of the
     second subtype, compare elements of a single subtype with `yes`
     and `no` respectively.

     Type: (a -> bool) -> (a -> a -> int) -> (a -> a -> int) -> (a -> a -> int)

     Example:
       let cmp = splitByAndCompare (hasPrefix "foo") compare compare; in

       cmp "a" "z" => -1
       cmp "fooa" "fooz" => -1

       cmp "f" "a" => 1
       cmp "fooa" "a" => -1
       # while
       compare "fooa" "a" => 1
  */
  splitByAndCompare =
    # Predicate
    p:
    # Comparison function if predicate holds for both values
    yes:
    # Comparison function if predicate holds for neither value
    no:
    # First value to compare
    a:
    # Second value to compare
    b:
    if p a
    then if p b then yes a b else -1
    else if p b then 1 else no a b;


  /* Reads a JSON file.

     Type: importJSON :: path -> any
  */
  importJSON = path:
    builtins.fromJSON (builtins.readFile path);

  /* Reads a TOML file.

     Type: importTOML :: path -> any
  */
  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`

    Type: 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}";

  /*
    Like warn, but only warn when the first argument is `true`.

    Type: 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`).

    Type: bool -> string -> a -> a
  */
  warnIfNot = cond: msg: if cond then x: x else warn msg;

  /*
    Like the `assert b; e` expression, but with a custom error message and
    without the semicolon.

    If true, return the identity function, `r: r`.

    If false, throw the error message.

    Calls can be juxtaposed using function application, as `(r: r) a = a`, so
    `(r: r) (r: r) a = a`, and so forth.

    Type: bool -> string -> a -> a

    Example:

        throwIfNot (lib.isList overlays) "The overlays argument to nixpkgs must be a list."
        lib.foldr (x: throwIfNot (lib.isFunction x) "All overlays passed to nixpkgs must be functions.") (r: r) overlays
        pkgs

  */
  throwIfNot = cond: msg: if cond then x: x else throw msg;

  /*
    Like throwIfNot, but negated (throw if the first argument is `true`).

    Type: bool -> string -> a -> a
  */
  throwIf = cond: msg: if cond then throw msg else x: x;

  /* Check if the elements in a list are valid values from a enum, returning the identity function, or throwing an error message otherwise.

     Example:
       let colorVariants = ["bright" "dark" "black"]
       in checkListOfEnum "color variants" [ "standard" "light" "dark" ] colorVariants;
       =>
       error: color variants: bright, black unexpected; valid ones: standard, light, dark

     Type: String -> List ComparableVal -> List ComparableVal -> a -> a
  */
  checkListOfEnum = msg: valid: given:
    let
      unexpected = lib.subtractLists valid given;
    in
      lib.throwIfNot (unexpected == [])
        "${msg}: ${builtins.concatStringsSep ", " (builtins.map builtins.toString unexpected)} unexpected; valid ones: ${builtins.concatStringsSep ", " (builtins.map builtins.toString valid)}";

  info = msg: builtins.trace "INFO: ${msg}";

  showWarnings = warnings: res: lib.foldr (w: x: warn w x) res warnings;

  ## Function annotations

  /* Add metadata about expected function arguments to a function.
     The metadata should match the format given by
     builtins.functionArgs, i.e. a set from expected argument to a bool
     representing whether that argument has a default or not.
     setFunctionArgs : (a → b) → Map String Bool → (a → b)

     This function is necessary because you can't dynamically create a
     function of the { a, b ? foo, ... }: format, but some facilities
     like callPackage expect to be able to query expected arguments.
  */
  setFunctionArgs = f: args:
    { # TODO: Should we add call-time "type" checking like built in?
      __functor = self: f;
      __functionArgs = args;
    };

  /* Extract the expected function arguments from a function.
     This works both with nix-native { a, b ? foo, ... }: style
     functions and functions with args set with 'setFunctionArgs'. It
     has the same return type and semantics as builtins.functionArgs.
     setFunctionArgs : (a → b) → Map String Bool.
  */
  functionArgs = f:
    if f ? __functor
    then f.__functionArgs or (lib.functionArgs (f.__functor f))
    else builtins.functionArgs f;

  /* Check whether something is a function or something
     annotated with function args.
  */
  isFunction = f: builtins.isFunction f ||
    (f ? __functor && isFunction (f.__functor f));

  /*
    `mirrorFunctionArgs f g` creates a new function `g'` with the same behavior as `g` (`g' x == g x`)
    but its function arguments mirroring `f` (`lib.functionArgs g' == lib.functionArgs f`).

    Type:
      mirrorFunctionArgs :: (a -> b) -> (a -> c) -> (a -> c)

    Example:
      addab = {a, b}: a + b
      addab { a = 2; b = 4; }
      => 6
      lib.functionArgs addab
      => { a = false; b = false; }
      addab1 = attrs: addab attrs + 1
      addab1 { a = 2; b = 4; }
      => 7
      lib.functionArgs addab1
      => { }
      addab1' = lib.mirrorFunctionArgs addab addab1
      addab1' { a = 2; b = 4; }
      => 7
      lib.functionArgs addab1'
      => { a = false; b = false; }
  */
  mirrorFunctionArgs =
    # Function to provide the argument metadata
    f:
    let
      fArgs = functionArgs f;
    in
    # Function to set the argument metadata to
    g:
    setFunctionArgs g fArgs;

  /*
    Turns any non-callable values into constant functions.
    Returns callable values as is.

    Example:

      nix-repl> lib.toFunction 1 2
      1

      nix-repl> lib.toFunction (x: x + 1) 2
      3
  */
  toFunction =
    # Any value
    v:
    if isFunction v
    then v
    else k: v;

  /* Convert the given positive integer to a string of its hexadecimal
     representation. For example:

     toHexString 0 => "0"

     toHexString 16 => "10"

     toHexString 250 => "FA"
  */
  toHexString = i:
    let
      toHexDigit = d:
        if d < 10
        then toString d
        else
          {
            "10" = "A";
            "11" = "B";
            "12" = "C";
            "13" = "D";
            "14" = "E";
            "15" = "F";
          }.${toString d};
    in
      lib.concatMapStrings toHexDigit (toBaseDigits 16 i);

  /* `toBaseDigits base i` converts the positive integer i to a list of its
     digits in the given base. For example:

     toBaseDigits 10 123 => [ 1 2 3 ]

     toBaseDigits 2 6 => [ 1 1 0 ]

     toBaseDigits 16 250 => [ 15 10 ]
  */
  toBaseDigits = base: i:
    let
      go = i:
        if i < base
        then [i]
        else
          let
            r = i - ((i / base) * base);
            q = (i - r) / base;
          in
            [r] ++ go q;
    in
      assert (isInt base);
      assert (isInt i);
      assert (base >= 2);
      assert (i >= 0);
      lib.reverseList (go i);
}