@@ -7,10 +7,10 @@ title: Hoon refresher / crash course
77
88# Basic Hoon
99
10−This recapitulates material you've already learned in Core Hoon.
10+This recapitulates material you've already learned in [Hoon](/docs/hoon/).
1111It will be a very abrupt tutorial if you don't know Hoon already,
1212but it may be enough in and of itself. If you don't find it obvious at first
13−glance, read it over again.
13+glance, try working up from Hoon.
1414
1515Our goal is to get you programming interesting and useful things
1616as soon as possible. To get there, we have to quickly cover some
@@ -29,8 +29,8 @@ operation](/docs/user/basic) of your urbit.
2929
3030If you haven't copied in the examples repo, running the following commands from your urbit directory should do the trick:
3131
32−`cp -r {wherever-you've-pulled-to}/examples/gall/*/ arvo/`
33−`cp -r {wherever-you've-pulled-to}/examples/dojo/*/ arvo/`
32+`$ cp -r {wherever-you've-pulled-to}/examples/gall/*/ arvo/`
33+`$ cp -r {wherever-you've-pulled-to}/examples/dojo/*/ arvo/`
3434
3535Run an example to ensure it worked:
3636
@@ -115,10 +115,10 @@ more detail later.
115115### How to form expressions
116116
117117Hoon does not typically use reserved words to form expressions. Instead,
118−expressions are formed with runes--diagraphs of two
119−ascii symbols. Each rune takes a specific number of
120−children--either expressions formed by other runes or literals
121−that produce their own value (some runes take n children, and are usually closed with `==`).
118+expressions are formed with _runes_: digraphs of two
119+ASCII symbols. Each rune takes a specific number of
120+children, either expressions formed by other runes or literals
121+that produce their own value (some runes take _N_ children, and are usually closed with `==`).
122122
123123For example, the rune `?:` from line 17 is the classic
124124'if-then-else' statement, and thus takes three children:
@@ -131,16 +131,16 @@ Since runes are such a fundamental structure in Hoon, we found
131131ourselves speaking them out loud frequently. It quickly grew
132132cumbersome to have to say "question mark, colon" to describe
133133`?:`. To alleviate this problem, we came up with our own naming
134−scheme: each ascii glyph has a single syllable pronunciation
134+scheme: each ASCII glyph has a single-syllable pronunciation
135135phonetically designed to be both easily remembered and easily
136136pronounced in conjunction with the other glyphs (when forming a
137137rune).
138138
139−See the entire naming schema below/or link to it:
139+See the entire naming scheme below.
140140
141141```
142142 ace [1 space] gal < pel (
143− bar | gap [>1 space, nl] per )
143+ bar | gap [>1 space, \n] per )
144144 bas \ gar > sel [
145145 buc $ hax # sem ;
146146 cab _ hep - ser ]
@@ -152,9 +152,9 @@ See the entire naming schema below/or link to it:
152152 fas / pat @ zap !
153153```
154154
155−Using our naming scheme `?:` is said 'wut col'.
155+Using this scheme, we would pronounce `?:` as 'wutcol'.
156156
157−For those that would prefer to use reserved words to form expressions, you can substitute a rune's keyword--which you can find in `++twig` in `/arvo/hoon.hoon`--for the rune. For example, here's the code for `?:` in `++twig`:
157+For those who prefer to use reserved words to form expressions, you can substitute any rune with that rune's keyword, which you can find in `++twig` in `/arvo/hoon.hoon`. For example, here's the code for `?:` in `++twig`:
158158
159159`{$if p/twig q/twig r/twig} :: ?: if/then/else`
160160
@@ -174,8 +174,8 @@ if(=(1 2) 'this is true' 'this is false')
174174### Lines 12-34
175175
176176Now let's quickly walk through this code line-by-line. Lines
177−12-34 are wrapped in a `|%` (pronounced 'bar cen'), which
178−produces a core, a fundamental datatype in hoon similar to a
177+12-34 are wrapped in a `|%` ('barcen'), which produces a core.
178+Cores are a fundamental datatype in Hoon, similar to a
179179struct, class, or object. A core is just a map of names
180180to any kind of code, whether it be functions or data. Each
181181element in this map begins with a `++` followed by the name and
@@ -183,8 +183,8 @@ the corresponding code. Since `|%` takes an arbitrary number of
183183children, it needs to be closed with a `--`.
184184
185185<blockquote class="blockquote">
186−`++` is not technically a rune, since it is only used in core
187−syntax as shown above
186+`++` ('luslus') is not technically a rune, since it is only used
187+in core syntax, as shown above.
188188</blockquote>
189189
190190Let's step into each of the three arms within our core.
@@ -196,16 +196,16 @@ Let's step into each of the three arms within our core.
196196 (add (five a) (three a))
197197 --
198198
199−`|=` produces a function, much like a lambda in lisp. It takes two children:
199+`|=` ('bartis') produces a function, much like a lambda in lisp. It takes two children:
200200
201−- A set of argument(s). In this case our argument set only
202− contains one: `a`, which is required to be an atom or natural
201+1. A set of argument(s). In this case our argument set only
202+ contains one: `a`, which is required to be an atom or natural
203203 number, denoted by `@`.
204204
205−- The body of the function itself, which is executed when the
205+1. The body of the function itself, which is executed when the
206206 function is called (in this case, with `(sum 1.000)`). This
207207 particular function adds the results of evaluating the gates `++
208− five` and `++three` with each of their respective input
208+ five` and `++three` with each of their respective input
209209 parameters set to `a`.
210210
211211### ++ three
@@ -222,20 +222,34 @@ As above, `++three` takes an integer argument, `a`, and then
222222executes the remainder of the code with `a` set to the actual
223223arguments.
224224
225−Similarly, `=|` pushes its first child, `b` into our context (in
226−other words, it declares a variable `b`) and executes the
227−remainder of the code. However, `b` is not an argument; `=|`
225+Similarly, `=|` ('tisbar') pushes its first child, `b` into our
226+context (in other words, it declares a variable `b`) and executes
227+the remainder of the code. However, `b` is not an argument; `=|`
228228sets `b` to the default value of whatever type it is declared as.
229229Since the default value of an atom is `0`, b is set to `0`.
230230
231+<blockquote class="blockquote">
232+To produce the default value of any given type, use `$*` ('buctar') followed by the type.
233+Alternatively, use the irregular form `*`.
234+
235+```
236+ > *@ :: produce the default value of atom @
237+ 0
238+
239+ > *@p :: produce the phonemic base of atom @
240+ ~zod
241+
242+```
243+</blockquote>
244+
231245So now we have two variables: `a` is set to our input, and `b` is
232246initialized to `0`.
233247
234−The easiest way to think about `|-` that it lays down a recursion
248+One way to think about `|-` ('barhep') is that it lays down a recursion
235249point. More on this later.
236250
237−`^-` is just a cast that sets the result of the remainder of the
238−code to an unsigned integer, `@u`.
251+`^-` ('kethep') is just a cast that sets the result of the remainder of
252+the code to an unsigned integer, `@u`.
239253
240254In pseudocode, the last three lines read like this: if `a` is
241255less than `b`, produce zero. Else, add `b` to the result of
@@ -250,73 +264,73 @@ you recurse by an actual function call, then you have to specify
250264every argument.
251265
252266<blockquote class="blockquote">
253−If you're familiar with Clojure, `|-` is `loop` and `$()` is
254−recur.
267+If you're familiar with Clojure, `|-` is `loop` and `$()` is `recur`.
255268</blockquote>
256269
257270**Exercises**:
258271
259−Please tweak your code to complete the following excercises.
272+Tweak your code to complete the following excercises.
260273
261−There are a few runes and some syntaxes that we have yet to cover that
274+There are a few runes and some syntax that we have yet to cover that
262275you will need to complete the excercises below. For these, please
263276refer to our cheatsheat at the bottom.
264277
265−- Read and understand `++five` line by line.
278+1. Read and understand `++five` line by line.
266279
267−- Change `++sum` to accept two variables, `a` and `b`. Pass `a`
268− to three and `b` to five. Then run the code with `a` set to
269− `1.000` and ` q` set to `2.000`.
280+1. Change `++sum` to accept two variables, `a` and `b`. Pass `a`
281+ to `three` and `b` to `five`. Then run the code with `a` set to
282+ `1.000` and `q` set to `2.000`.
270283
271−- Check if this new result is under one thousand. If it is,
272− return the string 'result is less than one thousand'. If not,
273− return 'result is greater than or equal to one thousand'.
284+1. Check if this new result is under one thousand. If it is,
285+ return the string `'result < 1.000'`. If not,
286+ return `'result >= 1.000'`.
274287
275−```
276−Review
288+### Review
277289
278−|% start core (collection of named ++ arms; an "object")
279−|= define function
280−=| define variable from type with default value
281−|- drop a recursion point
282−^- cast
283−?: if-then-else
284−=(a b) test equality
285−(function args ...) call function
290+ |% ('barcen') start core (collection of named ++ arms; an "object")
291+ |= ('bartis') define function
292+ =| ('tisbar') define variable from type with default value
293+ |- ('barhep') drop a recursion point
294+ ^- ('kethep') cast
295+ ?: ('wutcol') if-then-else
296+ =(a b) test equality
297+ (function args ...) call function with args
286298
287−New material
299+### New material
288300
289−- There are two syntaxes for writing Hoon: tall form and wide
290− form.
301+1. There are two syntaxes for writing Hoon: tallform and wideform.
291302
292− In tall form, expressions are formed with either two spaces or
303+ In tallform, expressions are formed with either two spaces or
293304 a line break separating both a rune from its children and each
294− of its children from one another. We use tall form when writing
305+ of its children from one another. We use tallform when writing
295306 multiline expressions.
296307
297308 For more concise expressions, we use wideform, which is always
298− a single line. Wideform can be used inside tall form
309+ a single line. Wideform can be used inside tallform
299310 expressions, but not vice versa.
300311
301− Wideform expressions are formed with a rune followed by ()
312+ Wideform expressions are formed with a rune followed by `()`
302313 containing its children, all of which are separated by a
303− single space. For example to make a cell of two elements:
314+ single space. For example, to make a cell of two elements:
304315
305− :-(a b)
316+ :-(a b)
306317
307318 We've already seen wideform in action, for example with
308− =((mod b 3) 0). In this case = is actually an irregular form
309− of .=, which tests its two children for equality.
319+ `=((mod b 3) 0)`. In this case, `=` is actually an irregular form
320+ of `.=`, which tests its two children for equality.
310321
311− Surrounding a function with () is an irregular wide form
312− syntax for calling a function with n arguments. More on this later.
322+ Surrounding a function with `()` is an irregular wide form
323+ syntax for calling a function with _N_ arguments. More on this later.
313324
314−- :- makes a cell of values. The irregular wide form of this is
315− [a b], with two expressions separated by a single space. (While the regular form of this rune takes a fixed number of children--2--its irregular wide form can accept n expressions:[a1..an])
325+1. `:-` makes a cell of values. The irregular wide form of this is
326+ `[a b]`, with two expressions separated by a single space.
327+ While the regular form of this rune takes a fixed number of
328+ children (two), its irregular wide form can accept _N_ expressions:
329+ `[a1..an]`
316330
317−- Cords are one datatype for text in hoon. They're just a big
331+2. Cords are one datatype for text in Hoon. They're just a big
318332 atom formed from adjacent unicode bytes -- a "c string". To
319− produce a cord enclose text within single quotes. To set the type
320− of an argument to a cord, use @t.
333+ produce a cord, enclose text within single quotes. To set the type
334+ of an argument to a cord, use `@t`.
335+
321336
322−```