@@ -7,13 +7,13 @@ 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 Core Hoon.
1111It will be a very abrupt tutorial if you don't know Hoon already,
12−but it may just suffice. If you don't find it obvious at first
13−glance, read it over again
12+but it may be enough in and of itself. If you don't find it obvious at first
13+glance, read it over again.
1414
1515Our goal is to get you programming interesting and useful things
16−as soon as possible. To get there we have to quickly cover some
16+as soon as possible. To get there, we have to quickly cover some
1717of the fundamentals of hoon. To do this we'll walk through two
1818simple programs: the first [Project
1919Euler](https://projecteuler.net/) problem and
@@ -23,7 +23,7 @@ To run this code, you'll need an urbit, and you'll need the
2323`%examples` desk from `~zod`. If you haven't installed
2424urbit yet, check out the [installation
2525instructions](http://urbit.org/docs/user/install). Once urbit is
26−intalled, take a look at the [basic
26+installed, take a look at the [basic
2727operation](http://urbit.org/docs/user/basic) of your urbit.
2828
2929If you haven't pulled the examples desk from `~zod`, do
@@ -34,8 +34,8 @@ so now:
3434 [time passes...]
3535 merged with strategy %init
3636
37−The merge could take several minutes; you'll know it's done when
38−"merged with strategy %init" is printed. Mount the new files to
37+This merge could take several minutes; you'll know it's done when
38+"merged with strategy %init" is printed. Next, mount the new files to
3939your Unix pier directory:
4040
4141 ~fintud-macrep:dojo> |mount /=examples=
@@ -66,6 +66,7 @@ under `/examples/gen/euler1.hoon`):
6666
6767```
6868:: project euler 1
69+:: project euler 1
6970:: https://projecteuler.net/problem=1
7071:: run in dojo with +euler1
7172::
@@ -75,20 +76,20 @@ under `/examples/gen/euler1.hoon`):
7576:- %noun
7677=< (sum 1.000)
7778::
78−:::: ~fintud-macrep
79+:::: ~sivtyv-barnel
7980 ::
8081|%
8182++ three
82− |= a=@
83− =| b=@
83+ |= a/@
84+ =| b/@
8485 |- ^- @u
8586 ?: (lth a b)
8687 0
8788 (add b $(b (add 3 b)))
8889
8990++ five
90− |= a=@
91− =| b=@
91+ |= a/@
92+ =| b/@
9293 |- ^- @
9394 ?: (lte a b)
9495 0
@@ -97,17 +98,19 @@ under `/examples/gen/euler1.hoon`):
9798 (add b $(b (add b 5)))
9899
99100++ sum
100− |= a=@u
101+ |= a/@u
101102 (add (five a) (three a))
102103--
103104```
104105
106+<blockquote class=“blockquote”>
105107> Hoon is not generally whitespace sensitive, but we do have two
106108> different kinds of whitespace: a single space and a gap, which
107109> is two or more spaces or a linebreak. Tabs are taboo. Do not
108110> use them. Really. For a more detailed explanation of when to
109111> use spaces vs. gaps, see the syntax section before the first
110112> excercises.
113+<blockquote class=“blockquote”>
111114
112115### Lines 1-11:
113116
@@ -123,11 +126,11 @@ more detail later.
123126
124127### How to form expressions
125128
126−Hoon does not use reserved words to form expressions. Instead,
127−expressions are formed with runes, which are diagraphs of two
129+Hoon does not use reserved words to form expressions. (We did recently implement an alternative keyword syntax, which is not covered here. For more information, see the [syntax section]()). Instead,
130+expressions are formed with runes--diagraphs of two
128131ascii symbols. Each rune takes a specific number of
129132children--either expressions formed by other runes or literals
130−that produce their own value.
133+that produce their own value (some runes take n children, and are usually closed with `==`).
131134
132135For example, the rune `?:` from line 17 is the classic
133136'if-then-else' statement, and thus takes three children:
@@ -182,7 +185,7 @@ Let's step into each of the three arms within our core.
182185### `++ sum`
183186
184187 ++ sum
185− |= a=@
188+ |= a/@
186189 (add (five a) (three a))
187190 --
188191
@@ -201,8 +204,8 @@ Let's step into each of the three arms within our core.
201204### ++ three
202205
203206 ++ three
204− |= a=@
205− =| b=@
207+ |= a/@
208+ =| b/@
206209 |- ^- @u
207210 ?: (lth a b)
208211 0
@@ -263,7 +266,7 @@ refer to our cheatsheat at the bottom.
263266```
264267Review
265268
266−|% start core (collection of named ++ arms)
269+|% start core (collection of named ++ arms; an "object")
267270|= define function
268271=| define variable from type with default value
269272|- drop a recursion point
@@ -274,14 +277,6 @@ Review
274277
275278New material
276279
277−- :- make a cell of values. The irregular wide form of this is
278− [a b] with two expressions separated by a single space.
279−
280−- Cords are one datatype for text in hoon. They're just a big
281− atom formed from adjacent unicode bytes -- a "c string". To
282− produce a cord enclose text within single quotes. To set the type
283− of an argument to a cord, use @t.
284−
285280- There are two syntaxes for writing Hoon: tall form and wide
286281 form.
287282
@@ -304,109 +299,15 @@ New material
304299 =((mod b 3) 0). In this case = is actually an irregular form
305300 of .=, which tests its two children for equality.
306301
307− Another irregular form is [a b] for :-(a b)
308−
309302 Surrounding a function with () is an irregular wide form
310− syntax for calling a function with n arguments.
311−```
312−
313−
314−## The subject
315−
316−Now we're going to cover the boiler plate that we skimmed over
317−earlier.
318−
319− :- %say |= *
320− :- %noun
321− =< (sum [1.000 2.000])
322−
323−This program is a cell of two elements: the first, `%say`, tells
324−the interpreter what to produce--in this case a value.
325−
326−The second element is `|=`, which we know produces a function.
327−`|=`'s first child is its argument(s), which in this case is any
328−noun (`*`). Its second child is the remainder of the program.
329−
330−Similarly, the rest of the program is a cell of the literal
331−`%noun`, which tells the shell that we're producing a value of
332−type `noun`, and the second child contains the code that we run
333−to actually produce our value of the type `noun`.
334−
335−`=<` is a rune that takes two children. The second child is the
336−context against which we run the first child. So in this case, we
337−are running the expression `(sum 1.000)` against everything
338−contained within the `|%`. In Hoon, we call the code executed the
339−"formula" and its context the "subject".
340−
341−```
342−::::::::::::::::::::::::::::::
343−=< (sum 1.000) :: formula
344−::::::::::::::::::::::::::::::
345−|% ::
346−++ three ::
347− |= a=@ ::
348− =| b=@ ::
349− |- ^- @u ::
350− ?: (lth a b) ::
351− 0 ::
352− (add b $(b (add 3 b))) ::
353− ::
354−++ five ::
355− |= a=@ :: subject
356− =| b=@ ::
357− |- ^- @ ::
358− ?: (lte a b) ::
359− 0 ::
360− ?: =((mod b 3) 0) ::
361− $(b (add b 5)) ::
362− (add b $(b (add b 5))) ::
363− ::
364−++ sum ::
365− |= a=@u ::
366− (add (five a) (three a)) ::
367−-- ::
368−::::::::::::::::::::::::::::::
369−```
370−
371−In nearly every language there is a similar concept of a
372−"context" in which expressions are executed. For example, in C
373−this includes things like the call stack, stack variables, and so
374−on.
303+ syntax for calling a function with n arguments. More on this later.
375304
376−Hoon is unique in that this context is a first-class value.
377−Scheme allows a sort of reification of the context through
378−continutations, and some may see a parallel to Forth's stack, but
379−Hoon takes takes the concept one step further.
305+- :- makes a cell of values. The irregular wide form of this is
306+ [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])
380307
381−Our starting subject is the standard library, which is defined in
382−`/arvo/hoon.hoon` and `/arvo/zuse.hoon`. This is where functions
383−like `add` are defined. When we define a core with `|%`, we
384−don't throw away the subject (i.e. the standard library); rather,
385−we stack the new core on top of the old subject so that both are
386−accessible.
387−
388−**Exercises**:
308+- Cords are one datatype for text in hoon. They're just a big
309+ atom formed from adjacent unicode bytes -- a "c string". To
310+ produce a cord enclose text within single quotes. To set the type
311+ of an argument to a cord, use @t.
389312
390−- Pass `++sum` its arguments (`2000` and `3000`) from the
391− commandline.
392−
393−- Comment out all of the arms of the `|%`. Now add another arm
394− and call it `++add`, have it accept two arguments and procduce
395− 42 (regardless of input). Change the `=<` line to `[(add 5 7)
396− (^add 5 7)]`. Can you recognize what's happening?
397−
398−Cheatsheet:
399−
400−- To pass arguments from the command line to a program, you
401− replace the `*` in the first line of the boiler plate to
402− `[^ [[arg=TYPE ~] ~]]` where `TYPE` is replaced with the
403− type of argument you're expecting. Then `+euler1 a` from
404− the dojo sets `arg` to `a`.
405−- The empty list is `~`
406−- Lisp-style cons (construct a cell/prepend an element) is
407− `[new-element list]`
408−- For example, the first three positive integers are `[1 2 3
409− ~]`
410−- `gte` tests whether `a` is greater than or equal to `b`.
411−- `mod` runs the modulo operation on two atoms.
412−- See the [basic math section]() for more info.
313+```