git.iko.soy/urbit.org
on master help sign in
Merge pull request #443 from urbit/rob-edits3
a34610aDavid Kerschner
learn/arvo/workbook/list.udon+9−10
compare with master
unifiedsplit
@@ -7,7 +7,7 @@
7
7
8# List of Numbers
8# List of Numbers
9
9
10−This code-example is intended to familiarize you with the basics of Hoon syntax. It's okay if you don't understand everything immediately; some concepts concepts may beyond your grasp for now. What's important is that you familiarize yourself with the elements of the code and their look once combined into a valid program.
10+This code-example is intended to familiarize you with the basics of Hoon syntax. It's okay if you don't understand everything immediately; some concepts may beyond your grasp for now. What's important is that you become accustomed to the elements of the code and their look once combined into a valid program.
11
11
12Below is a simple Hoon program that takes a single number `n` from the user as input and produces a list of numbers from `1` up to (but not including) `n`. So, if the user gives the number `5`, the program will produce: `~[1 2 3 4]`.
12Below is a simple Hoon program that takes a single number `n` from the user as input and produces a list of numbers from `1` up to (but not including) `n`. So, if the user gives the number `5`, the program will produce: `~[1 2 3 4]`.
13
13
@@ -27,7 +27,7 @@ The easiest way to use such a program is to run it as a _generator_. Saving a fi
27
27
28`~your-ship:> +list 5`
28`~your-ship:> +list 5`
29
29
30−Try it! You can choose any number, but this kind of program requires a number after the `+list` command to work. the `+` lets the Dojo know that it's looking for a generator with the name that follows.
30+Try it! You can choose any natural number to put after `+list`, but it can't be zero or blank. The `+` lets the Dojo know that it's looking for a generator with the name that follows.
31
31
32But what do all these squiggly symbols in the program _do_? It probably isn't immediately clear. Let's go through each component of this code.
32But what do all these squiggly symbols in the program _do_? It probably isn't immediately clear. Let's go through each component of this code.
33
33
@@ -43,7 +43,7 @@ In our example program, we use comments with line numbers for convenient referen
43|= end=@
43|= end=@
44```
44```
45
45
46−There's a few things going on in our first line. The first part of it, `|=` is a kind of *rune*. Runes are the building blocks of all Hoon code, represented as a pair of non-alphanumeric ASCII characters. Runes form expressions; runes are used how keywords are used in other languages. In other words, all computations in Hoon ultimately require runes. Runes, and other expressions, are all separated from one another by either two spaces or a line break.
46+There's a few things going on in our first line. The first part of it, `|=`, is a kind of *rune*. Runes are the building blocks of all Hoon code, represented as a pair of non-alphanumeric ASCII characters. Runes form expressions; runes are used how keywords are used in other languages. In other words, all computations in Hoon ultimately require runes. Runes and other Hoon expressions are all separated from one another by either two spaces or a line break.
47
47
48All runes take a fixed number of "children." Children can themselves be runes with children, and Hoon programs work by chaining through these until a value -- not another rune -- is arrived at. Keep this scheme in mind when examining Hoon code.
48All runes take a fixed number of "children." Children can themselves be runes with children, and Hoon programs work by chaining through these until a value -- not another rune -- is arrived at. Keep this scheme in mind when examining Hoon code.
49
49
@@ -53,7 +53,7 @@ Because we're only on line 1, all we're doing with the gate is creating it, and
53
53
54Our program is simple, so the _entire program_ is the gate that's being created here. The rest of our lines of code are part of the second child of our gate, and they determine how our gate produces an output.
54Our program is simple, so the _entire program_ is the gate that's being created here. The rest of our lines of code are part of the second child of our gate, and they determine how our gate produces an output.
55
55
56−## Line 2
56+### Line 2
57
57
58```
58```
59=/ count=@ 1
59=/ count=@ 1
@@ -65,7 +65,7 @@ This line begins with the `=/` rune, which stores a value with a name and specif
65
65
66We're using `count` to keep track of what numbers we're adding to the list we're building. We'll use it later in the program.
66We're using `count` to keep track of what numbers we're adding to the list we're building. We'll use it later in the program.
67
67
68−## Line 3
68+### Line 3
69
69
70```
70```
71|-
71|-
@@ -73,7 +73,7 @@ We're using `count` to keep track of what numbers we're adding to the list we're
73
73
74The `|-` rune functions as a "restart" point for recursion that will be defined later. It takes one child.
74The `|-` rune functions as a "restart" point for recursion that will be defined later. It takes one child.
75
75
76−## Line 4
76+### Line 4
77
77
78```
78```
79^- (list @)
79^- (list @)
@@ -83,7 +83,7 @@ The `^-` rune constrains output to a certain type. It takes two children.
83
83
84In this case, the rune specifies that our gate's output must be `(list @)` -- that is, a list of atoms.
84In this case, the rune specifies that our gate's output must be `(list @)` -- that is, a list of atoms.
85
85
86−## Lines 5 and 6
86+### Lines 5 and 6
87
87
88```
88```
89?: =(end count)
89?: =(end count)
@@ -108,10 +108,9 @@ In our case, `:- count` creates a cell out of whatever value is stored in `coun
108$(count (add 1 count))
108$(count (add 1 count))
109```
109```
110
110
111−
112The above code is, once again, a compact way of writing a rune expression. All you need to know is that this line of code restarts the program at `|-`, except with the value stored in `count` incremented by 1. The construction of `(count (add 1 count))` tells the computer, "replace the value of count with count+1".
111The above code is, once again, a compact way of writing a rune expression. All you need to know is that this line of code restarts the program at `|-`, except with the value stored in `count` incremented by 1. The construction of `(count (add 1 count))` tells the computer, "replace the value of count with count+1".
113
112
114−You'll notice that we use an unfamiliar word here: `add`. Unlike `count` and `end`, `add` is not defined anywhere else in the program. That's because it's a gate that's predefined in the Hoon *standard library*. The standard library is filled with pre-defined gates that are generally useful, and these gates can be used just like something that you named in your own program.
113+You'll notice that we use an unfamiliar word here: `add`. Unlike `count` and `end`, `add` is not defined anywhere in our program. That's because it's a gate that's predefined in the Hoon *standard library*. The standard library is filled with pre-defined gates that are generally useful, and these gates can be used just like something that you defined in your own program.
115
114
116## Explanation
115## Explanation
117
116
@@ -133,4 +132,4 @@ Our program works by having each iteration of the list creating a cell. In each
133 4 ~
132 4 ~
134```
133```
135
134
136−If you don't immediately intuit how this is working, don't worry. We'll take a deeper look into recursion later with our [Recursion example](../recursion).
135+If you still don't intuit how this is working, don't worry. We'll take a deeper look into recursion later with our [Recursion example](../recursion).
learn/arvo/workbook/recursion.udon+4−4
@@ -7,7 +7,7 @@
7
7
8# Recursion
8# Recursion
9
9
10−Recursion is a common pattern for solving certain problems in many programming
10+Recursion is a common pattern for solving certain problems in most programming
11languages, and Hoon is no exception. One of the classically recursive problems
11languages, and Hoon is no exception. One of the classically recursive problems
12is that of factorial. The factorial of _n_ is the product of all positive
12is that of factorial. The factorial of _n_ is the product of all positive
13integers less than or equal to N. Thus the factorial of 5, denoted as _5!_,
13integers less than or equal to N. Thus the factorial of 5, denoted as _5!_,
@@ -56,7 +56,7 @@ Let's run the program in the Dojo:
56120
56120
57```
57```
58
58
59−It may help to visualize the operation our example gate. The pseudo-Hoon below
59+It may help to visualize the operation of our example gate. The pseudo-Hoon below
60illustrates what happens when we use it to find the factorial of 5:
60illustrates what happens when we use it to find the factorial of 5:
61
61
62```
62```
@@ -74,7 +74,7 @@ illustrates what happens when we use it to find the factorial of 5:
74
74
75It's easy to see how we're "floating" gate calls until we reach the final
75It's easy to see how we're "floating" gate calls until we reach the final
76iteration of such calls that only produces a value. The `mul n` component of the
76iteration of such calls that only produces a value. The `mul n` component of the
77−gate leaves something like `mul 5`, waiting for the a final series of terms
77+gate leaves something like `mul 5`, waiting for the final series of terms
78to be operated upon. The `$(n (dec n))` component is what expands out the
78to be operated upon. The `$(n (dec n))` component is what expands out the
79expression, as illustrated by `(factorial 4)`. Once the expression cannot be
79expression, as illustrated by `(factorial 4)`. Once the expression cannot be
80expanded out further, the operations work backwards, successively feeding values
80expanded out further, the operations work backwards, successively feeding values
@@ -176,7 +176,7 @@ each iteration can be replaced instead of held in memory.
176
176
177##### A Note on `$`
177##### A Note on `$`
178
178
179−`$` is, in its use with recursion, a reference to the gate that we are inside
179+`$` (pronounced "buc") is, in its use with recursion, a reference to the gate that we are inside
180of. That's because a gate is just a core with a single arm named `$`. The
180of. That's because a gate is just a core with a single arm named `$`. The
181subject is searched depth-first, head before tail, with faces skipped, and
181subject is searched depth-first, head before tail, with faces skipped, and
182stopping on the first result. In other words, the first match found in the head
182stopping on the first result. In other words, the first match found in the head