added lang chapter

source/nix-language/attribute-sets.adoc

@@ -1,6 +1,6 @@
 = Attribute set operations
 
-== Selecttion
+== Selection
 
 The `.` operator selects an attribute from a set.
 
@@ -39,6 +39,7 @@ nix-repl> animal // { species = "tiger"; }
 { age = 10; name = { ... }; species = "tiger"; }
 ....
 
+[#rec-attrset]
 == Recursive attribute sets
 
 An ordinary attribute set cannot refer to its own elements.
@@ -57,3 +58,53 @@ error: undefined variable 'x'
 nix-repl> rec { x = 3; y = 4*x; }
 { x = 3; y = 12; }
 ....
+
+== Useful built-in functions for attribute sets
+
+Nix provides some built-in functions for working with attribute sets;
+a few examples are shown below.
+For more information on these and other built-in functions, see the Nix Manual
+(https://nixos.org/manual/nix/stable/language/builtins).
+
+Get an alphabetical list of the keys.
+
+[source]
+....
+nix-repl> builtins.attrNames animal
+[ "age" "name" "species" ]
+....
+
+Get the values associated with each key, in alphabetical order by the key names.
+
+[source]
+....
+nix-repl> builtins.attrValues animal
+[ 10 "Professor Paws" "cat" ]
+....
+
+What value is associated with a key?
+
+[source]
+....
+nix-repl> builtins.getAttr "age" animal
+10
+....
+
+Does the set have a value for a key?
+
+[source]
+....
+nix-repl> builtins.hasAttr "name" animal
+true
+
+nix-repl> builtins.hasAttr "car" animal
+false
+....
+
+Remove one or more keys and associated values from a set.
+
+[source]
+....
+nix-repl> builtins.removeAttrs animal [ "age" "species" ]
+{ name = "Professor Paws"; }
+....

source/nix-language/functions.adoc

@@ -1,3 +1,4 @@
+[#functions]
 = Functions
 
 == Anonymous functions
@@ -55,7 +56,7 @@ nix-repl> f 5
 6
 ....
 
-== Multiple parameters
+== Multiple parameters using nested functions
 
 Functions in Nix always have a single parameter.
 To define a calculation that requires more than one parameter,
@@ -121,3 +122,52 @@ nix-repl> g 5
 8
 ....
 
+== Multiple parameters using attribute sets
+
+I said earlier that a function in Nix always has a single parameter.
+However, that parameter need not be a simple value; it could be a list or an attribute set.
+To specify an attribute set as a parameter, we use a _set pattern_,
+which has the form
+
+    { _name1_, _name2_, ... }
+
+Note that while the key-value associations in attribute sets are separated by semi-colons,
+the key names in the attribute _set pattern_ are separated by commas.
+Here's an example.
+
+[source]
+....
+nix-repl> greet = { first, last }: "Hello ${first} ${last}! May I call you ${first}?"
+
+nix-repl> greet { first="Amy"; last="de Buitléir"; }
+"Hello Amy de Buitléir! May I call you Amy?"
+....
+
+== Optional parameters
+
+We can make some values in an attribute set optional by providing default values,
+using the syntax `_name_ ? _value_`.
+This is illustrated below.
+
+[source]
+....
+nix-repl> greet = { first, last ? "whatever-your-lastname-is", topic ? "Nix" }: "Hello ${first} ${last}! May I call you ${first}? Are you enjoying learning ${topic}?"
+
+nix-repl> greet { first="Amy"; }
+"Hello Amy whatever-your-lastname-is! May I call you Amy? Are you enjoying learning Nix?"
+
+nix-repl> greet { first="Amy"; topic="Mathematics";}
+"Hello Amy whatever-your-lastname-is! May I call you Amy? Are you enjoying learning Mathematics?"
+....
+
+== @-patterns
+
+TODO
+
+TODO
+
+TODO
+
+TODO
+
+TODO

source/nix-language/lists.adoc

@@ -1,5 +1,7 @@
 = List operations
 
+== List concatenation
+
 Lists can be concatenated using the `++` operator.
 
 [source]
@@ -7,3 +9,86 @@ Lists can be concatenated using the `++` operator.
 nix-repl> [ 1 2 3 ] ++ [ "apple" "banana" ]
 [ 1 2 3 "apple" "banana" ]
 ....
+
+== Useful built-in functions for lists
+
+Nix provides some built-in functions for working with lists;
+a few examples are shown below.
+For more information on these and other built-in functions, see the Nix Manual
+(https://nixos.org/manual/nix/stable/language/builtins).
+
+Testing if an element appears in a list.
+
+[source]
+....
+nix-repl> fruit = [ "apple" "banana" "canteloupe" ]
+
+nix-repl> builtins.elem "apple" fruit
+true
+
+nix-repl> builtins.elem "broccoli" fruit
+false
+....
+
+Selecting an item from a list by index.
+The first element in a list has index `0`.
+
+[source]
+....
+nix-repl> builtins.elemAt fruit 0
+"apple"
+
+nix-repl> builtins.elemAt fruit 2
+"canteloupe"
+....
+
+Determining the number of elements in a list.
+
+[source]
+....
+nix-repl> builtins.length fruit
+3
+....
+
+Accessing the first element of a list.
+
+[source]
+....
+nix-repl> builtins.head fruit
+"apple"
+....
+
+Dropping the first element of a list.
+
+[source]
+....
+nix-repl> builtins.tail fruit
+[ "banana" "canteloupe" ]
+....
+
+Functions are useful for working with lists.
+Functions will be introduced in <<functions>>,
+but the following examples should be somewhat self-explanatory.
+
+Using a function to filter (select elements from) a list.
+
+[source]
+....
+nix-repl> numbers = [ 1 3 6 8 9 15 25 ]
+
+nix-repl> isBig = n: n > 10                 # is the number "big" (greater than 10)?
+
+nix-repl> builtins.filter isBig numbers     # get just the "big" numbers
+[ 15 25 ]
+....
+
+Applying a function to all the elements in a list.
+
+[source]
+....
+nix-repl> double = n: 2*n                # multiply by two
+
+nix-repl> builtins.map double numbers    # double each element in the list
+[ 2 6 12 16 18 30 50 ]
+....
+

source/nix-language/main.adoc

@@ -24,8 +24,6 @@ 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]

source/nix-language/paths.adoc

@@ -82,3 +82,42 @@ nix-repl> "/home/wombat" + ./no-such-file.txt
 error (ignored): error: end of string reached
 error: getting status of '/home/amy/codeberg/nix-book/no-such-file.txt': No such file or directory
 ....
+
+== Useful built-in functions for paths
+
+Nix provides some built-in functions for working with paths;
+a few examples are shown below.
+For more information on these and other built-in functions, see the Nix Manual
+(https://nixos.org/manual/nix/stable/language/builtins).
+
+Does the path exist?
+
+[source]
+....
+nix-repl> builtins.pathExists ./index.html
+true
+
+nix-repl> builtins.pathExists /no/such/path
+false
+....
+
+Get a list of the files in a directory, along with the type of each file.
+
+[source]
+....
+nix-repl> builtins.readDir ./.
+{ ".envrc" = "regular"; ".git" = "directory"; ".gitignore" = "regular"; Makefile = "regular"; images = "directory"; "index.html" = "regular"; "shell.nix" = "regular"; source = "directory"; themes = "directory"; "wombats-book-of-nix.pdf" = "regular"; }
+....
+
+Read the contents of a file into a string.
+
+[source]
+....
+nix-repl> builtins.readFile ./.envrc
+"use nix\n"
+....
+
+
+[source]
+....
+....

source/nix-language/strings.adoc

@@ -42,3 +42,38 @@ error:
 ....
 Nix does provide functions for converting between types; we'll see these in <<_built_in_functions>>.
 ====
+
+== Useful built-in functions for strings
+
+Nix provides some built-in functions for working with strings;
+a few examples are shown below.
+For more information on these and other built-in functions, see the Nix Manual
+(https://nixos.org/manual/nix/stable/language/builtins).
+
+How long is this string?
+
+[source]
+....
+nix-repl> builtins.stringLength "supercalifragilisticexpialidocious"
+34
+....
+
+Given a startiing position and a length, extract a substring.
+The first character of a string has index `0`.
+
+[source]
+....
+nix-repl> builtins.substring 3 6 "hayneedlestack"
+"needle"
+....
+
+Convert an expression to a string.
+
+[source]
+....
+nix-repl> builtins.toString 7
+"7"
+
+nix-repl> builtins.toString (3*4 + 1)
+"13"
+....

source/nix-language/types.adoc

@@ -83,7 +83,7 @@ Values of attribute sets can be of any type, and can even be attribute sets them
 
     { name = { first = "Professor"; last = "Paws"; }; age = 10; species = "cat"; }
 
-In <<_recursive_attribute_sets>> you will be introduced to a special type of attribute set.
+In <<#rec-attrset>> you will be introduced to a special type of attribute set.
 
 [NOTE]
 ====