lib.trivial: miscellaneous functions
lib.trivial.id
The identity function For when you need a function that does “nothing”.
Inputs
x
: The value to return
Type
id :: a -> a
Located at lib/trivial.nix:39 in <nixpkgs>.
lib.trivial.const
The constant function
Ignores the second argument. If called with only one argument, constructs a function that always returns a static value.
Inputs
x
: Value to return
y
: Value to ignore
Type
const :: a -> b -> a
Examples
lib.trivial.const usage example
let f = const 5; in f 10
=> 5
Located at lib/trivial.nix:75 in <nixpkgs>.
lib.trivial.pipe
Pipes a value through a list of functions, left to right.
Inputs
value
: Value to start piping.
fns
: List of functions to apply sequentially.
Type
pipe :: a -> [<functions>] -> <return type of last function>
Examples
lib.trivial.pipe usage 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.
Located at lib/trivial.nix:131 in <nixpkgs>.
lib.trivial.concat
Concatenate two lists
Inputs
x
: 1. Function argument
y
: 2. Function argument
Type
concat :: [a] -> [a] -> [a]
Examples
lib.trivial.concat usage example
concat [ 1 2 ] [ 3 4 ]
=> [ 1 2 3 4 ]
Located at lib/trivial.nix:171 in <nixpkgs>.
lib.trivial.or
boolean “or”
Inputs
x
: 1. Function argument
y
: 2. Function argument
Located at lib/trivial.nix:187 in <nixpkgs>.
lib.trivial.and
boolean “and”
Inputs
x
: 1. Function argument
y
: 2. Function argument
Located at lib/trivial.nix:203 in <nixpkgs>.
lib.trivial.xor
boolean “exclusive or”
Inputs
x
: 1. Function argument
y
: 2. Function argument
Located at lib/trivial.nix:221 in <nixpkgs>.
lib.trivial.bitNot
bitwise “not”
Located at lib/trivial.nix:226 in <nixpkgs>.
lib.trivial.boolToString
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!).
Inputs
b
: 1. Function argument
Type
boolToString :: bool -> string
Located at lib/trivial.nix:248 in <nixpkgs>.
lib.trivial.mergeAttrs
Merge two attribute sets shallowly, right side trumps left
mergeAttrs :: attrs -> attrs -> attrs
Inputs
x
: Left attribute set
y
: Right attribute set (higher precedence for equal keys)
Examples
lib.trivial.mergeAttrs usage example
mergeAttrs { a = 1; b = 2; } { b = 3; c = 4; }
=> { a = 1; b = 3; c = 4; }
Located at lib/trivial.nix:278 in <nixpkgs>.
lib.trivial.flip
Flip the order of the arguments of a binary function.
Inputs
f
: 1. Function argument
a
: 2. Function argument
b
: 3. Function argument
Type
flip :: (a -> b -> c) -> (b -> a -> c)
Examples
lib.trivial.flip usage example
flip concat [1] [2]
=> [ 2 1 ]
Located at lib/trivial.nix:317 in <nixpkgs>.
lib.trivial.mapNullable
Apply function if the supplied argument is non-null.
Inputs
f
: Function to call
a
: Argument to check for null before passing it to f
Examples
lib.trivial.mapNullable usage example
mapNullable (x: x+1) null
=> null
mapNullable (x: x+1) 22
=> 23
Located at lib/trivial.nix:347 in <nixpkgs>.
lib.trivial.version
Returns the current full nixpkgs version number.
Located at lib/trivial.nix:363 in <nixpkgs>.
lib.trivial.release
Returns the current nixpkgs release number as string.
Located at lib/trivial.nix:368 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:383 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.
Inputs
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:399 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:409 in <nixpkgs>.
lib.trivial.versionSuffix
Returns the current nixpkgs version suffix as string.
Located at lib/trivial.nix:414 in <nixpkgs>.
lib.trivial.revisionWithDefault
Attempts to return the the current revision of nixpkgs and returns the supplied default value otherwise.
Inputs
default
: Default value to return if revision can not be determined
Type
revisionWithDefault :: string -> string
Located at lib/trivial.nix:437 in <nixpkgs>.
lib.trivial.inNixShell
Determine whether the function is being called from inside a Nix shell.
Type
inNixShell :: bool
Located at lib/trivial.nix:459 in <nixpkgs>.
lib.trivial.inPureEvalMode
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
Located at lib/trivial.nix:472 in <nixpkgs>.
lib.trivial.min
Return minimum of two numbers.
Inputs
x
: 1. Function argument
y
: 2. Function argument
Located at lib/trivial.nix:490 in <nixpkgs>.
lib.trivial.max
Return maximum of two numbers.
Inputs
x
: 1. Function argument
y
: 2. Function argument
Located at lib/trivial.nix:506 in <nixpkgs>.
lib.trivial.mod
Integer modulus
Inputs
base
: 1. Function argument
int
: 2. Function argument
Examples
lib.trivial.mod usage example
mod 11 10
=> 1
mod 1 10
=> 1
Located at lib/trivial.nix:536 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
Inputs
a
: 1. Function argument
b
: 2. Function argument
Located at lib/trivial.nix:559 in <nixpkgs>.
lib.trivial.splitByAndCompare
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.
Inputs
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
Type
(a -> bool) -> (a -> a -> int) -> (a -> a -> int) -> (a -> a -> int)
Examples
lib.trivial.splitByAndCompare usage 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
Located at lib/trivial.nix:619 in <nixpkgs>.
lib.trivial.importJSON
Reads a JSON file.
Examples
lib.trivial.importJSON usage example
example.json
{
"title": "Example JSON",
"hello": {
"world": "foo",
"bar": {
"foobar": true
}
}
}
importJSON ./example.json
=> {
title = "Example JSON";
hello = {
world = "foo";
bar = {
foobar = true;
};
};
}
Inputs
path
: 1. Function argument
Type
importJSON :: path -> any
Located at lib/trivial.nix:673 in <nixpkgs>.
lib.trivial.importTOML
Reads a TOML file.
Examples
lib.trivial.importTOML usage example
example.toml
title = "TOML Example"
[hello]
world = "foo"
[hello.bar]
foobar = true
importTOML ./example.toml
=> {
title = "TOML Example";
hello = {
world = "foo";
bar = {
foobar = true;
};
};
}
Inputs
path
: 1. Function argument
Type
importTOML :: path -> any
Located at lib/trivial.nix:721 in <nixpkgs>.
lib.trivial.warn
warn message value
Print a warning before returning the second argument.
See builtins.warn (Nix >= 2.23).
On older versions, the Nix 2.23 behavior is emulated with builtins.trace, including the NIX_ABORT_ON_WARN behavior, but not the nix.conf setting or command line option.
Inputs
message (String)
: Warning message to print before evaluating value.
value (any value)
: Value to return as-is.
Type
String -> a -> a
Located at lib/trivial.nix:749 in <nixpkgs>.
lib.trivial.warnIf
warnIf condition message value
Like warn, but only warn when the first argument is true.
Inputs
condition (Boolean)
: true to trigger the warning before continuing with value.
message (String)
: Warning message to print before evaluating
value (any value)
: Value to return as-is.
Type
Bool -> String -> a -> a
Located at lib/trivial.nix:789 in <nixpkgs>.
lib.trivial.warnIfNot
warnIfNot condition message value
Like warnIf, but negated: warn if the first argument is false.
Inputs
condition
: false to trigger the warning before continuing with val.
message
: Warning message to print before evaluating value.
value
: Value to return as-is.
Type
Boolean -> String -> a -> a
Located at lib/trivial.nix:817 in <nixpkgs>.
lib.trivial.throwIfNot
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.
Inputs
cond
: 1. Function argument
msg
: 2. Function argument
Type
bool -> string -> a -> a
Examples
lib.trivial.throwIfNot usage 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
Located at lib/trivial.nix:859 in <nixpkgs>.
lib.trivial.throwIf
Like throwIfNot, but negated (throw if the first argument is true).
Inputs
cond
: 1. Function argument
msg
: 2. Function argument
Type
bool -> string -> a -> a
Located at lib/trivial.nix:881 in <nixpkgs>.
lib.trivial.checkListOfEnum
Check if the elements in a list are valid values from a enum, returning the identity function, or throwing an error message otherwise.
Inputs
msg
: 1. Function argument
valid
: 2. Function argument
given
: 3. Function argument
Type
String -> List ComparableVal -> List ComparableVal -> a -> a
Examples
lib.trivial.checkListOfEnum usage 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
Located at lib/trivial.nix:920 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.
Inputs
f
: 1. Function argument
args
: 2. Function argument
Located at lib/trivial.nix:955 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.
Inputs
f
: 1. Function argument
Located at lib/trivial.nix:975 in <nixpkgs>.
lib.trivial.isFunction
Check whether something is a function or something annotated with function args.
Inputs
f
: 1. Function argument
Located at lib/trivial.nix:991 in <nixpkgs>.
lib.trivial.mirrorFunctionArgs
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).
Inputs
f
: Function to provide the argument metadata
g
: Function to set the argument metadata to
Type
mirrorFunctionArgs :: (a -> b) -> (a -> c) -> (a -> c)
Examples
lib.trivial.mirrorFunctionArgs usage 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; }
Located at lib/trivial.nix:1039 in <nixpkgs>.
lib.trivial.toFunction
Turns any non-callable values into constant functions. Returns callable values as is.
Inputs
v
: Any value
Examples
lib.trivial.toFunction usage example
nix-repl> lib.toFunction 1 2
1
nix-repl> lib.toFunction (x: x + 1) 2
3
Located at lib/trivial.nix:1073 in <nixpkgs>.
lib.trivial.fromHexString
Convert a hexadecimal string to it's integer representation.
Type
fromHexString :: String -> [ String ]
Examples
fromHexString "FF"
=> 255
fromHexString (builtins.hashString "sha256" "test")
=> 9223372036854775807
Located at lib/trivial.nix:1098 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"
Located at lib/trivial.nix:1115 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 ]
Inputs
base
: 1. Function argument
i
: 2. Function argument
Located at lib/trivial.nix:1151 in <nixpkgs>.