4title: Using Generators with Apps
9Up until now we've poked apps directly. This requires the user
10to specify the mark, and it requires the app to accept the
11arguments in a way that's convenient for users to input. This is
12the "plumbing" way to interact with apps. Generators are the
13"porcelain" layer. This is why when you run a command like `+ls` or
14`|merge`, there are no marks in sight.
16We've used generators before, back in [Basic
17Operation](/docs/user/basic). At that point, we just used the generators
18to produce values -- we didn't pipe their results into apps. In
19the dojo cast, the role of a generator is to take a list of
20arguments and produce a value, which is often, though not always,
21piped into an app. Generators are pure, stateless functions, and
22they cannot send moves.
24`+ls` and `+cat` are commonly-used generators that produce a directory
25listing and print out a file, respectively. These are useful in
26themselves, so we generally don't pipe the results into an app.
28Another generator is `+hood/merge`. Try running `+hood/merge`
29with the normal arguments for `|merge`:
32~fintud-macrep:dojo> +hood/merge %home our %they
33[syd=%home her=~fintud-macrep sud=%they gem=%auto]
34~fintud-macrep:dojo> +hood/merge %home our %they, =gem %this
35[syd=%home her=~fintud-macrep sud=%they gem=%auto]
38This didn't run any merge, it just constructed the command that,
39if sent to `:hood`, would run it. Note first that, even though
40it's not printed, this value has mark `kiln-merge`. Also, the
41merge strategy `gem=%auto` was added automatically. Optional
42arguments are straightforward with generators.
44In general, generators are prepended by either `+` or `|`. The
45general form is `+generator`, but often generators are created
46specifically to work with a single app, they're usually placed in
47a subdirectory of gen and run with `|`. Thus, if `my-generator`
48generator is made for use with `:my-app`, then `my-generator` is
49put in `/gen/my-app/my-generator.hoon`, and can be run directly
50with `+my-app/my-generator <args>`. If you want to pipe the
51result into `:my-app`, then run `:my-app +my-app/my-generator
52<args>`. Because this pattern is so common, this can be
53abbreviated to `:my-app|my-generator <args>`. Because most
54built-in commands are generators for the `:hood` app,
55`:hood|generator <args>` can be shortened to `|generator <args>`.
57Let's write a generator for a modified version of `:examples-pong` from
58the chapter on [Network Messages](/docs/programming/system/network). Recall that `:examples-pong`
59takes an urbit address, which is of mark `urbit`, and sends that
60urbit the message `'howdy'`. First--without a generator--let's
61make `:examples-ping` that does the same, except that it lets the user
62optionally specify the message as well.
64We'll need a new mark for our arguments. Let's call it
65`examples-ping-message`.
67<blockquote class="blockquote">
68For app-specific marks, it's good style to prefix the name of
69the mark with the name of the app. Since many apps have
70several such marks, subdirectories in `/mar` are rendered as
71`-`, so that `ping-message` is written in
72(/mar/examples/ping/message.hoon).
76:: Up-ness monitor. Accepts atom url, 'on', or 'off'
78:::: /hoon/up/examples/app
84 $% {$hiss wire $~ $httr {$purl p/purl}}
88 $% {$on $~} :: enable polling('on')
89 {$off $~} :: disable polling('off)
90 {$target p/cord} :: set poll target('http://...')
93|_ {hid/bowl on/_| in-progress/_| target/@t}
95 |= url-or-command/@t ^- (quip move +>)
97 ?: ?=($on url-or-command) [%on ~]
98 ?: ?=($off url-or-command) [%off ~]
99 [%target url-or-command]
101 $target [~ +>.$(target p.act)]
104 :- ?: |(on in-progress) ~
105 [ost.hid %hiss /request ~ %httr %purl (need (epur target))]~
106 +>.$(on &, in-progress &)
111:: ^- {(list move) _+>.$}
115:: :_ +>.$(on &, in-progress &)
116:: ?: |(on in-progress)
118:: [ost.hid %them /request ~ (need (epur target)) %get ~ ~]~
119:: [~ +>.$(target url)]
121 |= {wir/wire code/@ud headers/mess body/(unit octs)}
123 ^- {(list move) _+>.$}
124 ?: &((gte code 200) (lth code 300))
125 ~& [%all-is-well code]
127 [ost.hid %wait /timer (add ~s10 now.hid)]~
128 ~& [%we-have-a-problem code]
129 ~& [%headers headers]
132 [ost.hid %wait /timer (add ~s10 now.hid)]~
134 |= {wir/wire $~} ^- (quip move +>)
137 [ost.hid %hiss /request ~ %httr %purl (need (epur target))]~
138 [~ +>.$(in-progress |)]
140++ prep ~& target _`. ::
144The app can easily be modified to use this (`/app/examples/ping.hoon`):
148:::: /hoon/ping/examples/app
152 ++ move {bone term wire *}
157++ poke-examples-ping-message
158 |= {to/@p message/@t}
160 ^- {(list move) _+>.$}
162 :~ `move`[ost %poke /sending [to dap] %atom message]
169 ^- {(list move) _+>.$}
171 ~& [%receiving (@t arg)]
180Now we can run this with:
183~fintud-macrep:dojo> |start %examples-ping
185~fintud-macrep:dojo> :examples-ping &examples-ping-message [~sampel-sipnym 'heyya']
189And on `~sampel-sipnym`, assuming it's running `:examples-ping` as well,
190we see `[%receiving 'heyya']`.
192This is an annoying way to invoke the app, though. The `[]` are
193mandatory, and optional arguments are hard. Let's make a
194generator, `+examples-send` to make everything nicer. Since it's specific
195to `:examples-ping`, let's put it in `/gen/examples/ping/send.hoon`:
199|= {^ {{to/@p message/?($~ {text/@t $~})} $~}
200[%examples-ping-message to ?~(message 'howdy' text.message)]
203A couple of new things here. Firstly, `message/?($~ {text/@t $~})`
204should be read as "the message is either null or a pair of text
205and null". Generator argument lists are always null-terminated,
206which makes it convenient to accept lists in tail position (which
207are particularly annoying without generators). `?(a b)` is the
208irregular form of `$?(a b)`, which is a union type. Thus, `?(a
209b)` means the type of anything that's in either `a` or `b`.
210Thus, in our case, `?(~ [text=@t ~])` is either null or a pair of
213Secondly, `?~(a b c)` is a rune which means "if the `a` is null,
214do `b`, else `c`". It is roughly equivalent to `?:(=(~ a) b c)`.
216<blockquote class="blockquote">
217`?~(a b c)` is actually equivalent to `?:=(?=(~ a) b c)`,
218which, although identical at run time, is subtly different at
219compile time. Specifically, using `?=` rather than `=` means
220that we're checking whether `a` is in the *type* of `~`, and so
221the compiler knows that in the `b` case `a` is null, and in the
222`c` case `a` is not null. Since `=` is purely a runtime value
223check with no type implications, the compiler doesn't gain any
226At any rate, this is the reason why we can refer to
227`text.message` in the `c` clause. The compiler knows that
228`message` is not null, so it must have `text` within it. If
229you used `?:(=(~ message) 'howdy' text.message)` the compiler
230would complain that it doesn't know whether `message` has
234This is run as follows:
237~fintud-macrep:dojo> :examples-ping|send ~sampel-sipnym
239~fintud-macrep:dojo> :examples-ping|send ~sampel-sipnym 'how do you do'
243Which causes `~sampel-sipnym` to print `[%receiving 'howdy']` and
244`[%receiving 'how do you do']`.
248- Create a generator for `:examples-sum` from [State](state) so that
249 you can run `:examples-sum|add 5` to add numbers to it.
251- Create a generator for `:examples-click` from [Web Apps](web-apps) so
252 that you can run `:examplesclick|poke` to poke it.
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list