6024303 · urbit.org · git.iko.soy

git.iko.soy/urbit.org

Merge branch 'cleanorg'

commit6024303bdf1f8b9c57986c63e4805b16b7b9f74e authorTobias Merkle <tgamerkle@gmail.com> dateTue 7 Jun 2016, 17:00 (10 years ago) parent3f637d8 4290670

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

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

9090```

9191

9292

93−<blockquote class="blockquote">

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

95−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

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

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

99−excercises.

100−</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+> exercises.

10199

102100

103101### Lines 1-11:

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

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

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

184182

185−<blockquote class="blockquote">

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

187−in core syntax, as shown above.

188−</blockquote>

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

184+> in core syntax, as shown above.

189185

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

191187

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

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

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

230226

231−<blockquote class="blockquote">

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

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

234−

235−```

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

237− 0

238−

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

240− ~zod

241−

242−```

243−</blockquote>

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

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

229+>

230+> ```

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

232+> 0

233+>

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

235+> ~zod

236+>

237+> ```

244238

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

246240initialized to `0`.

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

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

264258every argument.

265259

266−<blockquote class="blockquote">

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

268−</blockquote>

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

269261

270262**Exercises**:

271263

docs/arvo/network.md+36−41

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

4646>=

4747```

4848

49−<blockquote class="blockquote">

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

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

52−look exactly like this.

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

54−executed.

55−</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.

5654

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

5856function. 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

6260interact with it by sending it messages. The most

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

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

65−[argument(s)]).

63+[argument(s)]`).

6664

6765In 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

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

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

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

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

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

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

9088app 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

9290"app state".

9391

9492Let'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,

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

123121mark to exist, however.

124122

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

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

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

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

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

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

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

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

129127

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

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

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

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

148146> line.

149147

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

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

152150

153151**Exercise**:

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

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

156154 previous section).

157155

158−# Sending a message to another ship

156+# Sending a message to another urbit

159157

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

161159

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

192190```

193191

194192Replace `~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

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

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

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

197195see, on the foreign urbit, this output:

198196

199197```

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

201199```

202200

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

204−the only new thing is the expression `(@t 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.

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

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

206204

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

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

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

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

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

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

211209to 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

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

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

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

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

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

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

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

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

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

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

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

300298

301299##### Term (sys-call)

302300

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

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

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

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

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

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

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

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

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

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

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

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

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

311307

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

313309different 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

315311corresponding mark on that app on that urbit

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

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

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

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

322318apps on different urbits.

323319

324−<blockquote class="blockquote">

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

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

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

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

329−</blockquote>

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

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

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

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

330324

331325**Exercises**:

332326

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

369363%success

370364```

371365

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

373− messages over the network.

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

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,

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

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

6262

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

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

6565meaning 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

67−you want.

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

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

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

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

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

74−

75−<blockquote class="blockquote">

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

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

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

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

80−libraries", and they're usually not hard 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

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

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

85−comments as reference doc.

86−</blockquote>

87−

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

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

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

68+

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

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

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

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

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

74+`/arvo/zuse.hoon`.

75+

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

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

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

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

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

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

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

83+> comments as a reference doc.

84+>

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+Urbit needs no "serialize to disk" step.

8989Everything you produce in the app state is persistent across

9090calls 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

9292needed for persistence. Urbit has transactional events, which

9393makes 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

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

9696

9797**Exercises**:

9898

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.

100100

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

102102 with. Sample output:

docs/arvo/subject.md+14−12

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

1414 :- %noun

1515 =< (sum [1.000 2.000])

1616

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

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

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,

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

1920

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

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

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

2324

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

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

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

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

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

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

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

2729

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

2931context 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

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

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

3335

3436```

3537::::::::::::::::::::::::::::::

36−=< (sum 1.000) :: formula

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

3739::::::::::::::::::::::::::::::

3840|% ::

3941++ three ::

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

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

7274Hoon takes takes the concept one step further.

7375

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

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

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

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

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

8082

8183**Exercises**:

8284

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

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

8486 commandline.

8587

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

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

100102 `[new-element list]`

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

102104 ~]`

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

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

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

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

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