on master help sign in
Various fixes and improvements.
d6be9a1C. Guy Yarvin
docs/byte/0.md+4−2
@@ -40,8 +40,10 @@ In the Urbyte exercises you'll be running what we call a "fake
40`~zod`." A string starting with `~`, like `~zod`, is what Urbit
40`~zod`." A string starting with `~`, like `~zod`, is what Urbit
41calls a *ship*.
41calls a *ship*.
42
42
43−A ship is one number which means four things: a network address, a
43+A *ship* is one number which means four things: a network address,
44−cryptographic identity, a memorable name, and a single virtual computer.
44+a cryptographic identity, a memorable name, and a single virtual
45+computer.
46+
45We write this number in a base-256 format, where each digit is a
47We write this number in a base-256 format, where each digit is a
46syllable. Imagine if your phone number was a pronounceable
48syllable. Imagine if your phone number was a pronounceable
47string which sounded like a name in a foreign language.
49string which sounded like a name in a foreign language.
docs/byte/1.md+45−26
@@ -22,22 +22,28 @@ http: live (insecure, loopback) on 12321
22~zod:dojo>
22~zod:dojo>
23```
23```
24
24
25−## The atom question
25+## What's in an atom?
26
26
27It seems limiting to have only one kind of atom, the unsigned
27It seems limiting to have only one kind of atom, the unsigned
28decimal. How are signed integers represented? Symbols?
28decimal. How are signed integers represented? Symbols?
29Floating-point values? Dates? IP addresses? Even just hex?
29Floating-point values? Dates? IP addresses? Even just hex?
30
30
31−The Lisp S-expression, with cons cells and atoms, is very similar
31+Lisp's S-expression, with its own cells and atoms, is very
32−to Hoon's nouns. But languages in the Lisp family mark each atom
32+similar to Hoon's nouns. But languages in the Lisp family mark
33−with a dynamic tag that defines the atom's meaning. These tags
33+each atom with a dynamic tag that defines the atom's meaning.
34−are effectively dynamic types.
34+These tags are effectively dynamic types.
35
35
36Hoon also tracks the meaning of atoms. But Hoon is statically
36Hoon also tracks the meaning of atoms. But Hoon is statically
37typed, so an atom description is obviously a type. An atomic type
37typed, so an atom description is obviously a type. An atomic type
38in Hoon is called an *aura*. The aura syntax is just an ASCII
38in Hoon is called an *aura*. The aura syntax is just an ASCII
39string starting with `@`, like `@ud` for unsigned decimal.
39string starting with `@`, like `@ud` for unsigned decimal.
40
40
41+Hoon has a wide (but not extensible) variety of atom syntaxes.
42+Each syntax for an atom produces an appropriate predefined aura.
43+And Hoon's printer can invertibly print any aura Hoon can parse.
44+Because atoms make great path nodes and paths make great URLs,
45+all regular atom syntaxes use only URL-safe characters.
46+
41## Examples
47## Examples
42
48
43With the dojo command `? expression`, you tell the dojo to print
49With the dojo command `? expression`, you tell the dojo to print
@@ -105,7 +111,7 @@ can't enforce any constraints the aura puts on the atom's value.
105```
111```
106
112
107`--7` means "positive 7." `+7` might have been better, but `+`
113`--7` means "positive 7." `+7` might have been better, but `+`
108−is not URL-safe, and every regular atom syntax fits in a URL.
114+is not URL-safe.
109
115
110Hoon needs `--` to distinguish positive signed numbers because
116Hoon needs `--` to distinguish positive signed numbers because
111Hoon's type system doesn't feed back into its parser. The
117Hoon's type system doesn't feed back into its parser. The
@@ -130,6 +136,14 @@ slightly clunkier syntax in exchange for much simpler semantics.
130 @ux
136 @ux
1310x7469.6272.9cc3
1370x7469.6272.9cc3
132
138
139+> ? ~~Ürbit
140+ @t
141+'Ürbit'
142+
143+? >~.urbit
144+ @ta
145+~.urbit
146+
133> ? `@ux`'foo'
147> ? `@ux`'foo'
134 @ux
148 @ux
1350x6f.6f66
1490x6f.6f66
@@ -140,6 +154,11 @@ Hoon doesn't actually have the power to check statically that
140your UTF-8 is valid. Auras don't tell you what an atom is, just
154your UTF-8 is valid. Auras don't tell you what an atom is, just
141what you think it is.
155what you think it is.
142
156
157+The familiar single-quote syntax for `@t` is an irregular form of
158+the more unusual `~~` prefix. The `~.` prefix, aura `@ta`, is
159+restricted to lowercase ASCII (a great common denominator). Of
160+course, `~` is URL-safe and `'` is not.
161+
143### Dates, floats, IP addresses...
162### Dates, floats, IP addresses...
144
163
145```
164```
@@ -174,35 +193,35 @@ what you think it is.
174`@da` is a 128-bit absolute date (64 bits for fractions of a
193`@da` is a 128-bit absolute date (64 bits for fractions of a
175second, 64 bits for seconds); `@dr` is a relative date; `@rs` is
194second, 64 bits for seconds); `@dr` is a relative date; `@rs` is
176a single-precision IEEE real; `@if` is an IPv4 address. This is
195a single-precision IEEE real; `@if` is an IPv4 address. This is
177−not all Hoon's aura syntax, but it's a good range of examples.
196+not all Hoon's aura syntax, just a good range of examples.
178
197
179`(add ~h6 now)` is a good example of the use and limits of
198`(add ~h6 now)` is a good example of the use and limits of
180the aura system. Unlike the signed-integer sum, offsetting a
199the aura system. Unlike the signed-integer sum, offsetting a
181date can use plain atomic addition. But the product of `add` is
200date can use plain atomic addition. But the product of `add` is
182−a flavorless atom with no aura, so we have to cast it back to an
201+a flavorless atom with no aura, `@`. So we have to cast it back
183−absolute date `@da`.
202+to an absolute date `@da`.
184
203
185## Auras explained
204## Auras explained
186
205
187Does an aura represent the units of the atom, its syntax, its
206Does an aura represent the units of the atom, its syntax, its
188semantics, its constraints?
207semantics, its constraints?
189
208
190−It can mean any or all of these. Programmers can even use their
209+Any or all of the above. Programmers can even use their own aura
191−own aura strings which nothing in Hoon recognizes. The set of
210+strings, which nothing in Hoon recognizes. The set of syntaxes
192−syntaxes that Hoon knows how to parse and print is fixed. But
211+that Hoon knows how to parse and/or print is fixed. But there
193−there are plenty of reasons to introduce user-defined auras.
212+are plenty of good reasons to use your own user-defined auras.
194
213
195−If your program uses both fortnights and furlongs, the aura
214+If your program uses both fortnights and furlongs, Hoon will not
196−system will not parse a fortnight syntax or print furlongs in the
215+parse a user-defined fortnight syntax. It will not print furlongs
197−dojo. It will keep you from accidentally confusing the two,
216+in the dojo. But the type system will keep you from accidentally
198−which is probably most of what you want.
217+passing a furlong to a function that expects a fortnight.
199
218
200−Hoon does interpret the string in one way: auras specialize to
219+Hoon does interpret the aura string in one way: auras specialize
201−the right. For example, `@u` is any unsigned integer; `@ux` is
220+to the right. For example, `@u` is any unsigned integer; `@ux`
202−an unsigned integer that likes to be printed as hex.
221+is an unsigned integer that likes to be printed as hex.
203
222
204Hoon's typechecker lets you go up or down the specialization
223Hoon's typechecker lets you go up or down the specialization
205−ladder, but complains if you try to go across. For example,
224+ladder. It complains if you try to move across. For example,
206`@u` can silently convert into `@ux` or `@ux` into `@u`, but
225`@u` can silently convert into `@ux` or `@ux` into `@u`, but
207turning `@ud` into `@ux`, `@ux` into `@da`, etc, requires an
226turning `@ud` into `@ux`, `@ux` into `@da`, etc, requires an
208explicit cast.
227explicit cast.
@@ -288,7 +307,7 @@ infix hyphens ("kebab-case").
288Loobeans are not true and false, but yes (`.y` or `&`) and no
307Loobeans are not true and false, but yes (`.y` or `&`) and no
289(`.n` or `|`). This is because *yes is zero and no is one*.
308(`.n` or `|`). This is because *yes is zero and no is one*.
290This makes sense at a certain mathematical level, though it
309This makes sense at a certain mathematical level, though it
291−was probably a mistake.
310+was probably a mistake from a practical perspective.
292
311
293`~` is Hoon's nil: constant `0`, aura `@n`.
312`~` is Hoon's nil: constant `0`, aura `@n`.
294
313
@@ -326,15 +345,15 @@ $
326
345
327As always, these questions are optional and only for fun.
346As always, these questions are optional and only for fun.
328
347
329−We didn't include anywhere near all auras or syntaxes in this
348+We didn't include anywhere near all Hoon's auras or syntaxes in
330−lesson. It's just a set of examples.
349+this lesson. It's just a set of examples.
331
350
332Try using the dojo's magic error erasure to stumble around the
351Try using the dojo's magic error erasure to stumble around the
333rest of Hoon's atom syntax. Any string that can't be extended
352rest of Hoon's atom syntax. Any string that can't be extended
334into a valid expression will be trimmed back, with a beep, until
353into a valid expression will be trimmed back, with a beep, until
335it can. Return will beep if the expression is not complete.
354it can. Return will beep if the expression is not complete.
336−This feedback is harmless and does not use an electric shock,
355+This feedback is harmless and does not use an electric shock.
337−but it enables stochastic reinforcement learning of Hoon syntax.
356+It enables stochastic reinforcement learning of Hoon syntax.
338
357
339If `~h6` is six hours, how do you write forty-five minutes? Two
358If `~h6` is six hours, how do you write forty-five minutes? Two
340days, six hours and forty-five minutes?
359days, six hours and forty-five minutes?
docs/byte/2.md+66−35
@@ -176,7 +176,7 @@ Of course, the fragment retains the type it had when we built it.
176## Labeled surfaces
176## Labeled surfaces
177
177
178We can obviously get anything we want out of the subject by tree
178We can obviously get anything we want out of the subject by tree
179−geometry. But it's not really how we'd like to program. We'd
179+geometry. But that's not really how we'd like to program. We'd
180much rather *label* subtrees with convenient, memorable symbols.
180much rather *label* subtrees with convenient, memorable symbols.
181
181
182For example, suppose our tree looked like:
182For example, suppose our tree looked like:
@@ -220,7 +220,7 @@ table here -- just a tree search.
220
220
221An expression like the label `x` or the axis `+2`, which
221An expression like the label `x` or the axis `+2`, which
222designates a fragment or feature of the subject, is called a
222designates a fragment or feature of the subject, is called a
223−*limb*. Limbs can be connected with a `.`, making a *wing*.
223+*limb*. A list of limbs connected with `.`, is a *wing*.
224
224
225To remind you that you're not in Kansas anymore, the syntax for a
225To remind you that you're not in Kansas anymore, the syntax for a
226wing, like `q.y` above, means means "q inside y." In a classic
226wing, like `q.y` above, means means "q inside y." In a classic
@@ -233,7 +233,7 @@ that is, attribute `q` within object `y`. In Hoon, `q.y` means
233Once again, Hoon has no symbol tables. When we put a surface
233Once again, Hoon has no symbol tables. When we put a surface
234on a noun, the surface label is part of that noun's type. It's
234on a noun, the surface label is part of that noun's type. It's
235not part of the cell or other structure that contains the noun.
235not part of the cell or other structure that contains the noun.
236−For example:
236+This will take a little getting used to:
237
237
238```
238```
239> ? x:a
239> ? x:a
@@ -249,8 +249,8 @@ x=42
24942
24942
250```
250```
251
251
252−When we take fragment 2 of the labeled subject the *surface
252+When we take fragment 2 of the labeled subject, the *surface
253−comes with it *. `+2` is not `42` but rather `x=42`. We can
253+comes with it*. `+2` is not `42` but rather `x=42`. We can
254take the surface off with `x.+2`.
254take the surface off with `x.+2`.
255
255
256## The search algorithm
256## The search algorithm
@@ -323,18 +323,22 @@ classical language. But where is Hoon's equivalent of objects:
323values which bind code to data?
323values which bind code to data?
324
324
325The Hoon equivalent of an object is a *core*. As usual in Hoon,
325The Hoon equivalent of an object is a *core*. As usual in Hoon,
326−the resemblance isn't exact. A core has a set of computed
326+the resemblance is inexact. A core has a set of computed
327attributes, or *arms*. Each arm is an expression whose subject
327attributes, or *arms*. Each arm is an expression whose subject
328is the core. There is no argument, so an arm is not a method.
328is the core. There is no argument, so an arm is not a method.
329
329
330Physically, a core is always a cell `[battery payload]`, where
330Physically, a core is always a cell `[battery payload]`, where
331the *payload* is any noun, and the *battery* is a tree of
331the *payload* is any noun, and the *battery* is a tree of
332formulas in Nock (Hoon's functional assembly language) that
332formulas in Nock (Hoon's functional assembly language) that
333−implements the arms.
333+implements the arms. (A battery is like a C++ vtable, sort of.)
334
334
335+## The search algorithm
336+
335−As you'd expect with a computed attribute, an expression which
337+As you'd expect with a computed attribute, there is only one
338+namespace and one search algorithm. We just extend the algorithm
339+described above. And an expression which uses a label can't know
336−uses a label can't know whether the subject will resolve it to a
340+whether the subject will resolve it to a surface fragment (a
337−surface fragment (a *leg*) or to an arm.
341+*leg*) or to an arm.
338
342
339If we're searching a core and the label matches one of the core's
343If we're searching a core and the label matches one of the core's
340arms, we compute the arm against the core. If the label is not
344arms, we compute the arm against the core. If the label is not
@@ -357,10 +361,55 @@ from "two or more spaces."
35742
36142
358
362
359> =b :per a :core ++ foo x ++ bar [q.y foo] --
363> =b :per a :core ++ foo x ++ bar [q.y foo] --
364+```
365+
366+We're seeing some Hoon regular forms for the first time. `x:a`
367+turns out to be an irregular relative of the regular `:per` form.
368+
369+We'll get more into syntax in a later Urbyte. If some of these
370+examples seem syntactically a little funky, this isn't usually
371+way we'd do them in "real life." We don't normally write cores
372+on a single command line. In a file this would be:
373+
374+```
375+ :per a
376+ :core
377+ ++ foo x
378+ ++ bar [q.y foo]
379+ --
380+```
381+
382+which is much more readable, at least once you get used to it.
383+Let's look at the core itself:
360
384
385+```
361> b
386> b
362<2.spy {x/@ud y/{p/$foo q/@rs r/@dr} x/@ux}>
387<2.spy {x/@ud y/{p/$foo q/@rs r/@dr} x/@ux}>
363
388
389+> ? +2:b
390+ *
391+[[0 6] [0 58] 9 4 0 1]
392+
393+> ? +3:b
394+ {x/@ud y/{p/$foo q/@rs r/@dr} x/@ux}
395+[x=42 y=[p=%foo q=.6.28 r=~m45] x=0xdead.beef]
396+```
397+
398+When we print `b`, or any core, we see that typed noun printing
399+can't be an invertible function in Hoon.
400+
401+We actually can read the battery (with `+2:b` above), but it's
402+just Nock code, not typed data. `<2.spy>` tells us the battery
403+has two arms and hashes to the three-letter code `spy`.
404+
405+When printing a full core, we don't even print the payload data,
406+just its type. But our `+3:b` confirms the `[battery payload]`
407+structure of the core. Remember, `+2` is the head and `+3` is
408+the tail.
409+
410+Finally, let's use this thing:
411+
412+```
364> ? foo:b
413> ? foo:b
365 @ud
414 @ud
36642
41542
@@ -372,27 +421,9 @@ from "two or more spaces."
372? x:b
421? x:b
373 @ud
422 @ud
37442
42342
375−
376−> ? +2:b
377− *
378−[[0 6] [0 58] 9 4 0 1]
379```
424```
380
425
381−We're seeing some Hoon regular forms for the first time. `x:a`
426+Seems legit.
382−turns out to be an irregular relative of the regular `:per` form.
383−
384−(We'll get more into syntax in a later Urbyte. If some of these
385−examples seem syntactically a little funky, this isn't usually
386−way we'd do them in "real life." We don't normally write cores
387−on one line in the dojo, for instance.)
388−
389−And when we print `b`, or any core, we see that typed noun
390−printing can't be an invertible function in Hoon.
391−
392−We actually can read the battery (with `+2:b` above), but it's
393−just Nock code, not typed data. We don't even print the payload
394−data, though we print the payload type. The `<2.spy>` just shows
395−a core with two arms, for which `spy` is a hash code.
396
427
397## The dojo subject
428## The dojo subject
398
429
@@ -415,14 +446,14 @@ directly at the real dojo subject:
415
446
416We see a bunch of surfaces: our custom `a` and `b`; standard
447We see a bunch of surfaces: our custom `a` and `b`; standard
417surfaces for identity, date, and entropy; and a ginormous core
448surfaces for identity, date, and entropy; and a ginormous core
418−stack with almost a thousand total arms.
449+stack with *over eight hundred* total arms.
419
450
420To be exact, the syntax `<283.xzp 42.ajz 407.xtr 110.xht 1.ztu
451To be exact, the syntax `<283.xzp 42.ajz 407.xtr 110.xht 1.ztu
421−$151>` denotes a system of six cores, each of whose payload is
452+$151>` denotes a stack of six cores, each of whose payload is
422another core, until the innermost payload `%151` (the Hoon
453another core, until the innermost payload `%151` (the Hoon
423−version). This stack is our standard library, from which comes
454+version number). This stack is our standard library, from which
424−`add` and other fine functions. (We don't know how to define a
455+comes `add` and other fine functions. (We don't know how to
425−Hoon function yet, but we're getting close.)
456+write a Hoon function yet, but we're getting way closer.)
426
457
427Let's clean up our subject, just to be hygienic:
458Let's clean up our subject, just to be hygienic:
428
459
@@ -458,7 +489,7 @@ $
458As always, these questions are optional and only for fun.
489As always, these questions are optional and only for fun.
459
490
460What's the best way to construct a core which acts as a function?
491What's the best way to construct a core which acts as a function?
461−How do you call the function?
492+What do you do to call the function?
462
493
463Why don't any other languages use subject-oriented programming?
494Why don't any other languages use subject-oriented programming?
464Which languages are most similar to it?
495Which languages are most similar to it?