@@ -4,11 +4,18 @@ weight = 6
44template = "doc.html"
55+++
66
7−In this lesson we'll review what a list is and then cover many of the list-related functions in the Hoon standard library.
87
9−## List Review
8+# Lists
109
11−A list is either null or non-null. The null list is just `~`. A non-null list is a cell in which the head is the first list item, and the tail is the rest of the list. The tail is itself a list. The head has the face `i` and the tail has the face `t`. (For the sake of neatness, these faces aren't shown by the Hoon pretty printer.)
10+A **list** is a type of noun that you'll frequently encounter when reading and writing Hoon. A list can be thought of as an ordered arrangement of zero or more elements terminated by a `~` (null).
11+
12+So a list can be either null or non-null. When the list contains only `~` and no items, it's the null list. Most lists are, however, non-null lists, which have has items preceding the `~`. Non-null lists are cells in which the head is the first list item, and the tail is the rest of the list. The tail is itself a list, and if such a list is also non-null, the head of this sub-list is the second item in the greater list, and so on. To illustrate, let's look at a list `[1 2 3 4 ~]` with the cell-delineating brackets left in:
13+
14+`[1 [2 [3 [4 ~]]]]`
15+
16+It's easy to see where the heads are and where the nesting tails are. The head of the above list is the atom `1` and the tail is the list `[2 [3 [4 ~]]]`, (or `[2 3 4]`). Recall that whenever cell brackets are omitted so that visually there appears to be more than two child nouns, it is implicitly understood that the right-most nouns constitute a cell.
17+
18+To make a list, let's cast nouns to the `(list @)` ("list of atoms") type.
1219
1320```
1421> `(list @)`~
@@ -17,11 +24,23 @@ A list is either null or non-null. The null list is just `~`. A non-null list
1724> `(list @)`[1 2 3 4 5 ~]
1825~[1 2 3 4 5]
1926
27+> `(list @)`[1 [2 [3 [4 [5 ~]]]]]
28+~[1 2 3 4 5]
29+
30+> `(list @)`~[1 2 3 4 5]
31+~[1 2 3 4 5]
32+```
33+
34+Notice how the last Dojo command has a different construction, with the `~` in front of the bracketed items. This is just another way of writing the same thing; `~[1 2]` is semantically identical to `[1 2 ~]`.
35+
36+Let's make a list whose items are of the `@t` string type:
37+
38+```
2039> `(list @t)`['Urbit' 'will' 'rescue' 'the' 'internet' ~]
2140<|Urbit will rescue the internet|>
2241```
2342
24−To use the `i` and `t` faces of a list, you must first prove that the list is non-null by using the conditional family of runes, `?`:
43+The head of a list has the face `i` and the tail has the face `t`. (For the sake of neatness, these faces aren't shown by the Hoon pretty printer.) To use the `i` and `t` faces of a list, you must first prove that the list is non-null by using the conditional family of runes, `?`:
2544
2645```
2746> =>(b=`(list @)`[1 2 3 4 5 ~] i.b)
@@ -39,6 +58,8 @@ You can construct lists of any type. `(list @)` indicates a list of atoms, `(li
3958
4059## Tapes
4160
61+While a list can be of any type, there are some special types of lists that are built into Hoon. The tape is the most common example.
62+
4263Hoon has two kinds of strings: cords and tapes. Cords are atoms with aura `@t`, and they're pretty-printed between `''` marks.
4364
4465```
@@ -69,90 +90,9 @@ You can also use the words `cord` and `tape` for casting:
6990'this is a cord'
7091```
7192
72−### Caesar Cipher
73−
74−Let's write a Caesar cipher encryption program in Hoon. A Caesar cipher substitutes each letter in a message with another letter shifted `n` places in the alphabet. For example, the Caesar cipher of `"ABC"` with a shift of `1` place is `"BCD"`.
75−
76−If you like, try to write your own version of this program before looking below.
77−
78−The following program takes an atom `a` and a tape `b`, and returns a tape that is like `b` except that each of its letters have been shifted `a` places in the alphabet:
79−
80−```
81−|= [a=@ b=tape] :: 1
82−?: (gth a 25) :: 2
83− $(a (sub a 26)) :: 3
84−|- ^- tape :: 4
85−?~ b ~ :: 5
86−:- :: 6
87− ?: &((gte i.b 'A') (lte i.b 'Z')) :: 7
88− =. i.b (add i.b a) :: 8
89− ?. (gth i.b 'Z') i.b :: 9
90− (sub i.b 26) :: 10
91− ?: &((gte i.b 'a') (lte i.b 'z')) :: 11
92− =. i.b (add i.b a) :: 12
93− ?. (gth i.b 'z') i.b :: 13
94− (sub i.b 26) :: 14
95− i.b :: 15
96−$(b t.b) :: 16
97−```
98−
99−Save this as `caesar.hoon` in `/gen` of your urbit's pier and run in the dojo:
100−
101−```
102−> +caesar [4 "test"]
103−"xiwx"
104−
105−> +caesar [4 "The quick brown fox jumps over the lazy dog."]
106−"Xli uymgo fvsar jsb nyqtw sziv xli pedc hsk."
107−```
108−
109−Let's look at this program, piece by piece:
110−
111−```
112−|= [a=@ b=tape] :: 1
113−?: (gth a 25) :: 2
114− $(a (sub a 26)) :: 3
115−```
116−
117−Line 1 has the `|=` rune for producing a gate and defines the gate's sample as a pair of `a=@` and `b=tape`. `b` is the message and `a` is the number of places to shift each letter in the alphabet. The English alphabet has 26 letters, so shifting by 26 places is the same as not shifting at all. If `a` is greater than 25, we can subtract by 26 and get the same result.
118−
119−Accordingly, if `a` is greater than `25`, line 3 restarts the function but with the value of `a` set to `(sub a 26)`.
120−
121−```
122−|- ^- tape :: 4
123−?~ b ~ :: 5
124−:- :: 6
125− ...
126−$(b t.b) :: 16
127−```
128−
129−Above is the body of the program with lines 7-15 taken out. The `|-` on line 4 indicates a recursion start point; it marks the beginning of the program's main loop. The output of the function is to be a `tape`.
130−
131−If the message, `b`, is empty, i.e., a null list `~`, then the program returns a `~`. The program is finished.
132−
133−Otherwise `b` isn't empty, in which case the `:-` rune is used to indicate that the function returns a cell. Remember, a `tape` is a list of `@tD` atoms. The head of a non-empty list is the first item of the list, in this case the first character of the `tape`. The tail is the rest of the list as another list. The tail value is produced by a recursion, where `b` is replaced with the tail of `b`, i.e., `b` without the first character.
134−
135−Lines 7-15 produce the replacement character for the head of `b`:
136−
137−```
138− ?: &((gte i.b 'A') (lte i.b 'Z')) :: 7
139− =. i.b (add i.b a) :: 8
140− ?. (gth i.b 'Z') i.b :: 9
141− (sub i.b 26) :: 10
142− ?: &((gte i.b 'a') (lte i.b 'z')) :: 11
143− =. i.b (add i.b a) :: 12
144− ?. (gth i.b 'z') i.b :: 13
145− (sub i.b 26) :: 14
146− i.b :: 15
147−```
148−
149−If the head of `b`, `i.b`, is a character between `A` and `Z` (line 7), then we add `a` to it (line 8) to shift it by the correct number of places in the alphabet. If the result is a character beyond `Z`, then we subtract `26` from `i.b` to shift back through `A` at the beginning of the alphabet (lines 9-10).
150−
151−Lines 11-14 do the same thing for the case in which `i.b` is a lowercase letter. If `i.b` is neither uppercase nor lowercase, then we leave it unchanged (line 15).
152−
15393## List Functions in the Hoon Standard Library
15494
155−Lists are a commonly used data structure. Accordingly, there are several functions in the Hoon standard library intended to make lists easier to use.
95+Lists are a commonly used data structure. Accordingly, there are several functions in the [Hoon standard library](/docs/reference/library/2b/) intended to make lists easier to use.
15696
15797For a complete list of these functions, check out the standard library reference for lists here (link). Here we'll look at a few of these functions.
15898
@@ -340,7 +280,7 @@ c
340280
341281## Using `hoon.hoon` to Learn Hoon
342282
343−The Hoon standard library and compiler are written in Hoon. At this point, you know enough Hoon to be able to explore the standard library portions of `hoon.hoon` and find more functions relevant to lists. [Look around in section `2b` (and elsewhere)](https://github.com/urbit/arvo/blob/master/sys/hoon.hoon#L459).
283+The Hoon standard library and compiler are written in Hoon. At this point, you know enough Hoon to be able to explore the standard library portions of `hoon.hoon` and find more functions relevant to lists. [Look around in section `2b` (and elsewhere)](/docs/reference/library/2b/)
344284
345285## Exercise Solutions
346286