@@ -23,7 +23,7 @@ code isn't 2xx. Here's `app/up.hoon`:
24++ move {bone card}
24++ move {bone card}
26− $% {$hiss wire $~ $httr {$purl p/purl}}
26+ $% {$hiss wire unit-iden/$~ mark/$httr cage/{mark/$purl vase/purl}}
27 {$wait wire @da}
27 {$wait wire @da}
@@ -33,7 +33,7 @@ code isn't 2xx. Here's `app/up.hoon`:
35|_ {hid/bowl on/_| in-progress/_| target/@t}
35|_ {hid/bowl on/_| in-progress/_| target/@t}
36−++ poke-cord
36+++ poke-atom
37 |= url-or-command/@t ^- (quip move +>)
37 |= url-or-command/@t ^- (quip move +>)
38 =+ ^- act/action
38 =+ ^- act/action
39 ?: ?=($on url-or-command) [%on ~]
39 ?: ?=($on url-or-command) [%on ~]
@@ -67,39 +67,41 @@ code isn't 2xx. Here's `app/up.hoon`:
67 [ost.hid %hiss /request ~ %httr %purl (need (epur target))]~
67 [ost.hid %hiss /request ~ %httr %purl (need (epur target))]~
68 [~ +>.$(in-progress |)]
68 [~ +>.$(in-progress |)]
70−++ prep ~& target _`. ::
70+++ prep ~& target _`. :: computed when the source file changes;
71−--
71+-- :: here it prints target then resets our state
74There's some fancy stuff going on here. We'll go through it line by
74There's some fancy stuff going on here. We'll go through it line by
75line, though.
75line, though.
77−Firstly, there's two kinds of cards we're sending to arvo. A
77+There's two kinds of cards we're sending to arvo. A `%hiss` move tells
78−`%them` card makes an HTTP requrest out of a unit `hiss`.
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
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`.
80> Recall that `++unit` means "maybe". Formally, "`(unit a)` is
92> Recall that `++unit` means "maybe". Formally, "`(unit a)` is
81> either null or a pair of null and a value in `a`". Also recall
93> 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
94+> 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 `?~`).
95+> verify that the unit is not null (for example with `?~`). See
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
98+A `purl` is a parsed url structure, which can be created with `++epur`,
88−function that takes a url as text and parses it into a `(unit
99+which is a function that takes a url as text and parses it into a `(unit
89purl)`. Thus, the result is null if and only if the url is malformed.
100purl)`. 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.
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
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.
101−When you send this request, you can expect a `%thou` with the
103+When you send this request, you can expect a `%sigh` with the
102−response, which we handle later on in `++thou-request`.
104+response, which we handle later on in `++sigh-httr`.
104For `%wait`, you just pass a [`@da`]() (absolute date), and arvo will
106For `%wait`, you just pass a [`@da`]() (absolute date), and arvo will
105produce a `%wake` when the time comes.
107produce a `%wake` when the time comes.
@@ -131,30 +133,45 @@ type is still a boolean, just like `?`, but the default value is
131> type as the value "+>.$". In other words, the same type as our
133> type as the value "+>.$". In other words, the same type as our
132> current context and state.
134> current context and state.
134−Let's take a look at `++poke-cord`. When we're poked with a
136+Let's take a look at `++poke-atom`. When we're poked with an atom, we
135−cord, we first check whether it's `'off'`. If so, we set `on` to
137+first check whether the atom is `'off'`. If so, we set our state
136−false.
138+variable `on` to false.
138−If not, we check whether it's `on`. If so, we set `on` and
140+If not, we check whether the atom is `'on'`. If so, we set `on` and
139−`in-progress` to true. If it was already either on or in
141+`in-progress` to true. If it was already either on or in progress, then
140−progress, then we don't take any other immediate action. If it
142+we don't take any other immediate action. If it was both off and not in
141−was both off and not in progress, then we send an HTTP request.
143+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.
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.
153If the argument is neither 'off' nor 'on', then we assume it's an
145If the argument is neither 'off' nor 'on', then we assume it's an
154actual url, so we save it in `target`.
146actual url, so we save it in `target`.
148+Here's the move that sends the HTTP request:
150+[ost.hid %hiss /request ~ %httr %purl (need (epur target))]
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.
160+The correspondence between this move and `{bone card}` can be hard to
161+visualize on one line. Here it is more pedantically:
164+:* bone=ost.hid :: the move
169+ cage=[%purl (need (epur target))]
156When the HTTP response comes back, we handle it with
173When 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
158on, takes the status code, the response headers, and the response
175on, takes the status code, the response headers, and the response
@@ -175,14 +192,14 @@ Let's try it out:
176~fintud-macrep:dojo> |start %up
193~fintud-macrep:dojo> |start %up
178−~fintud-macrep:dojo> :examples-up &cord 'http://www.google.com'
195+~fintud-macrep:dojo> :examples-up &atom 'http://www.google.com'
180[%all-is-well 200]
197[%all-is-well 200]
181[%all-is-well 200]
198[%all-is-well 200]
182−~fintud-macrep:dojo> :examples-up &cord 'http://example.com'
199+~fintud-macrep:dojo> :examples-up &atom 'http://example.com'
184[%all-is-well 200]
201[%all-is-well 200]
185−~fintud-macrep:dojo> :examples-up &cord 'http://google.com'
202+~fintud-macrep:dojo> :examples-up &atom 'http://google.com'
187[%we-have-a-problem 301]
204[%we-have-a-problem 301]
188[ %headers
205[ %headers
@@ -209,5 +226,5 @@ Let's try it out:
212−~fintud-macrep:dojo> :up &cord 'off'
229+~fintud-macrep:dojo> :up &atom 'off'