on master help sign in
cleans up arvo tutorials (fixes formatting, corrects a couple examples)
commit64228d67701f65245d8f48d9b1a1f8d94ff9108f authorJoseph Bryan <joemfb@gmail.com> dateMon 20 Jun 2016, 19:44 (10 years ago) parentee169bf
7 files changed+96−92
docs/arvo/basic.md+14−4 docs/arvo/generators.md+20−24 docs/arvo/http.md+19−29 docs/arvo/network.md+29−28 docs/arvo/state.md+10−3 docs/arvo/subject.md+3−3 docs/arvo/web-apps.md+1−1
docs/arvo/basic.md+14−4
@@ -29,8 +29,18 @@ at the [basic operation](/docs/using/admin) of your urbit.
2929If you haven't copied in the examples repo, running the following
3030commands from your urbit directory should do the trick:
3131
32−`$ cp -r {wherever-you've-pulled-to}/examples/gall/*/ arvo/`
33−`$ cp -r {wherever-you've-pulled-to}/examples/dojo/*/ arvo/`
32+Make sure you've mounted your `%home` desk:
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+```
3444
3545Run an example to ensure it worked:
3646
@@ -213,8 +223,8 @@ of the code. However, `b` is not an argument; `=|` sets `b` to the
213223default value of whatever type it is declared as. Since the default
214224value of an atom is `0`, b is set to `0`.
215225
216−> To produce the default value of any given type, use `$*` ('buctar')
217−> followed by the type. Alternatively, use the irregular form `*`.
226+> To produce the default value of any given type, use `*` ('tar')
227+> followed by the type. This operaction is called *bunt*.
218228>
219229> > *@ :: produce the default value of atom @
220230> 0
docs/arvo/generators.md+20−24
@@ -65,13 +65,11 @@ optionally specify the message as well.
6565We'll need a new mark for our arguments. Let's call it
6666`examples-ping-message`.
6767
68−<blockquote class="blockquote">
69−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
71−several such marks, subdirectories in `/mar` are rendered as
72−`-`, so that `ping-message` is written in
73−(/mar/examples/ping/message.hoon).
74−</blockquote>
68+> For app-specific marks, it's good style to prefix the name of
69+> the mark with the name of the app. Since many apps have
70+> several such marks, subdirectories in `/mar` are rendered as
71+> `-`, so that `ping-message` is written in
72+> (/mar/examples/ping/message.hoon).
7573
7674```
7775:: Up-ness monitor. Accepts atom url, 'on', or 'off'
@@ -214,23 +212,21 @@ text and null.
214212Secondly, `?~(a b c)` is a rune which means "if the `a` is null,
215213do `b`, else `c`". It is roughly equivalent to `?:(=(~ a) b c)`.
216214
217−<blockquote class="blockquote">
218−`?~(a b c)` is actually equivalent to `?:=(?=(~ a) b c)`,
219−which, although identical at run time, is subtly different at
220−compile time. Specifically, using `?=` rather than `=` means
221−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
223−`c` case `a` is not null. Since `=` is purely a runtime value
224−check with no type implications, the compiler doesn't gain any
225−information.
226−
227−At any rate, this is the reason why we can refer to
228−`text.message` in the `c` clause. The compiler knows that
229−`message` is not null, so it must have `text` within it. If
230−you used `?:(=(~ message) 'howdy' text.message)` the compiler
231−would complain that it doesn't know whether `message` has
232−`text` within it.
233−</blockquote>
215+> `?~(a b c)` is actually equivalent to `?:=(?=(~ a) b c)`,
216+> which, although identical at run time, is subtly different at
217+> compile time. Specifically, using `?=` rather than `=` means
218+> that we're checking whether `a` is in the *type* of `~`, and so
219+> the compiler knows that in the `b` case `a` is null, and in the
220+> `c` case `a` is not null. Since `=` is purely a runtime value
221+> check with no type implications, the compiler doesn't gain any
222+> information.
223+>
224+> At any rate, this is the reason why we can refer to
225+> `text.message` in the `c` clause. The compiler knows that
226+> `message` is not null, so it must have `text` within it. If
227+> you used `?:(=(~ message) 'howdy' text.message)` the compiler
228+> would complain that it doesn't know whether `message` has
229+> `text` within it.
234230
235231This is run as follows:
236232
docs/arvo/http.md+19−29
@@ -77,12 +77,10 @@ line, though.
7777Firstly, there's two kinds of cards we're sending to arvo. A
7878`%them` card makes an HTTP requrest out of a unit `hiss`.
7979
80−<blockquote class="blockquote">
81−Recall that `++unit` means "maybe". Formally, "`(unit a)` is
82−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
84−verify that the unit is not null (for example with `?~`).
85−</blockquote>
80+> Recall that `++unit` means "maybe". Formally, "`(unit a)` is
81+> either null or a pair of null and a value in `a`". Also recall
82+> that to pull a value out of a unit `(u.unit)`, you must first
83+> verify that the unit is not null (for example with `?~`).
8684
8785A `hiss` (all of the following terms are defined in `zuse`) is a
8886pair 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
9694representing the body. If it's null, then no body is sent (as in
9795this case).
9896
99−<blockquote class="blockquote">
100−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
102−turns it into an octet strem.
103−</blockquote>
97+> An octect stream is a pair of the length in bytes of the data
98+> plus the data itself. You can use `++taco` takes text and
99+> turns it into an octet strem.
104100
105101When you send this request, you can expect a `%thou` with the
106102response, which we handle later on in `++thou-request`.
@@ -108,11 +104,9 @@ response, which we handle later on in `++thou-request`.
108104For `%wait`, you just pass a [`@da`]() (absolute date), and arvo will
109105produce a `%wake` when the time comes.
110106
111−<blockquote class="blockquote">
112−A timer is guaranteed to not be triggered before the given
113−time, but it's currently impossible to guarantee the timer will be
114−triggered at exactly the requested time.
115−</blockquote>
107+> A timer is guaranteed to not be triggered before the given
108+> time, but it's currently impossible to guarantee the timer will be
109+> triggered at exactly the requested time.
116110
117111Let's take a look at our state:
118112
@@ -133,11 +127,9 @@ of `value`, but make the default value be `value`". Thus, our
133127type is still a boolean, just like `?`, but the default value is
134128`|` (false).
135129
136−<blockquote class="blockquote">
137−This is the same `_` used in `_+>.$`, which means "the same
138−type as the value "+>.$". In other words, the same type as our
139−current context and state.
140−</blockquote>
130+> This is the same `_` used in `_+>.$`, which means "the same
131+> type as the value "+>.$". In other words, the same type as our
132+> current context and state.
141133
142134Let's take a look at `++poke-cord`. When we're poked with a
143135cord, 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
151143target))` is the parsed url, `%get` is the HTTP method, `~`
152144means no extra headers, and another `~` means no body.
153145
154−<blockquote class="blockquote">
155−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
157−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]`.
159−These may be mixed and matched to create various convoluted
160−structures and emojis.
161−</blockquote>
146+> Note the `~` at the end of the move. This is a convenient
147+> shortcut for creating a list of a single element. It's part of
148+> a small family of such shortcuts. `~[a b c]` is `[a b c ~]`,
149+> `[a b c]~` is `[[a b c] ~]` and `\`[a b c]` is `[~ a b c]`.
150+> These may be mixed and matched to create various convoluted
151+> structures and emojis.
162152
163153If the argument is neither 'off' nor 'on', then we assume it's an
164154actual 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
3434the app, then you can poke it from the command line with the following
3535commands:
3636
37− ~fintud-macrep:dojo> |start %echo
37+ ~fintud-macrep:dojo> |start %examples-echo
38+ 'prep'
3839 >=
3940 ~fintud-macrep:dojo> :examples-echo 5
4041 [%argument 5]
@@ -169,7 +170,7 @@ Run it with these commands:
169170
170171 ~fintud-macrep:dojo> |start %examples-pong
171172 >=
172− ~fintud-macrep:dojo> :pong &examples-urbit ~sampel-sipnym
173+ ~fintud-macrep:dojo> :examples-pong &urbit ~sampel-sipnym
173174 >=
174175
175176Replace `~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.
220221If you look up `++bone` in `hoon.hoon`, you'll see that it's a number
221222(`@ud`), and that it's an opaque reference to a duct. `++duct` in
222223hoon.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
224225list of paths, and a bone is an opaque reference to it (in the same way
225226that a Unix file descriptor is an opaque reference to a file structure).
226227Thus, 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
283284different data. In our case, a `%poke` move takes a target (urbit and
284285app) and marked data, then pokes the arm of the corresponding mark on
285286that 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.
287288
288289When arvo receives a `%poke` move, it calls the appropriate `++poke`.
289290The 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.
312313 the end, you should be able to watch Collatz's conjecture play out
313314 between the two apps. Sample output:
314315
315−<!-- -->
316−
317− ~fintud-macrep:dojo> :even &atom 18
318− [%even 18]
319− [%odd 9]
320− [%even 28]
321− [%even 14]
322− [%odd 7]
323− [%even 22]
324− [%odd 11]
325− [%even 34]
326− [%odd 17]
327− [%even 52]
328− [%even 26]
329− [%odd 13]
330− [%even 40]
331− [%even 20]
332− [%even 10]
333− [%odd 5]
334− [%even 16]
335− [%even 8]
336− [%even 4]
337− [%even 2]
338− %success
316+```
317+~fintud-macrep:dojo> :even &atom 18
318+[%even 18]
319+[%odd 9]
320+[%even 28]
321+[%even 14]
322+[%odd 7]
323+[%even 22]
324+[%odd 11]
325+[%even 34]
326+[%odd 17]
327+[%even 52]
328+[%even 26]
329+[%odd 13]
330+[%even 40]
331+[%even 20]
332+[%even 10]
333+[%odd 5]
334+[%even 16]
335+[%even 8]
336+[%even 4]
337+[%even 2]
338+%success
339+```
339340
340341- Put `even` and `odd` on two separate urbits and pass the messages
341342 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.
9999- Write an app that prints out the previous value you poked it with.
100100 Sample output:
101101
102−\`\`\` \~fintud-macrep:dojo\> :examples-last 7 [%last 0] \>=
103−\~fintud-macrep:dojo\> :examples-last [1 2 3][%last 7] \>=
104−\~fintud-macrep:dojo\> :examples-last 'howdy' [%last [1 2 3]]
102+```
103+~fintud-macrep:dojo> :examples-last 7
104+[%last 0]
105+>=
106+~fintud-macrep:dojo> :examples-last [1 2 3]
107+[%last 7]
108+>=
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
3636"subject".
3737
3838 ::::::::::::::::::::::::::::::
39− =< (sum [1.000 2.000]) :: formula
39+ =< (sum [1.000 2.000]) :: formula
4040 ::::::::::::::::::::::::::::::
4141 |% ::
4242 ++ three ::
@@ -58,8 +58,8 @@ Hoon, we call the code executed the "formula" and its context the
5858 (add b $(b (add b 5))) ::
5959 ::
6060 ++ sum ::
61− |= a/@u ::
62− (add (five a) (three a)) ::
61+ |= {a/@u b/@u} ::
62+ (add (five a) (three b)) ::
6363 -- ::
6464 ::::::::::::::::::::::::::::::
6565
docs/arvo/web-apps.md+1−1
@@ -145,7 +145,7 @@ the app from the command line.
145145 `:click` and print out the subscription updates on the command
146146 line.
147147
148−#Frontend
148+# Frontend
149149
150150That's all that's needed for the back end. The front end is just
151151some "sail" html (Hoon markup for XML) and javascript. Here's `/web/click.hoon`: