builtins.md

Builtin functions

Before this, you'll want

  1. The Great Rebuild
The Nix language12 min

So far you have built everything by hand. Time to stop doing that.

Nix comes with a small toolbox of builtin functions, reachable through builtins with nothing to import and no nixpkgs in sight:

nix replevaluated as you typeNixA plain Nix expression. Nothing from nixpkgs or a module system is supplied.

Inspecting values

builtins.typeOf hands you the type of a value, as a string.

Try it

Make the inspector return "list".

nix replevaluated as you typeNixA plain Nix expression. Nothing from nixpkgs or a module system is supplied.

Sounds pointless until an unfamiliar expression hands you something that is not at all what you expected, which happens more than anyone admits.

Counting list items

builtins.length counts what is in a list. No surprises here.

nix replevaluated as you typeNixA plain Nix expression. Nothing from nixpkgs or a module system is supplied.
Try it

Add one tool so the result becomes "tools:3".

nix replevaluated as you typeNixA plain Nix expression. Nothing from nixpkgs or a module system is supplied.

Picking list items

builtins.head gives you the first item. builtins.tail gives you everything that isn’t the first item.

nix replevaluated as you typeNixA plain Nix expression. Nothing from nixpkgs or a module system is supplied.

head is the front of the queue and tail is everybody still waiting in it.

One catch, and it will bite you eventually: both need at least one item, so builtins.head [] and builtins.tail [] simply fail. Check items != [] first whenever a list might be empty.

Filtering a list

builtins.filter runs a function over every item and keeps the ones that answer true.

Try it

Keep only money values greater than 50.

nix replevaluated as you typeNixA plain Nix expression. Nothing from nixpkgs or a module system is supplied.

Transforming a list

builtins.map also runs a function over every item, but it keeps every result.

Try it

Double every amount of money.

nix replevaluated as you typeNixA plain Nix expression. Nothing from nixpkgs or a module system is supplied.

So filter decides which items survive, and map changes the items themselves. You’ll reach for these two constantly.

Inspecting attribute sets

Lists are only half of it. builtins.attrNames gives you the attribute names of a set, always in alphabetical order.

Try it

Add the missing place so the result contains castle, gate, and tower.

nix replevaluated as you typeNixA plain Nix expression. Nothing from nixpkgs or a module system is supplied.

builtins.attrValues gives you the values instead.

nix replevaluated as you typeNixA plain Nix expression. Nothing from nixpkgs or a module system is supplied.

The names get sorted first, so the values arrive in that same alphabetical order. Handy, as long as you never mistake it for the order you wrote them in.

Turning values into text

Interpolation only accepts strings, and sooner or later you will want to drop a number into one. builtins.toString, which you can also just write as toString, converts simple values into text.

Try it

Produce the string "balance=200".

nix replevaluated as you typeNixA plain Nix expression. Nothing from nixpkgs or a module system is supplied.

Build your own report

Time to put it together. Everything below is builtins, functions, lists and sets from the lessons you’ve already done, and there is no secret answer to guess at, so break it however you like.

nix replevaluated as you typeNixA plain Nix expression. Nothing from nixpkgs or a module system is supplied.

What to keep

  • Builtins belong to the language, not nixpkgs.
  • typeOf inspects a value’s kind.
  • length, head, tail, filter, and map work with lists.
  • attrNames and attrValues inspect attribute sets.
  • toString prepares simple values for interpolation.

Nixpkgs brings a far bigger lib toolbox along later. These builtins are the small, reliable set that is available absolutely everywhere.

Useful links

NORMALCOURSE IN BETA