@@ -12,39 +12,43 @@ planets to talk to each other.
1212
1313All we've written up until now are just shell commands that produce a value and
1414then disappear. To listen for and receive messages from other planets, we'll
15−need an app. Let's look at a very simple one:
15+need an app. Let's look at a very simple one, `echo.hoon`:
1616
1717 :: Accepts any noun from dojo and prints it out
1818 ::
19− :::: /hoon/echo/examples/app
19+ :::: /===/app/echo/hoon
2020 ::
21− /? 314
22− !:
23− |_ {bowl state/$~}
24− ++ poke-noun
25− |= arg/*
26− ^- {(list) _+>.$}
27− ~& [%argument arg]
28− [~ +>.$]
29− --
21+ !: :: enables debug printfs
22+ |% :: forms a core with subject as payload
23+ ++ move {bone card} :: defines echo app's arvo move mold
24+ ++ card $% $~ :: defines card (data) mold as null tagged union
25+ == :: end of mold definition; see $%
26+ -- :: end of card arm definition
27+ :: ::
28+ |_ {bow/bowl $~} :: forms a core with bowl (app state) as sample
29+ ++ poke-noun :: begin definition of poke-noun arm
30+ |= non/* :: forms a gate which accepts any noun
31+ ^- {(list move) _+>.$} :: casts product to mold of moves and context
32+ ~& echo+noun+non :: debug printf, i.e. '[%echo %noun *]'
33+ [~ +>.$] :: produce a cell of empty list and our state
34+ -- :: end of poke-noun arm definition
3035
3136This is a very simple app that does only one thing. If you poke it with a value,
3237it prints that value out. To try this out, you have to start the app, then you
3338can poke it from the command line with the following commands:
3439
35− ~fintud-macrep:dojo> |start %examples-echo
36− 'prep'
40+ ~fintud-macrep:dojo> |start %echo
3741 >=
38− ~fintud-macrep:dojo> :examples-echo 5
39− [%argument 5]
42+ ~fintud-macrep:dojo> :echo 5
43+ [%echo %noun 5]
4044 >=
4145 ~fintud-macrep:dojo> :examples-echo [1 2]
42− [%argument [1 2]]
46+ [%echo %noun [1 2]]
4347 >=
4448
45−> There is currently a bug where the `%argument` lines are printed *above* the
46−> line you entered, so your output may not look exactly like this. `>=` means
47−> that a command was successfully received and executed.
49+> There is currently a bug where the `[%echo %noun *]` lines are printed *above*
50+> the line you entered, so your output may not look exactly like this. `>=`
51+> means that a command was successfully received and executed.
4852
4953Most of the app code should be simple enough to guess its function. The
5054important part of this code is the definition of `++poke-noun`.
@@ -54,16 +58,17 @@ it by sending it messages. The most straightforward way to do that is to poke it
5458from the command line, which we we did with `:echo 5`
5559(`:[app-name] [argument(s)]`).
5660
57−In this case, `++poke-noun` takes an argument `arg` and prints it out with `~&`
58−([sigpam](../../hoon/twig/sig-hint/pam-dump/)). This is an unusual rune that
59−formally "does nothing", but the interpreter detects it and printfs the first
60−child, before executing the second as if the first didn't exist. This is a
61−slightly hacky way of printing to the console, but we'll get to the correct way
62−later on.
61+In this case, `++poke-noun` takes an argument (*sample*) `arg` and
62+prints it to dojo with `~&` ([sigpam](../../hoon/twig/sig-hint/pam-dump/)).
63+This is an unusual rune that formally "does nothing", but the interpreter
64+detects it and printfs the first child, before executing the second as if the
65+first didn't exist. This is a slightly hacky way of printing to the console,
66+but we'll get to the correct way later on.
6367
6468But what does `++poke-noun` produce? Recall that `^-` casts to a type. In this
65−case, it's declaring that the end result of the function will be of type
66−`{(list) _+>.$}`. But what does this mean?
69+case, it's declaring that the end result (*product*) of the function
70+(`++poke-noun`'s *gate*) will be of type `{(list) _+>.$}`. But what does this
71+mean?
6772
6873The phrase to remember is "a list of moves and our state". Urbit is a message
6974passing system, so whenever we want to do something that interacts with the rest
@@ -81,20 +86,31 @@ Let's look at another example (edit your code in `/app/examples/echo/hoon` to
8186reflect the code below). Say we want to only accept a number, and then print out
8287the square of that number.
8388
84− /? 314
85− !:
86− |_ {bowl state/$~}
89+ :: Accepts any atom from dojo and prints its square
8790 ::
91+ :::: /===/app/echo/hoon
92+ ::
93+ !:
94+ |%
95+ ++ move {bone card}
96+ ++ card $% $~
97+ ==
98+ --
99+ ::
100+ |_ {bow/bowl $~}
88101 ++ poke-atom
89− |= arg/@
90− ^- {(list) _+>.$}
91− ~& [%square (mul arg arg)]
92− [~ +>.$]
93− --
102+ |= atm/@
103+ ^- {(list move) _+>.$}
104+ ~& [%square atm (mul atm atm)]
105+ [~ +>.$]
106+ --
94107
95108A few things have changed. Firstly, we no longer accept arbitrary nouns because
96109we can only square atoms (integers, in this case an unsigned one). Thus, our
97−argument is now `arg/@`. Secondly, it's `++poke-atom` rather than `++poke-noun`.
110+argument is now `atm/@`. Secondly, it's `++poke-atom` rather than `++poke-noun`.
111+Also note how the format of the sample we send to the debug printf rune `~&`
112+has moved from irregular (`echo+noun+non`) to regular
113+(`[%square atm (mul atm atm)]`).
98114
99115# Intro to marks
100116