@@ -23,7 +23,7 @@ code isn't 2xx. Here's `app/up.hoon`:
2323|%
2424++ move {bone card}
2525++ card
26− $% {$hiss wire $~ $httr {$purl p/purl}}
26+ $% {$hiss wire unit-iden/$~ mark/$httr cage/{mark/$purl vase/purl}}
2727 {$wait wire @da}
2828 ==
2929++ action
@@ -33,7 +33,7 @@ code isn't 2xx. Here's `app/up.hoon`:
3333 ==
3434--
3535|_ {hid/bowl on/_| in-progress/_| target/@t}
36−++ poke-cord
36+++ poke-atom
3737 |= url-or-command/@t ^- (quip move +>)
3838 =+ ^- act/action
3939 ?: ?=($on url-or-command) [%on ~]
@@ -67,39 +67,41 @@ code isn't 2xx. Here's `app/up.hoon`:
6767 [ost.hid %hiss /request ~ %httr %purl (need (epur target))]~
6868 [~ +>.$(in-progress |)]
6969::
70−++ prep ~& target _`. ::
71−--
70+++ prep ~& target _`. :: computed when the source file changes;
71+-- :: here it prints target then resets our state
7272```
7373
7474There's some fancy stuff going on here. We'll go through it line by
7575line, though.
7676
77−Firstly, there's two kinds of cards we're sending to arvo. A
78−`%them` card makes an HTTP requrest out of a unit `hiss`.
77+There's two kinds of cards we're sending to arvo. A `%hiss` move tells
78+`%eyre` to make an HTTP request. It expects a `(unit iden)`, which will
79+be null here because we aren't doing any authentication; a mark, in this
80+case the http request mark `&httr`; and some data in the form of a
81+`cage`, which is a `{mark vase}`. This is confusing, so the mold in the
82+code quoted above includes a bunch of otherwise unnecessary faces for
83+the purpose of illustration. Compare: `{$hiss p/(unit iden) q/mark
84+r/cage}` from `zuse`.
85+
86+> You can grep zuse.hoon and arvo.hoon for most of these definitions.
87+> However, beware the ambiguity surrounding "hiss": there's ++hiss in
88+> section 3bI of `zuse` ("Arvo structures"), and there's `%hiss` the
89+> move that is sent to %eyre to make our HTTP request happen. Here we're
90+> talking about the latter. See `++kiss-eyre` in `zuse`.
7991
8092> Recall that `++unit` means "maybe". Formally, "`(unit a)` is
8193> 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 `?~`).
94+> that to pull a value out of a unit (`u.unit`), you must first
95+> verify that the unit is not null (for example with `?~`). See
96+> `++need`.
8497
85−A `hiss` (all of the following terms are defined in `zuse`) is a
86−pair of a `purl` and a `moth`. A `purl` is a parsed url
87−structure, which can be created with `++epur`, which is a
88−function that takes a url as text and parses it into a `(unit
98+A `purl` is a parsed url structure, which can be created with `++epur`,
99+which is a function that takes a url as text and parses it into a `(unit
89100purl)`. Thus, the result is null if and only if the url is malformed.
101+'Purl' is also the mark which will be applied to this result.
90102
91−A `moth` is a treble of a `meth`, a `math`, and `(unit octs)`.
92−`meth` is the HTTP method, in this case `%get`. `math` is a map
93−of HTTP headers. The `(unit octs)` is a possible octet stream
94−representing the body. If it's null, then no body is sent (as in
95−this case).
96−
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.
100−
101−When you send this request, you can expect a `%thou` with the
102−response, which we handle later on in `++thou-request`.
103+When you send this request, you can expect a `%sigh` with the
104+response, which we handle later on in `++sigh-httr`.
103105
104106For `%wait`, you just pass a [`@da`]() (absolute date), and arvo will
105107produce a `%wake` when the time comes.
@@ -131,30 +133,45 @@ type is still a boolean, just like `?`, but the default value is
131133> type as the value "+>.$". In other words, the same type as our
132134> current context and state.
133135
134−Let's take a look at `++poke-cord`. When we're poked with a
135−cord, we first check whether it's `'off'`. If so, we set `on` to
136−false.
137−
138−If not, we check whether it's `on`. If so, we set `on` and
139−`in-progress` to true. If it was already either on or in
140−progress, then we don't take any other immediate action. If it
141−was both off and not in progress, then we send an HTTP request.
142−This request follows the pattern in `++hiss` well. `(need (epur
143−target))` is the parsed url, `%get` is the HTTP method, `~`
144−means no extra headers, and another `~` means no body.
145−
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.
136+Let's take a look at `++poke-atom`. When we're poked with an atom, we
137+first check whether the atom is `'off'`. If so, we set our state
138+variable `on` to false.
139+
140+If not, we check whether the atom is `'on'`. If so, we set `on` and
141+`in-progress` to true. If it was already either on or in progress, then
142+we don't take any other immediate action. If it was both off and not in
143+progress, then we send an HTTP request.
152144
153145If the argument is neither 'off' nor 'on', then we assume it's an
154146actual url, so we save it in `target`.
155147
148+Here's the move that sends the HTTP request:
149+```
150+[ost.hid %hiss /request ~ %httr %purl (need (epur target))]
151+```
152+
153+> Remember, we are expected to produce a *list* of moves. Note the `~`
154+> after the move in the full example. This is a convenient shortcut for
155+> creating a list of a single element. It's part of a small family of
156+> such shortcuts. `~[a b c]` is `[a b c ~]`, `[a b c]~` is `[[a b c]
157+> ~]` and `\`[a b c]` is `[~ a b c]`. These may be mixed and matched to
158+> create various convoluted structures and emojis.
159+
160+The correspondence between this move and `{bone card}` can be hard to
161+visualize on one line. Here it is more pedantically:
162+
163+```
164+:* bone=ost.hid :: the move
165+ term=%hiss
166+ wire=/request
167+ unit-iden=~
168+ mark=%httr
169+ cage=[%purl (need (epur target))]
170+==
171+```
172+
156173When the HTTP response comes back, we handle it with
157−`++thou-request`, which, along with the wire the request was sent
174+`++sigh-httr`, which, along with the wire the request was sent
158175on, takes the status code, the response headers, and the response
159176body.
160177
@@ -175,14 +192,14 @@ Let's try it out:
175192```
176193~fintud-macrep:dojo> |start %up
177194>=
178−~fintud-macrep:dojo> :examples-up &cord 'http://www.google.com'
195+~fintud-macrep:dojo> :examples-up &atom 'http://www.google.com'
179196>=
180197[%all-is-well 200]
181198[%all-is-well 200]
182−~fintud-macrep:dojo> :examples-up &cord 'http://example.com'
199+~fintud-macrep:dojo> :examples-up &atom 'http://example.com'
183200>=
184201[%all-is-well 200]
185−~fintud-macrep:dojo> :examples-up &cord 'http://google.com'
202+~fintud-macrep:dojo> :examples-up &atom 'http://google.com'
186203>=
187204[%we-have-a-problem 301]
188205[ %headers
@@ -209,5 +226,5 @@ Let's try it out:
209226 ]
210227 ]
211228]
212−~fintud-macrep:dojo> :up &cord 'off'
229+~fintud-macrep:dojo> :up &atom 'off'
213230```