64228d6 · urbit.org · git.iko.soy

git.iko.soy/urbit.org

on master help sign in

cleans up arvo tutorials (fixes formatting, corrects a couple examples)

64228d6Joseph Bryan10 years ago

docs/arvo/basic.md+14−4

compare with master

unifiedsplit

@@ -29,8 +29,18 @@ at the [basic operation](/docs/using/admin) of your urbit.

29If you haven't copied in the examples repo, running the following

30commands from your urbit directory should do the trick:

32−`$ cp -r {wherever-you've-pulled-to}/examples/gall/*/ arvo/`

32+Make sure you've mounted your `%home` desk:

33−`$ cp -r {wherever-you've-pulled-to}/examples/dojo/*/ arvo/`

33+

34+```

35+~fintud-macrep:dojo> |mount %

36+```

37+

38+Then, copy the example into it

39+

40+```

41+$ cp -r {urbit-examples}/gall/*/ {your-pier}/home/

42+$ cp -r {urbit-examples}/dojo/*/ {your-pier}/home/

43+```

35Run an example to ensure it worked:

45Run an example to ensure it worked:

@@ -213,8 +223,8 @@ of the code. However, `b` is not an argument; `=|` sets `b` to the

213default value of whatever type it is declared as. Since the default

223default value of whatever type it is declared as. Since the default

214value of an atom is `0`, b is set to `0`.

224value of an atom is `0`, b is set to `0`.

215

225

216−> To produce the default value of any given type, use `$*` ('buctar')

226+> To produce the default value of any given type, use `*` ('tar')

217−> followed by the type. Alternatively, use the irregular form `*`.

227+> followed by the type. This operaction is called *bunt*.

218>

228>

219> > *@ :: produce the default value of atom @

229> > *@ :: produce the default value of atom @

220> 0

230> 0

docs/arvo/generators.md+20−24

@@ -65,13 +65,11 @@ optionally specify the message as well.

65We'll need a new mark for our arguments. Let's call it

66`examples-ping-message`.

68−<blockquote class="blockquote">

69−For app-specific marks, it's good style to prefix the name of

68+> For app-specific marks, it's good style to prefix the name of

70−the mark with the name of the app. Since many apps have

69+> the mark with the name of the app. Since many apps have

71−several such marks, subdirectories in `/mar` are rendered as

70+> several such marks, subdirectories in `/mar` are rendered as

72−`-`, so that `ping-message` is written in

71+> `-`, so that `ping-message` is written in

73−(/mar/examples/ping/message.hoon).

72+> (/mar/examples/ping/message.hoon).

74−</blockquote>

76```

74```

77:: Up-ness monitor. Accepts atom url, 'on', or 'off'

75:: Up-ness monitor. Accepts atom url, 'on', or 'off'

@@ -214,23 +212,21 @@ text and null.

214Secondly, `?~(a b c)` is a rune which means "if the `a` is null,

212Secondly, `?~(a b c)` is a rune which means "if the `a` is null,

215do `b`, else `c`". It is roughly equivalent to `?:(=(~ a) b c)`.

213do `b`, else `c`". It is roughly equivalent to `?:(=(~ a) b c)`.

216

214

217−<blockquote class="blockquote">

218−`?~(a b c)` is actually equivalent to `?:=(?=(~ a) b c)`,

215+> `?~(a b c)` is actually equivalent to `?:=(?=(~ a) b c)`,

219−which, although identical at run time, is subtly different at

216+> which, although identical at run time, is subtly different at

220−compile time. Specifically, using `?=` rather than `=` means

217+> compile time. Specifically, using `?=` rather than `=` means

221−that we're checking whether `a` is in the *type* of `~`, and so

218+> that we're checking whether `a` is in the *type* of `~`, and so

222−the compiler knows that in the `b` case `a` is null, and in the

219+> the compiler knows that in the `b` case `a` is null, and in the

223−`c` case `a` is not null. Since `=` is purely a runtime value

220+> `c` case `a` is not null. Since `=` is purely a runtime value

224−check with no type implications, the compiler doesn't gain any

221+> check with no type implications, the compiler doesn't gain any

225−information.

222+> information.

226−

223+>

227−At any rate, this is the reason why we can refer to

224+> At any rate, this is the reason why we can refer to

228−`text.message` in the `c` clause. The compiler knows that

225+> `text.message` in the `c` clause. The compiler knows that

229−`message` is not null, so it must have `text` within it. If

226+> `message` is not null, so it must have `text` within it. If

230−you used `?:(=(~ message) 'howdy' text.message)` the compiler

227+> you used `?:(=(~ message) 'howdy' text.message)` the compiler

231−would complain that it doesn't know whether `message` has

228+> would complain that it doesn't know whether `message` has

232−`text` within it.

229+> `text` within it.

233−</blockquote>

234

230

235This is run as follows:

231This is run as follows:

236

232

docs/arvo/http.md+19−29

@@ -77,12 +77,10 @@ line, though.

77Firstly, there's two kinds of cards we're sending to arvo. A

78`%them` card makes an HTTP requrest out of a unit `hiss`.

80−<blockquote class="blockquote">

81−Recall that `++unit` means "maybe". Formally, "`(unit a)` is

80+> Recall that `++unit` means "maybe". Formally, "`(unit a)` is

82−either null or a pair of null and a value in `a`". Also recall

81+> either null or a pair of null and a value in `a`". Also recall

83−that to pull a value out of a unit `(u.unit)`, you must first

82+> that to pull a value out of a unit `(u.unit)`, you must first

84−verify that the unit is not null (for example with `?~`).

83+> verify that the unit is not null (for example with `?~`).

85−</blockquote>

87A `hiss` (all of the following terms are defined in `zuse`) is a

85A `hiss` (all of the following terms are defined in `zuse`) is a

88pair of a `purl` and a `moth`. A `purl` is a parsed url

86pair of a `purl` and a `moth`. A `purl` is a parsed url

@@ -96,11 +94,9 @@ of HTTP headers. The `(unit octs)` is a possible octet stream

96representing the body. If it's null, then no body is sent (as in

94representing the body. If it's null, then no body is sent (as in

97this case).

95this case).

99−<blockquote class="blockquote">

100−An octect stream is a pair of the length in bytes of the data

97+> An octect stream is a pair of the length in bytes of the data

101−plus the data itself. You can use `++taco` takes text and

98+> plus the data itself. You can use `++taco` takes text and

102−turns it into an octet strem.

99+> turns it into an octet strem.

103−</blockquote>

104

100

105When you send this request, you can expect a `%thou` with the

101When you send this request, you can expect a `%thou` with the

106response, which we handle later on in `++thou-request`.

102response, which we handle later on in `++thou-request`.

@@ -108,11 +104,9 @@ response, which we handle later on in `++thou-request`.

108For `%wait`, you just pass a [`@da`]() (absolute date), and arvo will

104For `%wait`, you just pass a [`@da`]() (absolute date), and arvo will

109produce a `%wake` when the time comes.

105produce a `%wake` when the time comes.

110

106

111−<blockquote class="blockquote">

112−A timer is guaranteed to not be triggered before the given

107+> A timer is guaranteed to not be triggered before the given

113−time, but it's currently impossible to guarantee the timer will be

108+> time, but it's currently impossible to guarantee the timer will be

114−triggered at exactly the requested time.

109+> triggered at exactly the requested time.

115−</blockquote>

116

110

117Let's take a look at our state:

111Let's take a look at our state:

118

112

@@ -133,11 +127,9 @@ of `value`, but make the default value be `value`". Thus, our

133type is still a boolean, just like `?`, but the default value is

127type is still a boolean, just like `?`, but the default value is

134`|` (false).

128`|` (false).

135

129

136−<blockquote class="blockquote">

137−This is the same `_` used in `_+>.$`, which means "the same

130+> This is the same `_` used in `_+>.$`, which means "the same

138−type as the value "+>.$". In other words, the same type as our

131+> type as the value "+>.$". In other words, the same type as our

139−current context and state.

132+> current context and state.

140−</blockquote>

141

133

142Let's take a look at `++poke-cord`. When we're poked with a

134Let's take a look at `++poke-cord`. When we're poked with a

143cord, we first check whether it's `'off'`. If so, we set `on` to

135cord, we first check whether it's `'off'`. If so, we set `on` to

@@ -151,14 +143,12 @@ This request follows the pattern in `++hiss` well. `(need (epur

151target))` is the parsed url, `%get` is the HTTP method, `~`

143target))` is the parsed url, `%get` is the HTTP method, `~`

152means no extra headers, and another `~` means no body.

144means no extra headers, and another `~` means no body.

153

145

154−<blockquote class="blockquote">

155−Note the `~` at the end of the move. This is a convenient

146+> Note the `~` at the end of the move. This is a convenient

156−shortcut for creating a list of a single element. It's part of

147+> shortcut for creating a list of a single element. It's part of

157−a small family of such shortcuts. `~[a b c]` is `[a b c ~]`,

148+> a small family of such shortcuts. `~[a b c]` is `[a b c ~]`,

158−`[a b c]~` is `[[a b c] ~]` and `\`[a b c]` is `[~ a b c]`.

149+> `[a b c]~` is `[[a b c] ~]` and `\`[a b c]` is `[~ a b c]`.

159−These may be mixed and matched to create various convoluted

150+> These may be mixed and matched to create various convoluted

160−structures and emojis.

151+> structures and emojis.

161−</blockquote>

162

152

163If the argument is neither 'off' nor 'on', then we assume it's an

153If the argument is neither 'off' nor 'on', then we assume it's an

164actual url, so we save it in `target`.

154actual url, so we save it in `target`.

docs/arvo/network.md+29−28

@@ -34,7 +34,8 @@ a value, it prints that value out. To try this out, you have to start

34the app, then you can poke it from the command line with the following

35commands:

37− ~fintud-macrep:dojo> |start %echo

37+ ~fintud-macrep:dojo> |start %examples-echo

38+ 'prep'

38 >=

39 >=

39 ~fintud-macrep:dojo> :examples-echo 5

40 ~fintud-macrep:dojo> :examples-echo 5

40 [%argument 5]

41 [%argument 5]

@@ -169,7 +170,7 @@ Run it with these commands:

169

170

170 ~fintud-macrep:dojo> |start %examples-pong

171 ~fintud-macrep:dojo> |start %examples-pong

171 >=

172 >=

172− ~fintud-macrep:dojo> :pong &examples-urbit ~sampel-sipnym

173+ ~fintud-macrep:dojo> :examples-pong &urbit ~sampel-sipnym

173 >=

174 >=

174

175

175Replace `~sampel-sipnym` with another urbit. The easiest thing to do is

176Replace `~sampel-sipnym` with another urbit. The easiest thing to do is

@@ -220,7 +221,7 @@ Let's walk through each of these elements step by step.

220If you look up `++bone` in `hoon.hoon`, you'll see that it's a number

221If you look up `++bone` in `hoon.hoon`, you'll see that it's a number

221(`@ud`), and that it's an opaque reference to a duct. `++duct` in

222(`@ud`), and that it's an opaque reference to a duct. `++duct` in

222hoon.hoon is a list of `wire`s, where `++wire` is an alias for `++path`.

223hoon.hoon is a list of `wire`s, where `++wire` is an alias for `++path`.

223−`++path` is a list of `++span`s, which are ASCII text. Thus, a duct is a

224+`++path` is a list of `++knot`s, which are ASCII text. Thus, a duct is a

224list of paths, and a bone is an opaque reference to it (in the same way

225list of paths, and a bone is an opaque reference to it (in the same way

225that a Unix file descriptor is an opaque reference to a file structure).

226that a Unix file descriptor is an opaque reference to a file structure).

226Thus, to truly understand bones, we must understand ducts.

227Thus, to truly understand bones, we must understand ducts.

@@ -283,7 +284,7 @@ The move ends with `*` (that is, any noun) since each type of move takes

283different data. In our case, a `%poke` move takes a target (urbit and

284different data. In our case, a `%poke` move takes a target (urbit and

284app) and marked data, then pokes the arm of the corresponding mark on

285app) and marked data, then pokes the arm of the corresponding mark on

285that app on that urbit with that data. `[to-urbit-address %pong]` is the

286that app on that urbit with that data. `[to-urbit-address %pong]` is the

286−target urbit and app, `%atom` is the mark`, and`'howdy'\` is the data.

287+target urbit and app, `%atom` is the `mark`, and`'howdy'` is the data.

287

288

288When arvo receives a `%poke` move, it calls the appropriate `++poke`.

289When arvo receives a `%poke` move, it calls the appropriate `++poke`.

289The same mechanism is used for sending messages between apps on the same

290The same mechanism is used for sending messages between apps on the same

@@ -312,30 +313,30 @@ urbit as for sending messages between apps on different urbits.

312 the end, you should be able to watch Collatz's conjecture play out

313 the end, you should be able to watch Collatz's conjecture play out

313 between the two apps. Sample output:

314 between the two apps. Sample output:

314

315

315−

316+```

316−

317− ~fintud-macrep:dojo> :even &atom 18

317+~fintud-macrep:dojo> :even &atom 18

318− [%even 18]

318+[%even 18]

319− [%odd 9]

319+[%odd 9]

320− [%even 28]

320+[%even 28]

321− [%even 14]

321+[%even 14]

322− [%odd 7]

322+[%odd 7]

323− [%even 22]

323+[%even 22]

324− [%odd 11]

324+[%odd 11]

325− [%even 34]

325+[%even 34]

326− [%odd 17]

326+[%odd 17]

327− [%even 52]

327+[%even 52]

328− [%even 26]

328+[%even 26]

329− [%odd 13]

329+[%odd 13]

330− [%even 40]

330+[%even 40]

331− [%even 20]

331+[%even 20]

332− [%even 10]

332+[%even 10]

333− [%odd 5]

333+[%odd 5]

334− [%even 16]

334+[%even 16]

335− [%even 8]

335+[%even 8]

336− [%even 4]

336+[%even 4]

337− [%even 2]

337+[%even 2]

338− %success

338+%success

339+```

339

340

340- Put `even` and `odd` on two separate urbits and pass the messages

341- Put `even` and `odd` on two separate urbits and pass the messages

341 over the network. Post a link to a working solution in :talk to

342 over the network. Post a link to a working solution in :talk to

docs/arvo/state.md+10−3

@@ -99,6 +99,13 @@ ever go through the hassle of having to set up and write to a database.

99- Write an app that prints out the previous value you poked it with.

100 Sample output:

101

102+```

102−\`\`\` \~fintud-macrep:dojo\> :examples-last 7 [%last 0] \>=

103+~fintud-macrep:dojo> :examples-last 7

104+[%last 0]

105+>=

103−\~fintud-macrep:dojo\> :examples-last [1 2 3][%last 7] \>=

106+~fintud-macrep:dojo> :examples-last [1 2 3]

107+[%last 7]

108+>=

104−\~fintud-macrep:dojo\> :examples-last 'howdy' [%last [1 2 3]]

109+~fintud-macrep:dojo> :examples-last 'howdy'

110+[%last [1 2 3]]

111+```

docs/arvo/subject.md+3−3

@@ -36,7 +36,7 @@ Hoon, we call the code executed the "formula" and its context the

36"subject".

38 ::::::::::::::::::::::::::::::

39− =< (sum [1.000 2.000]) :: formula

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

40 ::::::::::::::::::::::::::::::

41 |% ::

42 ++ three ::

@@ -58,8 +58,8 @@ Hoon, we call the code executed the "formula" and its context the

58 (add b $(b (add b 5))) ::

59 ::

60 ++ sum ::

61− |= a/@u ::

61+ |= {a/@u b/@u} ::

62− (add (five a) (three a)) ::

62+ (add (five a) (three b)) ::

63 -- ::

64 ::::::::::::::::::::::::::::::

docs/arvo/web-apps.md+1−1

@@ -145,7 +145,7 @@ the app from the command line.

145 `:click` and print out the subscription updates on the command

146 line.

147

148−#Frontend

148+# Frontend

149

150That's all that's needed for the back end. The front end is just

151some "sail" html (Hoon markup for XML) and javascript. Here's `/web/click.hoon`: