@@ -12,39 +12,43 @@ planets to talk to each other.
13All we've written up until now are just shell commands that produce a value and
13All we've written up until now are just shell commands that produce a value and
14then disappear. To listen for and receive messages from other planets, we'll
14then 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`:
17 :: Accepts any noun from dojo and prints it out
17 :: Accepts any noun from dojo and prints it out
19− :::: /hoon/echo/examples/app
19+ :::: /===/app/echo/hoon
21− /? 314
21+ !: :: enables debug printfs
22− !:
22+ |% :: forms a core with subject as payload
23− |_ {bowl state/$~}
23+ ++ move {bone card} :: defines echo app's arvo move mold
24− ++ poke-noun
24+ ++ card $% $~ :: defines card (data) mold as null tagged union
25− |= arg/*
25+ == :: end of mold definition; see $%
26− ^- {(list) _+>.$}
26+ -- :: end of card arm definition
27− ~& [%argument arg]
27+ :: ::
28− [~ +>.$]
28+ |_ {bow/bowl $~} :: forms a core with bowl (app state) as sample
29− --
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
31This is a very simple app that does only one thing. If you poke it with a value,
36This is a very simple app that does only one thing. If you poke it with a value,
32it prints that value out. To try this out, you have to start the app, then you
37it prints that value out. To try this out, you have to start the app, then you
33can poke it from the command line with the following commands:
38can poke it from the command line with the following commands:
35− ~fintud-macrep:dojo> |start %examples-echo
40+ ~fintud-macrep:dojo> |start %echo
38− ~fintud-macrep:dojo> :examples-echo 5
42+ ~fintud-macrep:dojo> :echo 5
39− [%argument 5]
43+ [%echo %noun 5]
41 ~fintud-macrep:dojo> :examples-echo [1 2]
45 ~fintud-macrep:dojo> :examples-echo [1 2]
42− [%argument [1 2]]
46+ [%echo %noun [1 2]]
45−> There is currently a bug where the `%argument` lines are printed *above* the
49+> There is currently a bug where the `[%echo %noun *]` lines are printed *above*
46−> line you entered, so your output may not look exactly like this. `>=` means
50+> the line you entered, so your output may not look exactly like this. `>=`
47−> that a command was successfully received and executed.
51+> means that a command was successfully received and executed.
49Most of the app code should be simple enough to guess its function. The
53Most of the app code should be simple enough to guess its function. The
50important part of this code is the definition of `++poke-noun`.
54important 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
54from the command line, which we we did with `:echo 5`
58from the command line, which we we did with `:echo 5`
55(`:[app-name] [argument(s)]`).
59(`:[app-name] [argument(s)]`).
57−In this case, `++poke-noun` takes an argument `arg` and prints it out with `~&`
61+In this case, `++poke-noun` takes an argument (*sample*) `arg` and
58−([sigpam](../../hoon/twig/sig-hint/pam-dump/)). This is an unusual rune that
62+prints it to dojo with `~&` ([sigpam](../../hoon/twig/sig-hint/pam-dump/)).
59−formally "does nothing", but the interpreter detects it and printfs the first
63+This is an unusual rune that formally "does nothing", but the interpreter
60−child, before executing the second as if the first didn't exist. This is a
64+detects it and printfs the first child, before executing the second as if the
61−slightly hacky way of printing to the console, but we'll get to the correct way
65+first didn't exist. This is a slightly hacky way of printing to the console,
62−later on.
66+but we'll get to the correct way later on.
64But what does `++poke-noun` produce? Recall that `^-` casts to a type. In this
68But 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
69+case, it's declaring that the end result (*product*) of the function
66−`{(list) _+>.$}`. But what does this mean?
70+(`++poke-noun`'s *gate*) will be of type `{(list) _+>.$}`. But what does this
68The phrase to remember is "a list of moves and our state". Urbit is a message
73The phrase to remember is "a list of moves and our state". Urbit is a message
69passing system, so whenever we want to do something that interacts with the rest
74passing 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
81reflect the code below). Say we want to only accept a number, and then print out
86reflect the code below). Say we want to only accept a number, and then print out
82the square of that number.
87the square of that number.
84− /? 314
89+ :: Accepts any atom from dojo and prints its square
91+ :::: /===/app/echo/hoon
88 ++ poke-atom
101 ++ poke-atom
89− |= arg/@
102+ |= atm/@
90− ^- {(list) _+>.$}
103+ ^- {(list move) _+>.$}
91− ~& [%square (mul arg arg)]
104+ ~& [%square atm (mul atm atm)]
92− [~ +>.$]
105+ [~ +>.$]
95A few things have changed. Firstly, we no longer accept arbitrary nouns because
108A few things have changed. Firstly, we no longer accept arbitrary nouns because
96we can only square atoms (integers, in this case an unsigned one). Thus, our
109we 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)]`).
99# Intro to marks
115# Intro to marks