From 1fdcf556e2ebbc9caa72fc8b6e411f4c6a8720d1 Mon Sep 17 00:00:00 2001
From: Vincent Ambo <tazjin@google.com>
Date: Wed, 25 Nov 2020 13:21:45 +0100
Subject: [PATCH] Add small section about `or` expressions

---
 README.md | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 7f6770a..0399bc4 100644
--- a/README.md
+++ b/README.md
@@ -23,7 +23,8 @@ important is missing.
     - [`if ... then ... else ...`](#if--then--else-)
     - [`inherit` keyword](#inherit-keyword)
     - [`with` statements](#with-statements)
-    - [`import` / `NIX_PATH` / `<entry>`](#import--nixpath--entry)
+    - [`import` / `NIX_PATH` / `<entry>`](#import--nix_path--entry)
+    - [`or` expressions](#or-expressions)
 - [Standard libraries](#standard-libraries)
     - [`builtins`](#builtins)
     - [`pkgs.lib`](#pkgslib)
@@ -331,6 +332,31 @@ let pkgs = import <nixpkgs> {};
 in pkgs.something
 ```
 
+## `or` expressions
+
+Nix has a keyword called `or` which can be used to access a value from an
+attribute set while providing a fallback to a default value.
+
+The syntax is simple:
+
+```nix
+# Access an existing attribute
+let set = { a = 42; };
+in set.a or 23
+```
+
+Since the attribute `a` exists, this will return `42`.
+
+
+```
+# ... or fall back to a default if there is no such key
+let set = { };
+in set.a or 23
+```
+
+Since the attribute `a` does not exist, this will fall back to returning the
+default value `23`.
+
 # Standard libraries
 
 Yes, libraries, plural.