308eed0 · urbit.org · git.iko.soy

git.iko.soy/urbit.org

Monday fixup

commit308eed0c8324482f1d112cdd6ac2e2dbbb1877a5 authorTobias Merkle <tgamerkle@gmail.com> dateTue 7 Jun 2016, 16:57 (10 years ago) parent2288adf

4 files changed+97−108

compare with master

unifiedsplit

docs/arvo/basic.md+20−28 docs/arvo/network.md+36−41 docs/arvo/state.md+27−27 docs/arvo/subject.md+14−12

docs/arvo/basic.md+20−28

@@ -89,14 +89,12 @@ under `/gen/examples/euler1`):

8989```

9090

9191

92−<blockquote class="blockquote">

93−Hoon is not generally whitespace sensitive, but we do have two

94−different kinds of whitespace: a single space and a gap, which

95−is two or more spaces or a linebreak. Tabs are taboo. Do not

96−use them. Really. For a more detailed explanation of when to

97−use spaces vs. gaps, see the syntax section before the first

98−excercises.

99−</blockquote>

92+> Hoon is not generally whitespace sensitive, but we do have two

93+> different kinds of whitespace: a single space and a gap, which

94+> is two or more spaces or a linebreak. Tabs are taboo. Do not

95+> use them. Really. For a more detailed explanation of when to

96+> use spaces vs. gaps, see the syntax section before the first

97+> exercises.

10098

10199

102100### Lines 1-11:

@@ -181,10 +179,8 @@ element in this map begins with a `++` followed by the name and

181179the corresponding code. Since `|%` takes an arbitrary number of

182180children, it needs to be closed with a `--`.

183181

184−<blockquote class="blockquote">

185−`++` ('luslus') is not technically a rune, since it is only used

186−in core syntax, as shown above.

187−</blockquote>

182+> `++` ('luslus') is not technically a rune, since it is only used

183+> in core syntax, as shown above.

188184

189185Let's step into each of the three arms within our core.

190186

@@ -227,19 +223,17 @@ the remainder of the code. However, `b` is not an argument; `=|`

227223sets `b` to the default value of whatever type it is declared as.

228224Since the default value of an atom is `0`, b is set to `0`.

229225

230−<blockquote class="blockquote">

231−To produce the default value of any given type, use `$*` ('buctar') followed by the type.

232−Alternatively, use the irregular form `*`.

233−

234−```

235− > *@ :: produce the default value of atom @

236− 0

237−

238− > *@p :: produce the phonemic base of atom @

239− ~zod

240−

241−```

242−</blockquote>

226+> To produce the default value of any given type, use `$*` ('buctar') followed by the type.

227+> Alternatively, use the irregular form `*`.

228+>

229+> ```

230+> > *@ :: produce the default value of atom @

231+> 0

232+>

233+> > *@p :: produce the phonemic base of atom @

234+> ~zod

235+>

236+> ```

243237

244238So now we have two variables: `a` is set to our input, and `b` is

245239initialized to `0`.

@@ -262,9 +256,7 @@ Note that we only specify what changes (`b` in this case). If

262256you recurse by an actual function call, then you have to specify

263257every argument.

264258

265−<blockquote class="blockquote">

266−If you're familiar with Clojure, `|-` is `loop` and `$()` is `recur`.

267−</blockquote>

259+> If you're familiar with Clojure, `|-` is `loop` and `$()` is `recur`.

268260

269261**Exercises**:

270262

docs/arvo/network.md+36−41

@@ -45,13 +45,11 @@ with the following commands:

4545>=

4646```

4747

48−<blockquote class="blockquote">

49−There is currently a bug where the `%argument` lines are

50−printed *above* the line you entered, so your output may not

51−look exactly like this.

52−`>=` means that a command was successfully received and

53−executed.

54−</blockquote>

48+> There is currently a bug where the `%argument` lines are

49+> printed *above* the line you entered, so your output may not

50+> look exactly like this.

51+> `>=` means that a command was successfully received and

52+> executed.

5553

5654Most of the app code should be simple enough to guess its

5755function. The important part of this code is the definition of

@@ -61,10 +59,10 @@ Once an app starts, it's always running in the background and you

6159interact with it by sending it messages. The most

6260straightforward way to do that is to poke it from the command

6361line, which we we did with `:echo 5` (`:[app-name]

64−[argument(s)]).

62+[argument(s)]`).

6563

6664In this case, `++poke-noun` takes an argument `arg` and prints it

67−out with `~&`. This is an unusual rune that formally "does

65+out with `~&` (sigpam). This is an unusual rune that formally "does

6866nothing", but the interpreter detects it and printfs the first

6967child, before executing the second as if the first didn't exist.

7068This is a slightly hacky way of printing to the console, but

@@ -87,7 +85,7 @@ line).

8785The second thing `++poke-noun` produces is our state. `+>.$`

8886refers to a particular address in our subject where our formal

8987app state is stored. It'll become clear why this is later on,

90−but for now pretend that `+>.$` is a magic invocation that means

88+but for now pretend that `+>.$` is a magic incantation that means

9189"app state".

9290

9391Let's look at another example (edit your code in `/app/examples/echo/hoon` to reflect the code below). Say we want to only accept a

@@ -121,10 +119,10 @@ have conversion routines to other marks, and some have diff,

121119patch, and merge algorithms. None of these are required for a

122120mark to exist, however.

123121

124−`noun` and `atom` are two of dozens of predefined marks (that will

125−already be in your `/mar` directory), and the

126−user may add more at will. The type associated with `noun` is

127−`*`, and the type associated with `atom` is `@`.

122+`noun` and `atom` are two predefined marks. In your `/mar`

123+directory, there are already many more, and you may add more

124+at will. The type associated with `noun` is `*`, and the type

125+associated with `atom` is `@`.

128126

129127When we poke an app from anywhere, we do so with a mark that

130128searches for the corresponding (`++poke-[mark]`) arm. Data

@@ -146,7 +144,7 @@ gall: %square: no poke arm for noun

146144> Recall the bug where `%square` may get printed above the input

147145> line.

148146

149−Marks are powerful, and they're the backbone of urbit's data

147+Marks are powerful, and they're the backbone of Urbit's data

150148pipeline, so we'll be getting quite used to them.

151149

152150**Exercise**:

@@ -154,7 +152,7 @@ pipeline, so we'll be getting quite used to them.

154152- Write an app that computes fizzbuzz on its input (as in the

155153 previous section).

156154

157−# Sending a message to another ship

155+# Sending a message to another urbit

158156

159157Let's write our first network message! Here's `/app/examples/pong.hoon`:

160158

@@ -191,8 +189,8 @@ Run it with these commands:

191189```

192190

193191Replace `~sampel-sipnym` with another urbit. The easiest thing to

194−do is to start a moon, a sub-identity of your urbit. If you don't know how to start a moon, see [the user admin section](/docs/using/admin/) Don't

195−forget to start the `%examples-pong` app on that urbit too. You should

192+do is to start a moon, a sub-identity of your urbit. If you don't know how to start a moon, see [the user admin section](/docs/using/admin/). Don't

193+forget to start the `%examples-pong` app on that urbit, too. You should

196194see, on the foreign urbit, this output:

197195

198196```

@@ -200,11 +198,11 @@ see, on the foreign urbit, this output:

200198```

201199

202200Most of the code should be straightforward. In `++poke-atom`,

203−the only new thing is the expression `(@t arg)`. As we already

204−know, `@t` is the type of "cord" text strings. In Hoon, when types are called as functions, they serve as a validator function (called a "clam" in hoon) -- that is, a function whose domain is all nouns and range is the given type.

201+the only new thing is the expression `(@t arg)`, which is the type `@t` being called as a function with argument `arg`. As we already

202+know, `@t` is the type of "cord" text strings. In Hoon, when types are called as functions, they serve as a validator function called a "clam" -- that is, a function whose domain is all nouns, and range is the given type (in this case, `@t`).

205203

206−In simpler terms, if a validator function is passed a value that

207−falls within its type, that value is produced. Otherwise, it

204+In simpler terms, if a clam is passed a value of its own

205+type, it produces that value. Otherwise, it

208206produces the default value (aka the "bunt") of its type. Here we call

209207this `@t` function on the argument. This coerces the argument

210208to text, so that we can print it out prettily no matter what

@@ -289,8 +287,8 @@ Of course, we have to push a new layer onto our duct

289287before passing it along (or responding to it directly) anywhere. This

290288layer can have any data we want in it, but we don't need anything

291289specific here, so we just use the wire `/sending`

292−(`/elem1/elem2/elem n` is one syntax used to create `++path`s and

293−`++wire`s of n elements). If we were expecting a response (which

290+(`/elem1/elem2/elemN` is one syntax used to create `++path`s and

291+`++wire`s of N elements). If we were expecting a response (which

294292we're not), it would come back along the `/sending` wire, meaning

295293that the path `/sending` will be passed back to the response

296294handler as an argument. Although it's not required, it's

@@ -299,18 +297,16 @@ bug-handling purposes.

299297

300298##### Term (sys-call)

301299

302−Looking back at the general form of a move, there is a

303−`term`--which is text composed lowercase ascii and `-`, and has

304−the sign of `@tas`-- which in this case is `%poke`. This is the

305−name of the particular kind of move we're sending. If you think

306−of a move as a syscall (which you should), then this `term` is

307−the name of the syscall. Common ones include: `%poke`, to

308−message an app; `%warp`, to read from the filesystem; `%wait`, to

300+Each move also has a `term`, composed of lowercase ASCII and/or `-`.

301+This `term` has the sign `@tas`. In this case, out `term` is `%poke`,

302+which is the name of the particular kind of move we're sending.

303+You can always use `%poke` to message an app. Other common names

304+include `%warp`, to read from the filesystem; `%wait`, to

309305set a timer; and `%them`, to send an http request.

310306

311−The general form ends with `*` (a noun) since each type of move takes

307+The move ends with `*` (that is, any noun) since each type of move takes

312308different data. In our case, a `%poke` move takes a target

313−(urbit and app) and marked data and pokes the arm of the

309+(urbit and app) and marked data, then pokes the arm of the

314310corresponding mark on that app on that urbit

315311with that data. `[to-urbit-address %pong]` is the target urbit and app,

316312`%atom` is the mark`, and `'howdy'` is the data.

@@ -320,12 +316,10 @@ When arvo receives a `%poke` move, it calls the appropriate

320316between apps on the same urbit as for sending messages between

321317apps on different urbits.

322318

323−<blockquote class="blockquote">

324−We said earlier that we're not expecting a response. This is

325−not entirely true: the `++coup` is called when we receive

326−acknowledgment that the `++poke` was called. We don't do

327−anything with this information right now, but we could.

328−</blockquote>

319+> We said earlier that we're not expecting a response. This is

320+> not entirely true: the `++coup` is called when we receive

321+> acknowledgment that the `++poke` was called. We don't do

322+> anything with this information right now, but we could.

329323

330324**Exercises**:

331325

@@ -368,5 +362,6 @@ anything with this information right now, but we could.

368362%success

369363```

370364

371−- Put `even` and `odd` on two separate ships and pass the

372− messages over the network.

365+- Put `even` and `odd` on two separate urbits and pass the

366+ messages over the network. Post a link to a working solution

367+ in :talk to receive a cookie.

docs/arvo/state.md+27−27

@@ -59,43 +59,43 @@ It's passed in and produced explicitly. In Unix systems,

5959application state is just a block of memory, which you need to

6060serialize to disk if you want to keep it around for very long.

6161

62−In urbit, app state is a single (usually complex) value. In our

62+In Urbit, app state is a single (usually complex) value. In our

6363example, we have very simple state, so we defined `state=@`,

6464meaning that our state is an atom. Of course, `state` is just a

65−name we're assigning to it, and you're free to use whatever name

66−you want.

67−

68−There are at least two points you may be wondering about. First, `bowl` is a set of general global state that is managed by the system. It

69−includes things like `now` (current time), `our` (our urbit

70−identity), and `eny` (256 bits of guaranteed-fresh entropy). For

71−the full list of things in `++bowl`, search for `++ bowl` (note

72−the double space) in `/arvo/zuse.hoon`.

73−

74−<blockquote class="blockquote">

75−This is a very common technique in learning hoon. While

76−documentation exists, often the easiest way to learn about an

77−identifier you see in code is to search in `/arvo/zuse.hoon`

78−and `/arvo/hoon.hoon` for it. These are our two "standard

79−libraries", and they're usually not hard to read. Since

80−urbit's codebase is relatively small (those two files are less

81−than 15000 lines of code combined, and besides the standard

82−library they include the hoon parser and compiler, plus the

83−/arvo microkernel), you can usually use the code and the

84−comments as reference doc.

85−</blockquote>

86−

87−The second thing is that urbit needs no "serialize to disk" step.

65+name, and you're free to name your state whatever you like. But

66+let's clarify a couple other things before we continue.

67+

68+First, `bowl` is a set of general global states. This set is

69+managed by the system. It includes things like `now` (the

70+current time), `our` (our urbit identity), and `eny` (256 bits

71+of guaranteed-fresh entropy). For the full list of things in

72+`++bowl`, search for `++ bowl` (note: two spaces) in

73+`/arvo/zuse.hoon`.

74+

75+> This is, perhaps, the most common way to learn Hoon.

76+> The easiest way to learn about an identifier you see in code

77+> is to search in `/arvo/zuse.hoon` and `/arvo/hoon.hoon` for it.

78+> These "standard libraries" are usually simple to read. Since

79+> Urbit's codebase is less than 15000 lines of code combined,

80+> including the hoon parser, the compiler, and the

81+> `/arvo` microkernel, you can usually use the code and its

82+> comments as a reference doc.

83+>

84+> You can also read [zuse.hoon](https://github.com/urbit/arvo/blob/master/arvo/zuse.hoon) and [hoon.hoon](https://github.com/urbit/arvo/blob/master/arvo/hoon.hoon) in your browser.

85+

86+The second thing we should clear up is this:

87+Urbit needs no "serialize to disk" step.

8888Everything you produce in the app state is persistent across

8989calls to the app, restarts of the urbit, and even power failure.

90−If you want to write to the filesystem, you can, but it's not

90+If you want to write to the Unix filesystem, you can, but it's not

9191needed for persistence. Urbit has transactional events, which

9292makes it an [ACID operating system](https://en.wikipedia.org/wiki/ACID). Thus, you don't have to

93−worry about persistence when programming in urbit or to ever go

93+worry about persistence when programming in Urbit, or ever go

9494through the hassle of having to set up and write to a database.

9595

9696**Exercises**:

9797

98−- Modify `:examples-sum` to reset the counter when you poke it with zero.

98+- Modify `:examples-sum` to reset the counter when you poke it with 0.

9999

100100- Write an app that prints out the previous value you poked it

101101 with. Sample output:

docs/arvo/subject.md+14−12

@@ -13,26 +13,28 @@ earlier.

1313 :- %noun

1414 =< (sum [1.000 2.000])

1515

16−This program is a cell of two elements: the first, `%say`, tells

17−the interpreter what to produce--in this case a value.

16+The first rune, `:-` (colhep, aka [:cons](/hoon/twig/col-cell/hep-cons/)),

17+constructs the 2-element cell that will be our program. The first element,

18+`%say`, tells the interpreter what to produce--in this case a value.

1819

1920The second element is `|=`, which we know produces a function.

2021`|=`'s first child is its argument(s), which in this case is any

2122noun (`*`). Its second child is the remainder of the program.

2223

23−Similarly, the rest of the program is a cell of the literal

24−`%noun`, which tells the shell that we're producing a value of

25−type `noun`, and the code that we run to actually produce our value of the type `noun`.

24+Similarly, the rest of the program (which we construct

25+with another `:-`) is a cell of the literal `%noun`, which tells

26+the shell that we're producing a value of type `noun`, and the

27+code that we run to actually produce our value of the type `noun`.

2628

27−`=<` is a rune that takes two children. The second child is the

29+`=<` (tisgal) is a rune that takes two children. The second child is the

2830context against which we run the first child. So in this case, we

29−are running the expression `(sum 1.000)` against everything

31+are running the expression `(sum [1.000 2.000])` against everything

3032contained within the `|%`. In Hoon, we call the code executed the

3133"formula" and its context the "subject".

3234

3335```

3436::::::::::::::::::::::::::::::

35−=< (sum 1.000) :: formula

37+=< (sum [1.000 2.000]) :: formula

3638::::::::::::::::::::::::::::::

3739|% ::

3840++ three ::

@@ -70,7 +72,7 @@ Scheme allows a sort of reification of the context through

7072continutations, and some may see a parallel to Forth's stack, but

7173Hoon takes takes the concept one step further.

7274

73−Our starting subject is the standard library, which is defined in

75+Our starting subject is the [standard library](/hoon/library), which is defined in

7476`/arvo/hoon.hoon` and `/arvo/zuse.hoon`. This is where functions

7577like `add` are defined. When we define a core with `|%`, we

7678don't throw away the subject (i.e. the standard library); rather,

@@ -79,7 +81,7 @@ accessible.

7981

8082**Exercises**:

8183

82−- Pass `++sum` its arguments (`2000` and `3000`) from the

84+- Pass `++sum` its arguments (`2.000` and `3.000`) from the

8385 commandline.

8486

8587- Comment out all of the arms of the `|%`. Now add another arm

@@ -99,6 +101,6 @@ Cheatsheet:

99101 `[new-element list]`

100102- For example, the first three positive integers are `[1 2 3

101103 ~]`

102−- `gte` tests whether `a` is greater than or equal to `b`.

103−- `mod` runs the modulo operation on two atoms.

104+- `(gte a b)` tests whether `a` is greater than or equal to `b`.

105+- `(mod a b)` runs the modulo operation on two atoms.

104106- See the basic math section in `/arvo/hoon.hoon` for more info.