6024303 · urbit.org · git.iko.soy

git.iko.soy/urbit.org

on master help sign in

Merge branch 'cleanorg'

6024303Tobias Merkle10 years ago

docs/arvo/basic.md+20−28

compare with master

unifiedsplit

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

90```

93−<blockquote class="blockquote">

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

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

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

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

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

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

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

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

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

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

99−excercises.

98+> exercises.

100−</blockquote>

101

102

100

103### Lines 1-11:

101### Lines 1-11:

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

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

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

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

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

184

182

185−<blockquote class="blockquote">

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

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

187−in core syntax, as shown above.

184+> in core syntax, as shown above.

188−</blockquote>

189

185

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

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

191

187

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

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

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

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

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

230

226

231−<blockquote class="blockquote">

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

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

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

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

234−

229+>

235−```

230+> ```

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

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

237− 0

232+> 0

238−

233+>

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

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

240− ~zod

235+> ~zod

241−

236+>

242−```

237+> ```

243−</blockquote>

244

238

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

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

246initialized to `0`.

240initialized to `0`.

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

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

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

264every argument.

258every argument.

265

259

266−<blockquote class="blockquote">

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

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

268−</blockquote>

269

261

270**Exercises**:

262**Exercises**:

271

263

docs/arvo/network.md+36−41

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

46>=

47```

49−<blockquote class="blockquote">

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

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

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

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

52−look exactly like this.

51+> look exactly like this.

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

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

54−executed.

53+> executed.

55−</blockquote>

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

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

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

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

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

62interact with it by sending it messages. The most

60interact with it by sending it messages. The most

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

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

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

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

65−[argument(s)]).

63+[argument(s)]`).

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

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

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

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

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

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

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

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

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

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

@@ -88,7 +86,7 @@ line).

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

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

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

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

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

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

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

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

92"app state".

90"app state".

94Let'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

92Let'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

@@ -122,10 +120,10 @@ have conversion routines to other marks, and some have diff,

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

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

123mark to exist, however.

121mark to exist, however.

124

122

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

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

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

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

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

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

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

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

129

127

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

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

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

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

@@ -147,7 +145,7 @@ gall: %square: no poke arm for noun

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

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

148> line.

146> line.

149

147

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

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

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

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

152

150

153**Exercise**:

151**Exercise**:

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

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

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

156 previous section).

154 previous section).

157

155

158−# Sending a message to another ship

156+# Sending a message to another urbit

159

157

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

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

161

159

@@ -192,8 +190,8 @@ Run it with these commands:

192```

190```

193

191

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

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

195−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+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

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

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

197see, on the foreign urbit, this output:

195see, on the foreign urbit, this output:

198

196

199```

197```

@@ -201,11 +199,11 @@ see, on the foreign urbit, this output:

201```

199```

202

200

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

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

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

202+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

205−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.

203+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`).

206

204

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -300,18 +298,16 @@ bug-handling purposes.

300

298

301##### Term (sys-call)

299##### Term (sys-call)

302

300

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

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

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

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

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

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

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

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

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

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

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

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

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

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

311

307

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

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

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

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

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

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

315corresponding mark on that app on that urbit

311corresponding mark on that app on that urbit

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

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

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

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

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

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

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

322apps on different urbits.

318apps on different urbits.

323

319

324−<blockquote class="blockquote">

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

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

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

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

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

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

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

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

329−</blockquote>

330

324

331**Exercises**:

325**Exercises**:

332

326

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

369%success

363%success

370```

364```

371

365

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

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

373− messages over the network.

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

368+ in :talk to receive a cookie.

docs/arvo/state.md+27−27

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

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

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

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

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

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

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

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

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

67−you want.

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

68−

68+

69−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+First, `bowl` is a set of general global states. This set is

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

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

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

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

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

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

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

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

74+`/arvo/zuse.hoon`.

74−

75+

75−<blockquote class="blockquote">

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

85−comments as reference doc.

83+> comments as a reference doc.

86−</blockquote>

84+>

87−

85+> 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.

86+

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

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

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

89Everything you produce in the app state is persistent across

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

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

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

92needed for persistence. Urbit has transactional events, which

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

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

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

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

97**Exercises**:

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

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

100

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

102 with. Sample output:

docs/arvo/subject.md+14−12

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

14 :- %noun

15 =< (sum [1.000 2.000])

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

34```

36```

35::::::::::::::::::::::::::::::

37::::::::::::::::::::::::::::::

36−=< (sum 1.000) :: formula

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

37::::::::::::::::::::::::::::::

39::::::::::::::::::::::::::::::

38|% ::

40|% ::

39++ three ::

41++ three ::

@@ -71,7 +73,7 @@ Scheme allows a sort of reification of the context through

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

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

72Hoon takes takes the concept one step further.

74Hoon takes takes the concept one step further.

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

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

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

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

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

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

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

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

@@ -80,7 +82,7 @@ accessible.

81**Exercises**:

83**Exercises**:

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

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

84 commandline.

86 commandline.

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

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

@@ -100,6 +102,6 @@ Cheatsheet:

100 `[new-element list]`

102 `[new-element list]`

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

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

102 ~]`

104 ~]`

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

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

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

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

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

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