git.iko.soy/urbit.org
on master help sign in
Merge pull request #452 from urbit/page-normalization
d63aea5David Kerschner
concepts.udon+23−6
compare with master
unifiedsplit
@@ -10,9 +10,26 @@
10
10
11The documents in this section are high-level introductions to the Urbit project and components thereof.
11The documents in this section are high-level introductions to the Urbit project and components thereof.
12
12
13+## [Arvo vs. Azimuth](/docs/concepts/arvo-vs-azimuth)
14+
13−- [Arvo vs. Azimuth](/docs/concepts/arvo-vs-azimuth), a quick explanation of the two parallel systems that compose Urbit.
15+A quick explanation of the two parallel systems that compose Urbit.
16+
14−- [Technical Overview](/docs/concepts/technical-overview), a more in-depth description of the entire Urbit stack.
17+## [Technical Overview](/docs/concepts/technical-overview)
18+
19+A more in-depth description of the entire Urbit stack.
20+
21+## [Contributing](/docs/concepts/contributing)
22+
15−- [Contributing](/docs/concepts/contributing), a guide to getting involved with the Urbit project.
23+A guide to getting involved with the Urbit project.
24+
25+## [Community Tutorials](/docs/concepts/community-tutorials)
26+
16−- [Community Tutorials](/docs/concepts/community-tutorials), a collection of unofficial but useful Urbit learning resources.
27+A collection of unofficial but useful Urbit learning resources.
28+
17−- [Source Code](/docs/concepts/source-code-overview), an explanation of Urbit's constituent GitHub repos.
29+## [Source Code](/docs/concepts/source-code-overview)
30+
31+An explanation of Urbit's constituent GitHub repos.
32+
18−- [Galaxies, Stars, and Planets](/docs/concepts/galaxies-stars-and-planets), an explanation of the Urbit address-space hierarchy.
33+## [Galaxies, Stars, and Planets](/docs/concepts/galaxies-stars-and-planets)
34+
35+An explanation of the Urbit address-space hierarchy.
learn.udon+17−5
@@ -6,12 +6,24 @@
6
6
7# Learn
7# Learn
8
8
9−Tutorials and explanations of all the components of Urbit.
9+Tutorials and explanations for all the components of Urbit.
10
10
11−## [Arvo](/docs/learn/arvo)
11+## Arvo(/docs/learn/arvo)
12
12
13−In-depth documentation on Arvo internals, Hoon, Nock, and Vere, as well as a Hoon tutorial.
13+Arvo is a clean-slate system software stack defined as a deterministic computer. An encrypted P2P network, %ames, runs on a functional operating system, Arvo, written in a strict, typed functional language, Hoon, which compiles itself to a combinator interpreter, Nock, whose spec gzips to 340 bytes.
14
14
15−## [Azimuth](/docs/learn/azimuth)
15+## [Hoon](/docs/learn/hoon)
16
16
17−Azimuth documentation is in progress, but you can find descriptions of of the Urbit HD Wallet and an explanation of why Urbit needs a blockchain.
17+Hoon is a high-level, statically typed, functional programming language, custom-designed for use with Urbit. For a functional language it has a surprisingly imperative style, and mastering it doesn't require knowing any advanced mathematics.
18+
19+The [Hoon Tutorial](/docs/learn/hoon/hoon-tutorial) is the best place to start if you want to learn Urbit.
20+
21+## [Nock](/docs/learn/nock)
22+
23+Nock is the low-level functional programming language that is interpreted by Vere. You don't need to know Nock to write Hoon, or even to work on most parts of Vere. But if you want to understand the foundations of Urbit and are mathematically-inclined, dive right in.
24+
25+## [Vere](/docs/learn/vere)
26+
27+The Nock runtime system, written in C.
28+
29+Keep reading if you're planning to work on the Urbit interpreter, you're a language implementation geek, or you don't really understand anything until you've seen the actual structs.
learn/arvo-internals.udondeleted−147
@@ -1,147 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'1'
4− title/'Arvo Internals'
5− ==
6−;>
7−
8−# Arvo internals
9−
10−> Note: The last major revision of these sections was in 2016. They need to be rewritten: they're outdated in some respects, and also not always as clear as they could be. A rewrite is planned. There is still plenty of good information to be found, but don't bet the farm on anything you read here.
11−
12−Arvo is composed of modules called vanes:
13−
14−;list;
15−
16−At a high level `%arvo` takes a mess of Unix I/O events and turns them
17−into something clean and structured for the programmer.
18−
19−`%arvo` is designed to avoid the usual state of complex event networks:
20−event spaghetti. We keep track of every event's cause so that we have a
21−clear causal chain for every computation. At the bottom of every chain
22−is a Unix I/O event, such as a network request, terminal input, file
23−sync, or timer event. We push every step in the path the request takes
24−onto the chain until we get to the terminal cause of the computation.
25−Then we use this causal stack to route results back to the caller.
26−
27−## Ducts
28−
29−The `%arvo` causal stack is called a `++duct`. This is represented
30−simply as a list of paths, where each path represents a step in the
31−causal chain. The first element in the path is the first letter of
32−whichever vane handled that step in the computation, or the empty span
33−for Unix.
34−
35−Here's a duct that was recently observed in the wild:
36−
37−```
38−~[
39− /g/a/~zod/4_shell_terminal/u/time
40− /g/a/~zod/shell_terminal/u/child/4/main
41− /g/a/~zod/terminal/u/txt
42− /d/term-mess
43− //term/1
44−]
45−```
46−
47−This is the duct the timer vane receives when "timer" sample app asks
48−the timer vane to set a timer. This is also the duct over which the
49−response is produced at the specified time. Unix sent a terminal
50−keystroke event (enter), and Arvo routed it to `%dill` (our terminal),
51−which passed it on to the `%gall` app terminal, which sent it to shell,
52−its child, which created a new child (with process id 4), which on
53−startup asked the timer vane to set a timer.
54−
55−The timer vane saves this duct, so that when the specified time arrives
56−and Unix sends a wakeup event to the timer vane, it can produce the
57−response on the same duct. This response is routed to the place we
58−popped off the top of the duct, i.e. the time app. This app produces the
59−text "ding", which falls down to the shell, which drops it through to
60−the terminal. Terminal drops this down to dill, which converts it into
61−an effect that Unix will recognize as a request to print "ding" to the
62−screen. When dill produces this, the last path in the duct has an
63−initial element of the empty span, so this is routed to Unix, which
64−applies the effects.
65−
66−This is a call stack, with a crucial feature: the stack is a first-class
67−citizen. You can respond over a duct zero, one, or many times. You can
68−save ducts for later use. There are definitely parallels to Scheme-style
69−continuations, but simpler and with more structure.
70−
71−## Making Moves
72−
73−If ducts are a call stack, then how do we make calls and produce
74−results? Arvo processes "moves" which are a combination of message data
75−and metadata. There are two types of moves. A `%pass` move is analogous
76−to a call:
77−
78−```
79−[duct %pass return-path=path vane-name=@tD data=card]
80−```
81−
82−Arvo pushes the return path (preceded by the first letter of the vane
83−name) onto the duct and sends the given data, a card, to the vane we
84−specified. Any response will come along the same duct with the path
85−`return-path`.
86−
87−A `%give` move is analogous to a return:
88−
89−```
90−[duct %give data=card]
91−```
92−
93−Arvo pops the top path off the duct and sends the given card back to the
94−caller.
95−
96−## Vanes
97−
98−As shown above, we use Arvo proper to route and control the flow of
99−moves. However, Arvo proper is rarely directly responsible for
100−processing the event data that directly causes the desired outcome of a
101−move. This event data is contained within a card, which is simply a
102−`(pair term noun)`. Instead, Arvo proper passes the card off to one of
103−its vanes, which each present an interface to clients for a particular
104−well-defined, stable, and general-purpose piece of functionality.
105−
106−As of this writing, we have seven vanes, which each provide the
107−following services:
108−
109−- `%ames`: the name of both our network and the vane that communicates over it.
110−- `%behn`: a simple timer.
111−- `%clay`: our version-controlled, referentially- transparent, and global filesystem.
112−- `%dill`: a terminal driver. Unix sends keyboard events to `%dill` from either the console or telnet, and `%dill` produces terminal output.
113−- `%eyre`: an http server. Unix sends http messages to `%eyre`, and `%eyre` produces http messages in response.
114−- `%ford`: handles resources and publishing.
115−- `%gall`: manages our userspace applications. `%gall` keeps state and manages subscribers.
116−
117−## Cards
118−
119−Cards are the vane-specific portion of a move. Each vane defines a
120−protocol for interacting with other vanes (via Arvo) by defining four
121−types of cards: kisses, gifts, notes, and signs.
122−
123−When one vane is `%pass`ed a card in its `++kiss`, Arvo activates the
124−`++call` gate with the card as its argument. To produce a result, the
125−vane `%give`s one of the cards defined in its `++gift`. If the vane
126−needs to request something of another vane, it `%pass`es it a `++note`
127−card. When that other vane returns a result, Arvo activates the `++take`
128−gate of the initial vane with one of the cards defined in its `++sign`.
129−
130−In other words, there are only four ways of seeing a move: (1) as a
131−request seen by the caller, which is a ++note. (2) that same request as
132−seen by the callee, a `++kiss`. (3) the response to that first request
133−as seen by the callee, a `++gift`. (4) the response to the first request
134−as seen by the caller, a `++sign`.
135−
136−When a `++kiss` card is passed to a vane, Arvo calls its `++call` gate,
137−passing it both the card and its duct. This gate must be defined in
138−every vane. It produces two things in the following order: a list of
139−moves and a possibly modified copy of its context. The moves are used to
140−interact with other vanes, while the new context allows the vane to save
141−its state. The next time Arvo activates the vane it will have this
142−context as its subject.
143−
144−This overview has detailed how to pass a card to a particular vane. To
145−see the cards each vane can be `%pass`ed as a `++kiss` or return as a
146−`++gift` (as well as the semantics tied to them), each vane's public
147−interface is explained in detail in its respective overview.
learn/arvo.udon+98−9
@@ -5,20 +5,109 @@
5
5
6# Arvo
6# Arvo
7
7
8−Arvo is a clean-slate system software stack defined as a deterministic computer. An encrypted P2P network, %ames, runs on a functional operating system, Arvo, written in a strict, typed functional language, Hoon, which compiles itself to a combinator interpreter, Nock, whose spec gzips to 340 bytes.
8+Arvo is Urbit's functional operating system, written in [Hoon](/docs/learn/hoon). It's composed of modules called _vanes_:
9
9
10−## [Hoon](/docs/learn/arvo/hoon)
10+## [Ames](ames)
11
11
12−Hoon is a high-level, statically typed, functional programming language, custom-designed for use with Urbit. For a functional language it has a surprisingly imperative style, and mastering it doesn't require knowing any advanced mathematics.
12+Ames is the name of our network and the vane that communicates over it. It's an encrypted P2P network composed of instances of the Arvo operating system.
13
13
14−The [Hoon Tutorials](/docs/learn/arvo/hoon/getting-started) are the best place to start if you want to learn Urbit.
14+## [Behn](behn)
15
15
16−## [Nock](/docs/learn/arvo/nock)
16+Behn is our timer. It allows vanes and applications to set and timer events, which are managed in a simple priority queue.
17
17
18−Nock is the low-level functional programming language that is interpreted by Vere. You don't need to know Nock to write Hoon, or even to work on most parts of Vere. But if you want to understand the foundations of Urbit and are mathematically-inclined, dive right in.
18+## [Clay](clay)
19
19
20−## [Vere](/docs/learn/arvo/vere)
20+Clay is our filesystem and revision-control system.
21
21
22−The Nock runtime system, written in C.
22+## [Dill](dill)
23
23
24−Keep reading if you're planning to work on the Urbit interpreter, you're a language implementation geek, or you don't really understand anything until you've seen the actual structs.
24+Dill is our terminal driver. Unix sends keyboard events to dill from the terminal, and dill produces terminal output.
25+
26+## [Eyre](eyre)
27+
28+Eyre is our HTTP server. Unix sends HTTP messages to `%eyre`, and `%eyre` produces HTTP messages in response.
29+
30+## [Ford](ford)
31+
32+Ford is our build system. It handles resources and publishing.
33+
34+## [Gall](gall)
35+
36+Gall is the vane for controlling userspace apps.
37+
38+### [Hall](hall)
39+
40+Hall isn't a vane, but an important Gall app that functions as the Urbit messaging protocol.
41+
42+## Principles
43+
44+At a high level `%arvo` takes a mess of Unix I/O events and turns them into something clean and structured for the programmer.
45+
46+`%arvo` is designed to avoid the usual state of complex event networks: event spaghetti. We keep track of every event's cause so that we have a clear causal chain for every computation. At the bottom of every chain is a Unix I/O event, such as a network request, terminal input, file sync, or timer event. We push every step in the path the request takes onto the chain until we get to the terminal cause of the computation. Then we use this causal stack to route results back to the caller.
47+
48+### Ducts
49+
50+The `%arvo` causal stack is called a `++duct`. This is represented simply as a list of paths, where each path represents a step in the causal chain. The first element in the path is the first letter of whichever vane handled that step in the computation, or the empty span for Unix.
51+
52+Here's a duct that was recently observed in the wild:
53+
54+```
55+~[
56+ /g/a/~zod/4_shell_terminal/u/time
57+ /g/a/~zod/shell_terminal/u/child/4/main
58+ /g/a/~zod/terminal/u/txt
59+ /d/term-mess
60+ //term/1
61+]
62+```
63+
64+This is the duct the timer vane receives when "timer" sample app asks the timer vane to set a timer. This is also the duct over which the response is produced at the specified time. Unix sent a terminal keystroke event (enter), and Arvo routed it to `%dill` (our terminal), which passed it on to the `%gall` app terminal, which sent it to shell, its child, which created a new child (with process id 4), which on startup asked the timer vane to set a timer.
65+
66+The timer vane saves this duct, so that when the specified time arrives and Unix sends a wakeup event to the timer vane, it can produce the response on the same duct. This response is routed to the place we popped off the top of the duct, i.e. the time app. This app produces the text "ding", which falls down to the shell, which drops it through to the terminal. Terminal drops this down to dill, which converts it into an effect that Unix will recognize as a request to print "ding" to the screen. When dill produces this, the last path in the duct has an
67+initial element of the empty span, so this is routed to Unix, which applies the effects.
68+
69+This is a call stack, with a crucial feature: the stack is a first-class citizen. You can respond over a duct zero, one, or many times. You can save ducts for later use. There are definitely parallels to Scheme-style continuations, but simpler and with more structure.
70+
71+### Making Moves
72+
73+If ducts are a call stack, then how do we make calls and produce results? Arvo processes "moves" which are a combination of message data and metadata. There are two types of moves. A `%pass` move is analogous to a call:
74+
75+```
76+[duct %pass return-path=path vane-name=@tD data=card]
77+```
78+
79+Arvo pushes the return path (preceded by the first letter of the vane name) onto the duct and sends the given data, a card, to the vane we specified. Any response will come along the same duct with the path `return-path`.
80+
81+A `%give` move is analogous to a return:
82+
83+```
84+[duct %give data=card]
85+```
86+
87+Arvo pops the top path off the duct and sends the given card back to the caller.
88+
89+### Vanes
90+
91+As shown above, we use Arvo proper to route and control the flow of moves. However, Arvo proper is rarely directly responsible for processing the event data that directly causes the desired outcome of a move. This event data is contained within a card, which is simply a `(pair term noun)`. Instead, Arvo proper passes the card off to one of its vanes, which each present an interface to clients for a particular well-defined, stable, and general-purpose piece of functionality.
92+
93+As of this writing, we have seven vanes, which each provide the following services:
94+
95+- `%ames`: the name of both our network and the vane that communicates over it.
96+- `%behn`: a simple timer.
97+- `%clay`: our version-controlled, referentially- transparent, and global filesystem.
98+- `%dill`: a terminal driver. Unix sends keyboard events to `%dill` from either the console or telnet, and `%dill` produces terminal output.
99+- `%eyre`: an http server. Unix sends http messages to `%eyre`, and `%eyre` produces http messages in response.
100+- `%ford`: handles resources and publishing.
101+- `%gall`: manages our userspace applications. `%gall` keeps state and manages subscribers.
102+
103+### Cards
104+
105+Cards are the vane-specific portion of a move. Each vane defines a protocol for interacting with other vanes (via Arvo) by defining four types of cards: kisses, gifts, notes, and signs.
106+
107+When one vane is `%pass`ed a card in its `++kiss`, Arvo activates the `++call` gate with the card as its argument. To produce a result, the vane `%give`s one of the cards defined in its `++gift`. If the vane needs to request something of another vane, it `%pass`es it a `++note` card. When that other vane returns a result, Arvo activates the `++take` gate of the initial vane with one of the cards defined in its `++sign`.
108+
109+In other words, there are only four ways of seeing a move: (1) as a request seen by the caller, which is a ++note. (2) that same request as seen by the callee, a `++kiss`. (3) the response to that first request as seen by the callee, a `++gift`. (4) the response to the first request as seen by the caller, a `++sign`.
110+
111+When a `++kiss` card is passed to a vane, Arvo calls its `++call` gate, passing it both the card and its duct. This gate must be defined in every vane. It produces two things in the following order: a list of moves and a possibly modified copy of its context. The moves are used to interact with other vanes, while the new context allows the vane to save its state. The next time Arvo activates the vane it will have this context as its subject.
112+
113+This overview has detailed how to pass a card to a particular vane. To see the cards each vane can be `%pass`ed as a `++kiss` or return as a `++gift` (as well as the semantics tied to them), each vane's public interface is explained in detail in its respective overview.
learn/arvo/clay.udon+1−1
@@ -63,7 +63,7 @@ access to devices, to random number generators, to the /proc
63tree. It is easy and intuitive to read from and write to a
63tree. It is easy and intuitive to read from and write to a
64filesystem tree.
64filesystem tree.
65
65
66−Second, clay has a distributed revision control system baked into
66+Second, clay has a distributed revision-control system baked into
67it. Traditional filesystems are not revision controlled, so
67it. Traditional filesystems are not revision controlled, so
68userspace software -- such as git -- is written on top of them to
68userspace software -- such as git -- is written on top of them to
69do so. clay natively provides the same functionality as modern
69do so. clay natively provides the same functionality as modern
learn/arvo/eyre.udon+1−1
@@ -8,7 +8,7 @@
8
8
9# Eyre
9# Eyre
10
10
11−Our http server.
11+Our HTTP server.
12
12
13Unix sends http messages to `%eyre`, and `%eyre` produces http messages
13Unix sends http messages to `%eyre`, and `%eyre` produces http messages
14in response. In general, apps and vanes do not call `%eyre`; rather,
14in response. In general, apps and vanes do not call `%eyre`; rather,
learn/hoon.udon+11−3
@@ -13,6 +13,14 @@ Hoon is an unusual language in several respects, both in syntax and semantics.
13
13
14In this section, you'll find useful resources on the Hoon programming language.
14In this section, you'll find useful resources on the Hoon programming language.
15
15
16+## [The Hoon Tutorial](hoon-tutorial)
17+
16−- [The Hoon Tutorial](hoon-tutorial) is the place to learn the fundamentals of the language, from the very beginning.
18+This section is the place to learn the fundamentals of the language, from the very beginning.
19+
20+## [The Hoon Workbook](workbook)
21+
17−- [The Hoon Workbook](workbook) lets you dive right into code walkthroughs.
22+The workbook lets you dive right into code walkthroughs.
23+
24+## [The Style Guide](style)
25+
18−- [The Style Guide](style) shows you how to write code in the correct way.
26+This guide shows you how to write code in the correct way.
learn/hoon/workbook/caesar.udon+21−33
@@ -33,7 +33,7 @@ demonstrates important principles that more laconic code would not. Save it as
33
33
34```
34```
35!:
35!:
36−:- %say
36+|= [msg=tape key=@ud]
37=+ ^= caesar
37=+ ^= caesar
38 |%
38 |%
39 ++ alpha "abcdefghijklmnopqrstuvwxyz"
39 ++ alpha "abcdefghijklmnopqrstuvwxyz"
@@ -76,8 +76,6 @@ demonstrates important principles that more laconic code would not. Save it as
76 =+ s=(trim (mod n length) m)
76 =+ s=(trim (mod n length) m)
77 (weld q.s p.s)
77 (weld q.s p.s)
78 --
78 --
79−|= [* [msg=tape key=@ud ~] ~]
80−:- %noun
81=. msg (cass msg)
79=. msg (cass msg)
82:- (shift.caesar msg key)
80:- (shift.caesar msg key)
83(unshift.caesar msg key)
81(unshift.caesar msg key)
@@ -91,24 +89,23 @@ that has been shifted left. It also converts any uppercase input into lowercase.
91Try it out in the Dojo:
89Try it out in the Dojo:
92
90
93```
91```
94−> +caesar "test" 2
92+> +caesar ["test" 2]
95["vguv" "rcqr"]
93["vguv" "rcqr"]
96
94
97−> +caesar "test" 26
95+> +caesar ["test" 26]
98["test" "test"]
96["test" "test"]
99
97
100−> +caesar "test" 28
98+> +caesar ["test" 28]
101["vguv" "rcqr"]
99["vguv" "rcqr"]
102
100
103−> +caesar "test" 104
101+> +caesar ["test" 104]
104["test" "test"]
102["test" "test"]
105
103
106−> +caesar "tESt" 2
104+> +caesar ["tESt" 2]
107["vguv" "rcqr"]
105["vguv" "rcqr"]
108
106
109−> +caesar "test!" 2
107+> +caesar ["test!" 2]
110nest-fail
108nest-fail
111−
112```
109```
113
110
114### Examining Our Code
111### Examining Our Code
@@ -120,7 +117,7 @@ itself before reading the explanation.
120
117
121```
118```
122!:
119!:
123−:- %say
120+|= [msg=tape key=@ud]
124=+ ^= caesar
121=+ ^= caesar
125 |%
122 |%
126```
123```
@@ -128,34 +125,23 @@ itself before reading the explanation.
128The `!:` in the first line of the above code enables a full stack trace in the
125The `!:` in the first line of the above code enables a full stack trace in the
129event of an error.
126event of an error.
130
127
131−`:- %say` begins to construct a cell with `%say` as the head, and the code that
128+`|= [msg=tape key=@ud]` creates a gate that takes a cell. The head of this cell
132−follows as the tail. This causes the Arvo to interpret the file as a
129+is a `tape`, which is a string type that's a list of `cord`s. Tapes are represented
133−[`%say` generator](/docs/tutorials/generators).
130+as text surrounded by double-quotes, such as this: `"a tape"`. We give this input tape the face `msg`.
131+The tail of our cell is a `@ud` -- an unsigned decimal atom -- that we give the face `key`.
134
132
135−`=+` adds a noun the subject, `=^ caesar` names that noun, and `|%` is used
133+`=+` adds a noun to the subject, `=^ caesar` names that noun, and `|%` is used
136to create a core that contains the following arms. This results in having a core
134to create a core that contains the following arms. This results in having a core
137with the face `caesar` that we can call.
135with the face `caesar` that we can call.
138
136
139Now let's look at the rest of the program that is outside of our core:
137Now let's look at the rest of the program that is outside of our core:
140
138
141```
139```
142−|= [* [msg=tape key=@ud ~] ~]
143−:- %noun
144=. msg (cass msg)
140=. msg (cass msg)
145:- (shift.caesar msg key)
141:- (shift.caesar msg key)
146(unshift.caesar msg key)
142(unshift.caesar msg key)
147```
143```
148
144
149−The top line creates a gate with `|=`. The sample of that gate follows the
150−scheme used by `%say` generators: it's a 3-tuple whose parts allow for different
151−kinds of data. We only need non-optional arguments, though, so we only fill in
152−the second part. There we take a `msg` argument and a `key` argument. We use a
153−`*` and a `~` in the first part (Arvo data) and third part (optional arguments),
154−respectively, because we aren't using them here. See the
155−[generator documentation](/docs/tutorials/generators) for more information.
156−
157−`:- %noun` simply labels the output of this program as the `%noun` mark.
158−
159`=. msg (cass msg)` changes the input string `msg` to lowercases. `=.` changes
145`=. msg (cass msg)` changes the input string `msg` to lowercases. `=.` changes
160the leg of the subject to something else. In our case, the leg to be changed is
146the leg of the subject to something else. In our case, the leg to be changed is
161`msg`, and the thing to replace it is `(cass msg)`. `cass` is a standard-library
147`msg`, and the thing to replace it is `(cass msg)`. `cass` is a standard-library
@@ -235,10 +221,10 @@ the program is finished and can return `chart`, the the `map` that we have been
235creating.
221creating.
236
222
237If the above test finds that its condition to be false, we trigger a recursion
223If the above test finds that its condition to be false, we trigger a recursion
238−that constructs our `map`: $(chart (~(put by chart) i.a i.b), a t.a, b t.b)`.
224+that constructs our `map`: `$(chart (~(put by chart) i.a i.b), a t.a, b t.b)`.
239This code recursively adds an entry in our `map` where the head of the tape `a`
225This code recursively adds an entry in our `map` where the head of the tape `a`
240maps to the value of the head of tape `b` with `~(put by chart)`, our calling
226maps to the value of the head of tape `b` with `~(put by chart)`, our calling
241−of the `put` arm of the `by` map-engien core. The recursion also "consumes"
227+of the `put` arm of the `by` map-engine core. The recursion also "consumes"
242those heads with every iteration by changing `a` and `b` to their tails.
228those heads with every iteration by changing `a` and `b` to their tails.
243
229
244Perhaps now you can understand why this arm is named `zipper`. It's putting two
230Perhaps now you can understand why this arm is named `zipper`. It's putting two
@@ -333,7 +319,7 @@ If we then give our arm Caesar's famous statement, and get our left- and
333right-ciphers.
319right-ciphers.
334
320
335```
321```
336−> +caesar "i came i saw i conquered" 4
322+> +caesar ["i came i saw i conquered" 4]
337["m geqi m wea m gsruyivih" "e ywia e ows e ykjmqanaz"]
323["m geqi m wea m gsruyivih" "e ywia e ows e ykjmqanaz"]
338```
324```
339
325
@@ -341,10 +327,10 @@ Now, to decode, we can put either of our ciphers in with the appropriate key and
341look for the legible result.
327look for the legible result.
342
328
343```
329```
344−> +caesar "m geqi m wea m gsruyivih" 4
330+> +caesar ["m geqi m wea m gsruyivih" 4]
345["q kium q aie q kwvycmzml" "i came i saw i conquered"]
331["q kium q aie q kwvycmzml" "i came i saw i conquered"]
346
332
347−> +caesar "e ywia e ows e ykjmqanaz" 4
333+> +caesar ["e ywia e ows e ykjmqanaz" 4]
348["i came i saw i conquered" "a usew a kso a ugfimwjwv"]
334["i came i saw i conquered" "a usew a kso a ugfimwjwv"]
349```
335```
350
336
@@ -353,7 +339,9 @@ look for the legible result.
353
339
3541. Take the example generator and modify it to add a second layer of shifts.
3401. Take the example generator and modify it to add a second layer of shifts.
355
341
356−2. Extend the example generator to allow for using characters other than a-z.
342+2. Extend the example generator to allow for use of characters other than a-z.
357
343
3583. Build a gate that can take a Caesar shifted `tape` and produce
3443. Build a gate that can take a Caesar shifted `tape` and produce
359possible unshifted `tapes`.
345possible unshifted `tapes`.
346+
347+4. Modify the example generator into a `%say` generator.
learn/nock.udon+4−4
@@ -11,18 +11,18 @@
11
11
12Nock is the low-level functional programming language that is interpreted by Vere. You don't need to know Nock to write Hoon, or even to work on most parts of Vere. But if you want to understand the foundations of Urbit and are mathematically-inclined, dive right in.
12Nock is the low-level functional programming language that is interpreted by Vere. You don't need to know Nock to write Hoon, or even to work on most parts of Vere. But if you want to understand the foundations of Urbit and are mathematically-inclined, dive right in.
13
13
14−### [Nock Definition](definition)
14+## [Nock Definition](definition)
15
15
16The Nock specification.
16The Nock specification.
17
17
18−### [An explanation of Nock](explanation)
18+## [An explanation of Nock](explanation)
19
19
20A comprehensive walkthrough of the Nock spec.
20A comprehensive walkthrough of the Nock spec.
21
21
22−### [Nock by hand](example)
22+## [Nock by hand](example)
23
23
24Learn Nock by example.
24Learn Nock by example.
25
25
26−### [Nock Implementations](implementations)
26+## [Nock Implementations](implementations)
27
27
28The many ways that Nock has been implemented.
28The many ways that Nock has been implemented.
learn/vere.udon+5−5
@@ -13,26 +13,26 @@ Keep reading if you're planning to work on the Urbit interpreter, you're a
13language implementation geek, or you don't really understand anything until
13language implementation geek, or you don't really understand anything until
14you've seen the actual structs.
14you've seen the actual structs.
15
15
16−### [C runtime system](runtime)
16+## [C runtime system](runtime)
17
17
18The Urbit interpreter is built on a Nock runtime system written
18The Urbit interpreter is built on a Nock runtime system written
19in C, `u3`. This section is a relatively complete description.
19in C, `u3`. This section is a relatively complete description.
20
20
21−### [c3: C in Urbit](c)
21+## [c3: C in Urbit](c)
22
22
23Under `u3` is the simple `c3` layer, which is just how we write C
23Under `u3` is the simple `c3` layer, which is just how we write C
24in Urbit.
24in Urbit.
25
25
26−### [u3: Land of nouns](nouns)
26+## [u3: Land of nouns](nouns)
27
27
28The division between `c3` and `u3` is that you could theoretically
28The division between `c3` and `u3` is that you could theoretically
29imagine using `c3` as just a generic C environment. Anything to do
29imagine using `c3` as just a generic C environment. Anything to do
30with nouns is in `u3`.
30with nouns is in `u3`.
31
31
32−### [u3: API overview by prefix](api)
32+## [u3: API overview by prefix](api)
33
33
34A walkthrough of each of the `u3` modules.
34A walkthrough of each of the `u3` modules.
35
35
36−### [How to write a jet](jetting)
36+## [How to write a jet](jetting)
37
37
38A jetting guide by for new Urbit developers.
38A jetting guide by for new Urbit developers.