From cb079d4d5c00ad3fbbfd131a626a57101c421bce Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Amy=20de=20Buitl=C3=A9ir?= <amy@nualeargais.ie>
Date: Fri, 1 Dec 2023 20:14:26 +0000
Subject: [PATCH] initial commit

---
 source/nix-language/attribute-sets.adoc | 19 ++++++++++
 source/nix-language/if.adoc             | 15 ++++++++
 source/nix-language/let.adoc            | 46 +++++++++++++++++++++++++
 source/nix-language/main.adoc           |  6 ++++
 source/nix-language/paths.adoc          | 16 ++++++++-
 source/nix-language/types.adoc          |  4 +++
 source/nix-language/with.adoc           | 37 ++++++++++++++++++++
 7 files changed, 142 insertions(+), 1 deletion(-)
 create mode 100644 source/nix-language/if.adoc
 create mode 100644 source/nix-language/let.adoc
 create mode 100644 source/nix-language/with.adoc

diff --git a/source/nix-language/attribute-sets.adoc b/source/nix-language/attribute-sets.adoc
index 9a93b43..1493c0a 100644
--- a/source/nix-language/attribute-sets.adoc
+++ b/source/nix-language/attribute-sets.adoc
@@ -1,5 +1,24 @@
 = Attribute set operations
 
+
+An ordinary attribute set cannot refer to its own elements.
+To do this, you need a _recursive_ attribute set.
+
+[source]
+....
+nix-repl> { x = 3; y = 4*x; }
+error: undefined variable 'x'
+
+       at «string»:1:16:
+
+            1| { x = 3; y = 4*x; }
+             |                ^
+
+nix-repl> rec { x = 3; y = 4*x; }
+{ x = 3; y = 12; }
+....
+
+
 The `.` operator selects an attribute from a set.
 
 [source]
diff --git a/source/nix-language/if.adoc b/source/nix-language/if.adoc
new file mode 100644
index 0000000..4e07f50
--- /dev/null
+++ b/source/nix-language/if.adoc
@@ -0,0 +1,15 @@
+= If expressions
+
+The conditional construct in Nix is an _expression_, not a _statement_.
+Since expressions must have values in all cases, you must specify both the `then` and the `else` branch.
+
+[source]
+....
+nix-repl> a = 7
+
+nix-repl> b = 3
+
+nix-repl> if a > b then "yes" else "no"
+"yes"
+....
+
diff --git a/source/nix-language/let.adoc b/source/nix-language/let.adoc
new file mode 100644
index 0000000..ceff96a
--- /dev/null
+++ b/source/nix-language/let.adoc
@@ -0,0 +1,46 @@
+= Let expressions
+
+A `let` expression defines a value with a local scope.
+
+[source]
+....
+nix-repl> let x = 3; in x*x
+9
+
+nix-repl> let x = 3; y = 2; in x*x + y
+11
+....
+
+You can also nest `let` expressions.
+The previous expression is equivalent to the following.
+
+[source]
+....
+nix-repl> let x = 3; in let y = 2; in x*x + y
+11
+....
+
+[IMPORTANT]
+====
+A variable defined inside a `let` expression will "shadow" an outer variable with the same name.
+
+[source]
+....
+nix-repl> x = 100
+
+nix-repl> let x = 3; in x*x
+9
+
+nix-repl> let x = 3; in let x = 7; in x+1
+8
+....
+====
+
+A variable in a let expression can refer to another variable in the expression.
+This is similar to how recursive attribute sets work.
+
+[source]
+....
+nix-repl> let x = 3; y = x + 1; in x*y
+12
+....
diff --git a/source/nix-language/main.adoc b/source/nix-language/main.adoc
index f0ae79b..d59f496 100644
--- a/source/nix-language/main.adoc
+++ b/source/nix-language/main.adoc
@@ -25,3 +25,9 @@ include::attribute-sets.adoc[leveloffset=+1]
 include::functions.adoc[leveloffset=+1]
 
 include::builtins.adoc[leveloffset=+1]
+
+include::if.adoc[leveloffset=+1]
+
+include::let.adoc[leveloffset=+1]
+
+include::with.adoc[leveloffset=+1]
diff --git a/source/nix-language/paths.adoc b/source/nix-language/paths.adoc
index 805f00d..171dabb 100644
--- a/source/nix-language/paths.adoc
+++ b/source/nix-language/paths.adoc
@@ -1,4 +1,18 @@
-= Path opearations
+= Path operations
+
+Any expression that contains a forward slash (`/`) _not_ followed by a space
+is interpreted as a path.
+To refer to a file or directory relative to the current directory, prefix it with `./`.
+You can specify the current directory as `./.`
+
+[source]
+....
+nix-repl> ./file.txt
+/home/amy/codeberg/nix-book/file.txt
+
+nix-repl> ./.
+/home/amy/codeberg/nix-book
+....
 
 Paths can be concatenated with each other to produce a new path.
 
diff --git a/source/nix-language/types.adoc b/source/nix-language/types.adoc
index 695f555..ed3e5ac 100644
--- a/source/nix-language/types.adoc
+++ b/source/nix-language/types.adoc
@@ -63,6 +63,10 @@ Note that the final semi-colon before the closing bracket is required.
 
     { name = "Professor Paws"; age = 10; species = "cat"; }
 
+The keys of an attribute set must be strings.
+When the key is not a valid identifier, it must be enclosed in quotation marks.
+
+    { abc = true; "123" = false; }
 
 Attribute sets can be empty.
 
diff --git a/source/nix-language/with.adoc b/source/nix-language/with.adoc
new file mode 100644
index 0000000..7af5c58
--- /dev/null
+++ b/source/nix-language/with.adoc
@@ -0,0 +1,37 @@
+= With expression
+
+A `with` expression is somewhat similar to a `let` expression,
+but it brings all of the associations in an attribute set into scope.
+
+[source]
+....
+nix-repl> point = { x1 = 3; x2 = 2; }
+
+nix-repl> with point; x1*x1 + x2
+11
+....
+
+
+[IMPORTANT]
+====
+Unlike a `let` expression, a variable defined inside a `with` expression will _not_
+"shadow" an outer variable with the same name.
+
+[source]
+....
+nix-repl> name = "Amy"
+
+nix-repl> animal = { name = "Professor Paws"; age = 10; species = "cat"; }
+
+nix-repl> with animal; "Hello, " + name
+"Hello, Amy"
+....
+
+However, you can refer to it using the attribute set selection operaator `.`.
+
+[source]
+....
+nix-repl> with animal; "Hello, " + animal.name
+"Hello, Professor Paws"
+....
+====