21cac44 · urbit.org · git.iko.soy

git.iko.soy/urbit.org

Merge pull request #544 from urbit/rob-update

adds content, cleans up docs

commit21cac446966356bd153a0b8cb86cb62a6e12307f authorrmariani <robert@tlon.io> dateMon 8 Jul 2019, 11:06 (7 years ago) parentacdc102 cdd1701

7 files changed+5−168

compare with master

unifiedsplit

learn/hoon/hoon-tutorial/arms-and-cores.md+1−1 learn/hoon/hoon-tutorial/gates.md+1−3 learn/hoon/hoon-tutorial/hoon-syntax.md+2 learn/hoon/hoon-tutorial/the-subject-and-its-legs.md+1−1 learn/hoon/workbook/ackermann.md−24 learn/hoon/workbook/bank.md−79 learn/hoon/workbook/fibonacci.md−60

learn/hoon/hoon-tutorial/arms-and-cores.md+1−1

@@ -1,5 +1,5 @@

11+++

2−title = "Arms and Cores"

2+title = "1.7 Arms and Cores"

33weight = 15

44template = "doc.html"

55+++

learn/hoon/hoon-tutorial/gates.md+1−3

@@ -1,5 +1,5 @@

11+++

2−title = "Gates (Hoon Functions)"

2+title = "1.5 Gates (Hoon Functions)"

33weight = 8

44template = "doc.html"

55+++

@@ -68,8 +68,6 @@ The gate works as promised -- it takes any number `n` and returns `n + 1`. Let'

6868

6969We typically use the `|=` rune to create a gate. In the expression above the `|=` is immediately followed by a set of parentheses containing two subexpressions: `a=@` and `(add 1 a)`. The first defines the gate's sample (input value type), and the second defines the gate's product (value).

7070

71−When we used the `|%` rune in the last lesson we didn't use parentheses because we were writing in "tall form" syntax, whereas here we are writing in "flat form" syntax. (The latter uses parentheses and is more suitable for shorter snippets of code.) We'll explain these concepts more thoroughly in lesson 2.2.

72−

7371In the example gate above, `inc`, the sample is defined by `a=@`. This means that the sample is defined as an atom, `@`, meaning that the gate will take as input anything of that type. The sample is given the face `a`. With the face it's easier to refer to the sample in later code, if desired.

7472

7573In `inc`, the product is defined by `(add 1 a)`. There's not much to it -- it returns the value of `a + 1`!

learn/hoon/hoon-tutorial/hoon-syntax.md+2

@@ -152,6 +152,8 @@ Runes are classified by family (with the exceptions of `--` and `==`). The firs

152152

153153Rune expressions are usually complex, which means they usually have one or more subexpressions. The appropriate syntax varies from rune to rune; after all, they're used for different purposes. To see the syntax rules for a particular rune, consult the [rune reference](@/docs/reference/hoon-expressions/rune/_index.md). Nevertheless, there are some general principles that hold of all rune expressions.

154154

155+Runes generally do not need to be closed. In other languages you'll see an abundance of terminators, such as opening and closing parentheses, and this way of doing this is largely absent from Urbit. That's because all runes take a fixed number of children. Children can themselves be runes (with more children), and Hoon programs work by chaining through these series of children until a value -- not another rune -- is arrived at. This makes Hoon code nice and neat to look at.

156+

155157#### Tall and Flat Forms

156158

157159There are two rune syntax forms: **tall** and **flat**. Tall form is usually used for multi-line expressions, and flat form is used for one-line expressions. Most runes can be used in either of tall or flat forms. Tall form expressions may contain flat form subexpressions, but flat form expressions may not contain tall form.

learn/hoon/hoon-tutorial/the-subject-and-its-legs.md+1−1

@@ -1,5 +1,5 @@

11+++

2−title = "The Subject and Its Legs"

2+title = "1.6 The Subject and Its Legs"

33weight = 13

44template = "doc.html"

55+++

learn/hoon/workbook/ackermann.mddeleted−24

@@ -1,24 +0,0 @@

1−+++

2−title = "Ackermann"

3−weight = 10

4−template = "doc.html"

5−+++

6−

7−Write a gate to compute [Ackermann's Function](https://en.wikipedia.org/wiki/Ackermann_function)

8−

9−```

10−|= [m=@ n=@]

11−?~ m +(n)

12−?~ n $(m (dec m), n 1)

13−$(m (dec m), n $(n (dec n)))

14−```

15−

16−Ackermann Function is one of the earliest examples of a function that is totally computable, meaning it can be solved, but is not primitive recursive, meaning it can not be rewritten in an iterative fashion.

17−

18−Our gate takes two argument, `m` and `n`. There are three cases.

19−

20−First, if `m` is zero, return the increment of `n`.

21−Second, if `n` is zero, decrement `m`, set `n` to 1 and recurse.

22−Else, decrement `m` and set `n` to be the value of the Ackermann function with `n` and the decrement of `n` as arguments.

23−

24−This is not a terribly useful function to compute but it has an interesting history in mathematics. When running this function the value grows rapidly even for very small input. The value of computing this where `m` is `4` and `n` is `2` is an integer with 19,729 digits.

learn/hoon/workbook/bank.mddeleted−79

@@ -1,79 +0,0 @@

1−+++

2−title = "Bank Account"

3−weight = 0

4−template = "doc.html"

5−+++

6−

7−Write a door that can act as a bank account with the ability to withdraw, deposit, and check the balance.

8−

9−```

10−:- %say

11−|= *

12−:- %noun

13−=< =~ new-account

14− (deposit 100)

15− (deposit 100)

16− (withdraw 50)

17− balance

18− ==

19−|%

20−++ new-account

21− |_ balance=@ud

22− ++ deposit

23− |= amount=@ud

24− +>.$(balance (add balance amount))

25− ++ withdraw

26− |= amount=@ud

27− +>.$(balance (sub balance amount))

28− --

29−--

30−```

31−

32−We start with the three lines we have in every `%say` generator.

33−

34−```

35−:- %say

36−|= *

37−:- %noun

38−```

39−

40−We're creating a cell the head of which is a `%say` and the tail of which is a gate that produces a cell with a head of the mark of the kind of data we are going to produce.

41−

42−```

43−=< =~ new-account

44− (deposit 100)

45− (deposit 100)

46− (withdraw 50)

47− balance

48− ==

49−```

50−

51−Here we're going to compose two runes using `=<` which has inverted arguments. We use this rune to keep the heaviest twig to the bottom of the code.

52−

53−`=~` is a rune that composes multiple expressions. We take `new-account` and use that as the subject for the call to `deposit`. `deposit` and `withdraw` both produce a new version of the door which is used in subsequent calls which is why we are able to chain them in this fashion, the final reference is to `balance` which is the balance contain in the core we are about to examine.

54−

55−```

56−|%

57−++ new-account

58− |_ balance=@ud

59− ++ deposit

60− |= amount=@ud

61− +>.$(balance (add balance amount))

62− ++ withdraw

63− |= amount=@ud

64− +>.$(balance (sub balance amount))

65− --

66−--

67−```

68−

69−We've chosen here to wrap our door in it's own core to emulate the style of programming that is used when creating libraries. `new-account` is the name of our door. Recall that a door is a core with one or more arms that has a sample. Here our door has a sample of one `@ud` with the face `balance` and two arms, `deposit` and `withdraw`.

70−

71−Each of these arms produces a gate which takes an `@ud` argument. Each of these gates has a similar bit of code inside.

72−

73−```

74−+>.$(balance (add balance amount))

75−```

76−

77−With wing syntax remember that we're looking for `+>`, or the 3rd element, out of `$`, which is to say the subject of the gate we are in, which is the entire `new-account` door. We change `balance` to be the result of adding `balance` and `amount` and produce the door as the result. `withdraw` functions the same way only doing subtraction instead of addition.

78−

79−The important point to notice here is that the sample, `balance`, is stored as part of the door rather than existing outside of it.

learn/hoon/workbook/fibonacci.mddeleted−60

@@ -1,60 +0,0 @@

1−+++

2−title = "Fibonacci"

3−weight = 9

4−template = "doc.html"

5−+++

6−

7−In this example, we will write a generator that produces a list of Fibonacci numbers up to `n`.

8−

9−```

10−|= n=@ud

11−%- flop

12−=+ [i=0 p=0 q=1 r=*(list @ud)]

13−|- ^+ r

14−?: =(i n) r

15−%= $

16− i +(i)

17− p q

18− q (add p q)

19− r [q r]

20−==

21−```

22−

23−On the first line, we use `|=` to produce a gate which takes an `@ud` that's stored in the face `n`. This `n` sample that we give our gate determines how long our Fibonacci sequence is. When the list that our program builds has `n` members, the program ends.

24−

25−```

26−%- flop

27−```

28−

29−In the line above, we use `flop` on the output of the rest of the program. `flop` is a standard library function to reverse a list.

30−

31−Why are we using this instead of just producing the list in the order we want it in the first place? Because with lists, adding an element to the end is a computationally expensive operation that gets more expensive the longer the list is, due to the fact that you need to traverse to the end of the tree. Adding an element to the front, however, is cheap. [In Big-O Notation](https://en.wikipedia.org/wiki/Big_O_notation), adding to the end of a list is O(n) and the front is O(1).

32−

33−```

34−=+ [i=0 p=0 q=1 r=*(list @ud)]

35−```

36−

37−Here we declare several values that we are going to use the execution of our program. The only one of these that is noteworthy is `r`: we're using `*` to bunt, or get the default value for, the mold `(list @ud)`.

38−

39−```

40−|- ^+ r

41−```

42−

43−With this code, we define `|-`, the _trap_ that acts as a recursion point and contains the rest of our program. We also use `^+` to cast the output by example. This will result in the output being the same type as `r`, a list of `@ud`.

44−

45−```

46−?: =(i n) r

47−```

48−

49−In the code above, `?:` checks whether the first child, `=(i n)`, our terminating case, is true or false. If it is true, it branches to `r` and the program ends. If it is false, the program continues to the code below.

50−

51−```

52−%= $

53− i +(i)

54− p q

55− q (add p q)

56− r [q r]

57−==

58−```

59−

60−The final expression in our program calls the `$` arm of the trap we are but makes some changes: we increment `i`, set `p` to be `q` and `q` becomes the sum of `p` and `q`. `r` becomes a cell of `q` and whatever `r` was previously. The list built from this is the one that will get `flop`ped to produce the result at the end of the computation.