@@ -1,6 +1,6 @@
4title: Using Generators with Apps
4title: Using Generators with Apps
@@ -12,7 +12,7 @@ the "plumbing" way to interact with apps. Generators are the
12`|merge`, there are no marks in sight.
12`|merge`, there are no marks in sight.
14We've used generators before, back in [Basic
14We've used generators before, back in [Basic
15−Operation](basic). At that point, we just used the generators
15+Operation](http://urbit.org/docs/user/basic). At that point, we just used the generators
16to produce values -- we didn't pipe their results into apps. In
16to produce values -- we didn't pipe their results into apps. In
17the dojo cast, the role of a generator is to take a list of
17the dojo cast, the role of a generator is to take a list of
18arguments and produce a value, which is often, though not always,
18arguments and produce a value, which is often, though not always,
@@ -52,10 +52,8 @@ abbreviated to `:my-app|my-generator <args>`. Because most
52built-in commands are generators for the `:hood` app,
52built-in commands are generators for the `:hood` app,
53`:hood|generator <args>` can be shortened to `|generator <args>`.
53`:hood|generator <args>` can be shortened to `|generator <args>`.
55−XXThe paragraph above is too long and confusing
57Let's write a generator for a modified version of `:pong` from
55Let's write a generator for a modified version of `:pong` from
58−the chapter on [Network Messages](network). Recall that `:pong`
56+the chapter on [Network Messages](http://urbit.org/docs/user/network). Recall that `:pong`
59takes an urbit address, which is of mark `urbit`, and sends that
57takes an urbit address, which is of mark `urbit`, and sends that
60urbit the message `'howdy'`. First--without a generator--let's
58urbit the message `'howdy'`. First--without a generator--let's
61make `:ping` that does the same, except that it lets the user
59make `:ping` that does the same, except that it lets the user
@@ -64,44 +62,117 @@ optionally specify the message as well.
64We'll need a new mark for our arguments. Let's call it
62We'll need a new mark for our arguments. Let's call it
65`ping-message`.
63`ping-message`.
65+<blockquote class="blockquote">
67−> For app-specific marks, it's good style to prefix the name of
66+For app-specific marks, it's good style to prefix the name of
68−> the mark with the name of the app. Since many apps have
67+the mark with the name of the app. Since many apps have
69−> several such marks, subdirectories in `/mar` are rendered as
68+several such marks, subdirectories in `/mar` are rendered as
70−> `-`, so that `ping-message` is written in
69+`-`, so that `ping-message` is written in
71−> (`/mar/ping/message.hoon`).
70+(`/mar/ping/message.hoon`).
74−|_ [to=@p message=@t]
74+:: Up-ness monitor. Accepts atom url, 'on', or 'off'
76+:::: /hoon/up/examples/app
77− ++ noun ,[@p @t]
80+++ move {bone card}
82+ $% {$hiss wire $~ $httr {$purl p/purl}}
86+ $% {$on $~} :: enable polling('on')
87+ {$off $~} :: disable polling('off)
88+ {$target p/cord} :: set poll target('http://...')
91+|_ {hid/bowl on/_| in-progress/_| target/@t}
93+ |= url-or-command/@t ^- (quip move +>)
95+ ?: ?=($on url-or-command) [%on ~]
96+ ?: ?=($off url-or-command) [%off ~]
97+ [%target url-or-command]
99+ $target [~ +>.$(target p.act)]
102+ :- ?: |(on in-progress) ~
103+ [ost.hid %hiss /request ~ %httr %purl (need (epur target))]~
104+ +>.$(on &, in-progress &)
109+:: ^- {(list move) _+>.$}
113+:: :_ +>.$(on &, in-progress &)
114+:: ?: |(on in-progress)
116+:: [ost.hid %them /request ~ (need (epur target)) %get ~ ~]~
117+:: [~ +>.$(target url)]
119+ |= {wir/wire code/@ud headers/mess body/(unit octs)}
121+ ^- {(list move) _+>.$}
122+ ?: &((gte code 200) (lth code 300))
123+ ~& [%all-is-well code]
125+ [ost.hid %wait /timer (add ~s10 now.hid)]~
126+ ~& [%we-have-a-problem code]
127+ ~& [%headers headers]
130+ [ost.hid %wait /timer (add ~s10 now.hid)]~
132+ |= {wir/wire $~} ^- (quip move +>)
135+ [ost.hid %hiss /request ~ %httr %purl (need (epur target))]~
136+ [~ +>.$(in-progress |)]
138+++ prep ~& target _`. ::
82−The app can easily be modified to use this (`/ape/ping.hoon`):
142+The app can easily be modified to use this (`/app/ping.hoon`):
146+:::: /hoon/ping/examples/app
87− ++ move ,[bone term wire *]
150+ ++ move {bone term wire *}
90−|_ [bowl state=~]
153+|_ {bowl state/$~}
92−++ poke-ping-message
155+++ poke-examples-ping-message
93− |= [to=@p message=@t]
156+ |= {to/@p message/@t}
94− ^- [(list move) _+>.$]
158+ ^- {(list move) _+>.$}
95− [[[ost %poke /sending [to dap] %atom message] ~] +>.$]
160+ :~ `move`[ost %poke /sending [to dap] %atom message]
97++ poke-atom
164++ poke-atom
98− |= arg=@
165+ |= arg/@
99− ^- [(list move) _+>.$]
167+ ^- {(list move) _+>.$}
100− ~& [%receiving (,@t arg)]
169+ ~& [%receiving (@t arg)]
103++ coup |=(* `+>)
172++ coup |=(* `+>)
107Now we can run this with:
178Now we can run this with:
@@ -123,11 +194,11 @@ to `:ping`, let's put it in `/gen/ping/send.hoon`:
126−|= [^ [[to=@p message=?(~ [text=@t ~])] ~]]
197+|= {^ {{to/@p message/?($~ {text/@t $~})} $~}
127[%ping-message to ?~(message 'howdy' text.message)]
198[%ping-message to ?~(message 'howdy' text.message)]
130−A couple of new things here. Firstly, `message=?(~ [text=@t ~])`
201+A couple of new things here. Firstly, `message/?($~ {text=@t $~})`
131should be read as "the message is either null or a pair of text
202should be read as "the message is either null or a pair of text
132and null". Generator argument lists are always null-terminated,
203and null". Generator argument lists are always null-terminated,
133which makes it convenient to accept lists in tail position (which
204which makes it convenient to accept lists in tail position (which
@@ -140,21 +211,23 @@ text and null.
140Secondly, `?~(a b c)` is a rune which means "if the `a` is null,
211Secondly, `?~(a b c)` is a rune which means "if the `a` is null,
141do `b`, else `c`". It is roughly equivalent to `?:(=(~ a) b c)`.
212do `b`, else `c`". It is roughly equivalent to `?:(=(~ a) b c)`.
214+<blockquote class="blockquote">
143−> `?~(a b c)` is actually equivalent to `?:=(?=(~ a) b c)`,
215+`?~(a b c)` is actually equivalent to `?:=(?=(~ a) b c)`,
144−> which, although identical at run time, is subtly different at
216+which, although identical at run time, is subtly different at
145−> compile time. Specifically, using `?=` rather than `=` means
217+compile time. Specifically, using `?=` rather than `=` means
146−> 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
147−> 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
148−> `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
149−> check with no type implications, the compiler doesn't gain any
221+check with no type implications, the compiler doesn't gain any
150−> information.
222+information.
152−> 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
153−> `text.message` in the `c` clause. The compiler knows that
225+`text.message` in the `c` clause. The compiler knows that
154−> `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
155−> you used `?:(=(~ message) 'howdy' text.message)` the compiler
227+you used `?:(=(~ message) 'howdy' text.message)` the compiler
156−> would complain that it doesn't know whether `message` has
228+would complain that it doesn't know whether `message` has
157−> `text` within it.
229+`text` within it.
159This is run as follows:
232This is run as follows: