@@ -6,7 +6,7 @@ title: Hoon refresher / crash course
66
77# Basic Hoon
88
9−This recapitulates material you've already learned in Core Hoon.
9+This recapitulates material you've already learned in [Hoon](/docs/hoon/).
1010It will be a very abrupt tutorial if you don't know Hoon already,
1111but it may be enough in and of itself. If you don't find it obvious at first
1212glance, read it over again.
@@ -28,8 +28,8 @@ operation](/docs/user/basic) of your urbit.
2828
2929If you haven't copied in the examples repo, running the following commands from your urbit directory should do the trick:
3030
31−`cp -r {wherever-you've-pulled-to}/examples/gall/*/ arvo/`
32−`cp -r {wherever-you've-pulled-to}/examples/dojo/*/ arvo/`
31+`$ cp -r {wherever-you've-pulled-to}/examples/gall/*/ arvo/`
32+`$ cp -r {wherever-you've-pulled-to}/examples/dojo/*/ arvo/`
3333
3434Run an example to ensure it worked:
3535
@@ -114,10 +114,10 @@ more detail later.
114114### How to form expressions
115115
116116Hoon does not typically use reserved words to form expressions. Instead,
117−expressions are formed with runes--diagraphs of two
118−ascii symbols. Each rune takes a specific number of
119−children--either expressions formed by other runes or literals
120−that produce their own value (some runes take n children, and are usually closed with `==`).
117+expressions are formed with _runes_: digraphs of two
118+ASCII symbols. Each rune takes a specific number of
119+children, either expressions formed by other runes or literals
120+that produce their own value (some runes take _N_ children, and are usually closed with `==`).
121121
122122For example, the rune `?:` from line 17 is the classic
123123'if-then-else' statement, and thus takes three children:
@@ -130,16 +130,16 @@ Since runes are such a fundamental structure in Hoon, we found
130130ourselves speaking them out loud frequently. It quickly grew
131131cumbersome to have to say "question mark, colon" to describe
132132`?:`. To alleviate this problem, we came up with our own naming
133−scheme: each ascii glyph has a single syllable pronunciation
133+scheme: each ASCII glyph has a single-syllable pronunciation
134134phonetically designed to be both easily remembered and easily
135135pronounced in conjunction with the other glyphs (when forming a
136136rune).
137137
138−See the entire naming schema below/or link to it:
138+See the entire naming scheme below.
139139
140140```
141141 ace [1 space] gal < pel (
142− bar | gap [>1 space, nl] per )
142+ bar | gap [>1 space, \n] per )
143143 bas \ gar > sel [
144144 buc $ hax # sem ;
145145 cab _ hep - ser ]
@@ -151,9 +151,9 @@ See the entire naming schema below/or link to it:
151151 fas / pat @ zap !
152152```
153153
154−Using our naming scheme `?:` is said 'wut col'.
154+Using this scheme, we would pronounce `?:` as 'wutcol'.
155155
156−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`:
156+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`:
157157
158158`{$if p/twig q/twig r/twig} :: ?: if/then/else`
159159
@@ -173,8 +173,8 @@ if(=(1 2) 'this is true' 'this is false')
173173### Lines 12-34
174174
175175Now let's quickly walk through this code line-by-line. Lines
176−12-34 are wrapped in a `|%` (pronounced 'bar cen'), which
177−produces a core, a fundamental datatype in hoon similar to a
176+12-34 are wrapped in a `|%` ('barcen'), which produces a core.
177+Cores are a fundamental datatype in Hoon, similar to a
178178struct, class, or object. A core is just a map of names
179179to any kind of code, whether it be functions or data. Each
180180element in this map begins with a `++` followed by the name and
@@ -182,8 +182,8 @@ the corresponding code. Since `|%` takes an arbitrary number of
182182children, it needs to be closed with a `--`.
183183
184184<blockquote class="blockquote">
185−`++` is not technically a rune, since it is only used in core
186−syntax as shown above
185+`++` ('luslus') is not technically a rune, since it is only used
186+in core syntax, as shown above.
187187</blockquote>
188188
189189Let's step into each of the three arms within our core.
@@ -195,16 +195,16 @@ Let's step into each of the three arms within our core.
195195 (add (five a) (three a))
196196 --
197197
198−`|=` produces a function, much like a lambda in lisp. It takes two children:
198+`|=` ('bartis') produces a function, much like a lambda in lisp. It takes two children:
199199
200−- A set of argument(s). In this case our argument set only
201− contains one: `a`, which is required to be an atom or natural
200+1. A set of argument(s). In this case our argument set only
201+ contains one: `a`, which is required to be an atom or natural
202202 number, denoted by `@`.
203203
204−- The body of the function itself, which is executed when the
204+1. The body of the function itself, which is executed when the
205205 function is called (in this case, with `(sum 1.000)`). This
206206 particular function adds the results of evaluating the gates `++
207− five` and `++three` with each of their respective input
207+ five` and `++three` with each of their respective input
208208 parameters set to `a`.
209209
210210### ++ three
@@ -221,20 +221,35 @@ As above, `++three` takes an integer argument, `a`, and then
221221executes the remainder of the code with `a` set to the actual
222222arguments.
223223
224−Similarly, `=|` pushes its first child, `b` into our context (in
225−other words, it declares a variable `b`) and executes the
226−remainder of the code. However, `b` is not an argument; `=|`
224+Similarly, `=|` ('tisbar') pushes its first child, `b` into our
225+context (in other words, it declares a variable `b`) and executes
226+the remainder of the code. However, `b` is not an argument; `=|`
227227sets `b` to the default value of whatever type it is declared as.
228228Since the default value of an atom is `0`, b is set to `0`.
229229
230+<blockquote class="blockquote">
231+To find the default value of any given type, use `$*` ('buctar') followed by the type.
232+Alternatively, use the irregular form `*`.
233+
234+ > ($* @)
235+ 0
236+
237+ > *@
238+ 0
239+
240+ > *@p
241+ ~zod
242+
243+</blockquote>
244+
230245So now we have two variables: `a` is set to our input, and `b` is
231246initialized to `0`.
232247
233−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
234249point. More on this later.
235250
236−`^-` is just a cast that sets the result of the remainder of the
237−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`.
238253
239254In pseudocode, the last three lines read like this: if `a` is
240255less than `b`, produce zero. Else, add `b` to the result of
@@ -249,73 +264,73 @@ you recurse by an actual function call, then you have to specify
249264every argument.
250265
251266<blockquote class="blockquote">
252−If you're familiar with Clojure, `|-` is `loop` and `$()` is
253−recur.
267+If you're familiar with Clojure, `|-` is `loop` and `$()` is `recur`.
254268</blockquote>
255269
256270**Exercises**:
257271
258−Please tweak your code to complete the following excercises.
272+Tweak your code to complete the following excercises.
259273
260−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
261275you will need to complete the excercises below. For these, please
262276refer to our cheatsheat at the bottom.
263277
264−- Read and understand `++five` line by line.
278+1. Read and understand `++five` line by line.
265279
266−- Change `++sum` to accept two variables, `a` and `b`. Pass `a`
267− to three and `b` to five. Then run the code with `a` set to
268− `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`.
269283
270−- Check if this new result is under one thousand. If it is,
271− return the string 'result is less than one thousand'. If not,
272− 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'`.
273287
274−```
275−Review
288+### Review
276289
277−|% start core (collection of named ++ arms; an "object")
278−|= define function
279−=| define variable from type with default value
280−|- drop a recursion point
281−^- cast
282−?: if-then-else
283−=(a b) test equality
284−(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
285298
286−New material
299+### New material
287300
288−- There are two syntaxes for writing Hoon: tall form and wide
289− form.
301+1. There are two syntaxes for writing Hoon: tallform and wideform.
290302
291− In tall form, expressions are formed with either two spaces or
303+ In tallform, expressions are formed with either two spaces or
292304 a line break separating both a rune from its children and each
293− of its children from one another. We use tall form when writing
305+ of its children from one another. We use tallform when writing
294306 multiline expressions.
295307
296308 For more concise expressions, we use wideform, which is always
297− a single line. Wideform can be used inside tall form
309+ a single line. Wideform can be used inside tallform
298310 expressions, but not vice versa.
299311
300− Wideform expressions are formed with a rune followed by ()
312+ Wideform expressions are formed with a rune followed by `()`
301313 containing its children, all of which are separated by a
302− single space. For example to make a cell of two elements:
314+ single space. For example, to make a cell of two elements:
303315
304− :-(a b)
316+ :-(a b)
305317
306318 We've already seen wideform in action, for example with
307− =((mod b 3) 0). In this case = is actually an irregular form
308− 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.
309321
310− Surrounding a function with () is an irregular wide form
311− 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.
312324
313−- :- makes a cell of values. The irregular wide form of this is
314− [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]`
315330
316−- 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
317332 atom formed from adjacent unicode bytes -- a "c string". To
318− produce a cord enclose text within single quotes. To set the type
319− 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+
320336
321−```