lib.trivial: miscellaneous functions

lib.trivial.id

Type: id :: a -> a

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

x

The value to return

Located at lib/trivial.nix:12 in <nixpkgs>.

lib.trivial.const

Type: const :: a -> b -> a

The constant function

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

x

Value to return

y

Value to ignore

let f = const 5; in f 10
=> 5

Located at lib/trivial.nix:26 in <nixpkgs>.

lib.trivial.pipe

Type: pipe :: a -> [<functions>] -> <return type of last function>

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

val

Function argument

functions

Function argument

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.

Located at lib/trivial.nix:61 in <nixpkgs>.

lib.trivial.concat

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

Concatenate two lists

x

Function argument

y

Function argument

concat [ 1 2 ] [ 3 4 ]
=> [ 1 2 3 4 ]

Located at lib/trivial.nix:80 in <nixpkgs>.

lib.trivial.or

boolean “or”

x

Function argument

y

Function argument

Located at lib/trivial.nix:83 in <nixpkgs>.

lib.trivial.and

boolean “and”

x

Function argument

y

Function argument

Located at lib/trivial.nix:86 in <nixpkgs>.

lib.trivial.bitAnd

bitwise “and”

Located at lib/trivial.nix:89 in <nixpkgs>.

lib.trivial.bitOr

bitwise “or”

Located at lib/trivial.nix:94 in <nixpkgs>.

lib.trivial.bitXor

bitwise “xor”

Located at lib/trivial.nix:99 in <nixpkgs>.

lib.trivial.bitNot

bitwise “not”

Located at lib/trivial.nix:104 in <nixpkgs>.

lib.trivial.boolToString

Type: boolToString :: bool -> string

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!).

b

Function argument

Located at lib/trivial.nix:114 in <nixpkgs>.

lib.trivial.mergeAttrs

Merge two attribute sets shallowly, right side trumps left

mergeAttrs :: attrs -> attrs -> attrs

x

Left attribute set

y

Right attribute set (higher precedence for equal keys)

mergeAttrs { a = 1; b = 2; } { b = 3; c = 4; }
=> { a = 1; b = 3; c = 4; }

Located at lib/trivial.nix:124 in <nixpkgs>.

lib.trivial.flip

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

Flip the order of the arguments of a binary function.

f

Function argument

a

Function argument

b

Function argument

flip concat [1] [2]
=> [ 2 1 ]

Located at lib/trivial.nix:138 in <nixpkgs>.

lib.trivial.mapNullable

Apply function if the supplied argument is non-null.

f

Function to call

a

Argument to check for null before passing it to f

mapNullable (x: x+1) null
=> null
mapNullable (x: x+1) 22
=> 23

Located at lib/trivial.nix:148 in <nixpkgs>.

lib.trivial.version

Returns the current full nixpkgs version number.

Located at lib/trivial.nix:164 in <nixpkgs>.

lib.trivial.release

Returns the current nixpkgs release number as string.

Located at lib/trivial.nix:167 in <nixpkgs>.

lib.trivial.oldestSupportedRelease

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.

Located at lib/trivial.nix:180 in <nixpkgs>.

lib.trivial.isInOldestRelease

Whether a feature is supported in all supported releases (at the time of release branch-off, if applicable). See oldestSupportedRelease.

release

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.

Located at lib/trivial.nix:186 in <nixpkgs>.

lib.trivial.codeName

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.

Located at lib/trivial.nix:198 in <nixpkgs>.

lib.trivial.versionSuffix

Returns the current nixpkgs version suffix as string.

Located at lib/trivial.nix:201 in <nixpkgs>.

lib.trivial.revisionWithDefault

Type: revisionWithDefault :: string -> string

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

default

Default value to return if revision can not be determined

Located at lib/trivial.nix:212 in <nixpkgs>.

lib.trivial.inNixShell

Type: inNixShell :: bool

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

Located at lib/trivial.nix:230 in <nixpkgs>.

lib.trivial.inPureEvalMode

Type: inPureEvalMode :: bool

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.

Located at lib/trivial.nix:238 in <nixpkgs>.

lib.trivial.min

Return minimum of two numbers.

x

Function argument

y

Function argument

Located at lib/trivial.nix:243 in <nixpkgs>.

lib.trivial.max

Return maximum of two numbers.

x

Function argument

y

Function argument

Located at lib/trivial.nix:246 in <nixpkgs>.

lib.trivial.mod

Integer modulus

base

Function argument

int

Function argument

mod 11 10
=> 1
mod 1 10
=> 1

Located at lib/trivial.nix:256 in <nixpkgs>.

lib.trivial.compare

C-style comparisons

a < b, compare a b => -1 a == b, compare a b => 0 a > b, compare a b => 1

a

Function argument

b

Function argument

Located at lib/trivial.nix:267 in <nixpkgs>.

lib.trivial.splitByAndCompare

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

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.

p

Predicate

yes

Comparison function if predicate holds for both values

no

Comparison function if predicate holds for neither value

a

First value to compare

b

Second value to compare

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

Located at lib/trivial.nix:292 in <nixpkgs>.

lib.trivial.importJSON

Type: importJSON :: path -> any

Reads a JSON file.

path

Function argument

Located at lib/trivial.nix:312 in <nixpkgs>.

lib.trivial.importTOML

Type: importTOML :: path -> any

Reads a TOML file.

path

Function argument

Located at lib/trivial.nix:319 in <nixpkgs>.

lib.trivial.warn

Type: string -> a -> a

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

Located at lib/trivial.nix:347 in <nixpkgs>.

lib.trivial.warnIf

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

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

cond

Function argument

msg

Function argument

Located at lib/trivial.nix:357 in <nixpkgs>.

lib.trivial.warnIfNot

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

Like warnIf, but negated (warn if the first argument is false).

cond

Function argument

msg

Function argument

Located at lib/trivial.nix:364 in <nixpkgs>.

lib.trivial.throwIfNot

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

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.

cond

Function argument

msg

Function argument

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

Located at lib/trivial.nix:386 in <nixpkgs>.

lib.trivial.throwIf

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

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

cond

Function argument

msg

Function argument

Located at lib/trivial.nix:393 in <nixpkgs>.

lib.trivial.checkListOfEnum

Type: String -> List ComparableVal -> List ComparableVal -> a -> a

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

msg

Function argument

valid

Function argument

given

Function argument

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

Located at lib/trivial.nix:405 in <nixpkgs>.

lib.trivial.setFunctionArgs

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.

f

Function argument

args

Function argument

Located at lib/trivial.nix:428 in <nixpkgs>.

lib.trivial.functionArgs

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.

f

Function argument

Located at lib/trivial.nix:440 in <nixpkgs>.

lib.trivial.isFunction

Check whether something is a function or something annotated with function args.

f

Function argument

Located at lib/trivial.nix:448 in <nixpkgs>.

lib.trivial.toFunction

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

v

Any value

nix-repl> lib.toFunction 1 2
1

nix-repl> lib.toFunction (x: x + 1) 2
3

Located at lib/trivial.nix:463 in <nixpkgs>.

lib.trivial.toHexString

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

toHexString 0 => "0"

toHexString 16 => "10"

toHexString 250 => "FA"

i

Function argument

Located at lib/trivial.nix:479 in <nixpkgs>.

lib.trivial.toBaseDigits

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 ]

base

Function argument

i

Function argument

Located at lib/trivial.nix:505 in <nixpkgs>.