@@ -13,28 +13,68 @@ possible. To get there, we have to quickly cover some of the fundamentals of
1313first [Project Euler](https://projecteuler.net/) problem and
1414[fizzbuzz](https://en.wikipedia.org/wiki/Fizz_buzz).
1515
16−To run this code, you'll need an urbit, and will have to copy the [examples
17−repo](https://github.com/urbit/examples) into it.
16+To run this code, you'll need an urbit, and will have to either sync or copy the
17+[examples repo](https://github.com/urbit/examples) into it.
1818
19−If you haven't installed urbit yet, check out the [installation
20−instructions](/docs/using/install). Once urbit is installed, take a look at the
21−[basic operation](/docs/using/admin) of your urbit.
19+## Installation
2220
23−If you haven't copied in the examples repo, running the following commands from
24−your urbit directory should do the trick:
21+First, you'll need a running urbit. Follow our urbit.org [install
22+instructions](https://urbit.org/docs/using/install), then
23+[setup](https://urbit.org/docs/using/setup) and urbit.
2524
26−Make sure you've mounted your `%home` desk:
25+Follow the *Network install* below if your urbit is running on the live network
26+(comets are usually best for development). Follow the *Local install* instead
27+if you're on a
28+[fake ship](https://urbit.org/fora/posts/~2017.1.5..21.31.04..20f3~/) or are
29+otherwise experiencing problems with the network install.
2730
28− ~fintud-macrep:dojo> |mount %
31+### Network install
2932
30−Then, copy the example into it
33+In your urbit's `:dojo`, run the command:
3134
32− $ cp -r {urbit-examples}/gall/*/* {your-pier}/home/
33− $ cp -r {urbit-examples}/dojo/*/* {your-pier}/home/
35+ ~your-urbit:dojo> |sync %examples ~ropmev-pocseb %examples
36+
37+Depending on network traffic, this initial merge and sync could take anywhere
38+between thirty seconds to several minutes. Upon a successful sync you'll see the
39+output:
40+
41+ sync succeeded from %examples on ~ropmev-pocseb to %examples
42+
43+In which case, next run the commands:
44+
45+ ~your-urbit:dojo> =dir /=examples=
46+ ~your-urbit:dojo/examples> |serve %/web
47+ ~your-urbit:dojo/examples> |mount %
48+
49+If your sync isn't succeeding after a few minutes for whatever reason, run
50+`|cancel %examples` in your `:dojo` and follow the local install below instead.
51+
52+### Local install
53+
54+In your urbit's `:dojo`:
55+
56+ ~your-urbit:dojo> |merge %examples our %base, =gem %init
57+ ~your-urbit:dojo> =dir /=examples=
58+ ~your-urbit:dojo/examples> |serve %/web
59+ ~your-urbit:dojo/examples> |mount %
60+
61+If `~your-urbit` was installed at `/urbit/path` on your Unix machine, you can
62+now find your `%examples` desk at the path `/urbit/path/your-urbit/examples`.
63+
64+Lastly, in Unix, clone this repo somewhere and copy in the `examples` files to
65+your urbit's new mounted `%examples` desk. You can run the following shell
66+commands (*replacing your urbit's examples desk path as necessary*):
67+
68+ $ git clone https://github.com/urbit/examples
69+ $ for dir in {app,gen,lib,mar,sec,sur,web}; do cp -r ./examples/$dir* /urbit/path/your-urbit/examples; done
70+
71+Your `%clay` filesystem should acknowledge the newly added files.
72+
73+## Get started!
3474
3575Run an example to ensure it worked:
3676
37− ~fintud-macrep:dojo> +examples-euler1
77+ ~fintud-macrep:dojo> +project-euler/p1
3878 233.168
3979
4080## Euler 1
@@ -47,42 +87,44 @@ Let's check out the code for Euler 1. First, the problem:
4787 Find the sum of all the multiples of 3 or 5 below 1000.
4888
4989Here is the hoon solution (which should be in your pier directory under
50−`/gen/examples/euler1`):
90+`/examples/gen/project-euler/p1`):
5191
52− :: project euler 1
53− :: https://projecteuler.net/problem=1
54− :: run in dojo with +examples-euler1
92+ :: Project Euler 1
93+ :: https://projecteuler.net/problem=1
5594 ::
56− :::: /hoon/euler1/examples/gen
57− ::
58− :- %say |= *
95+ :: run in dojo with:
96+ :: ~your-urbit:dojo/examples> +project-euler/p1
97+ ::
98+ :::: /===/gen/project-euler/p1/hoon
99+ ::
100+ !:
101+ ::
102+ :- %say |= *
59103 :- %noun
60104 =< (sum 1.000)
61105 ::
62− :::: ~sivtyv-barnel
63− ::
64106 |%
65107 ++ three
66− |= a/@
67− =| b/@
68− |- ^- @u
108+ |= a/@
109+ =| b/@
110+ |- ^- @u
69111 ?: (lth a b)
70− 0
112+ 0
71113 (add b $(b (add 3 b)))
72114 ::
73115 ++ five
74− |= a/@
75− =| b/@
116+ |= a/@
117+ =| b/@
76118 |- ^- @
77119 ?: (lte a b)
78− 0
120+ 0
79121 ?: =((mod b 3) 0)
80− $(b (add b 5))
122+ $(b (add b 5))
81123 (add b $(b (add b 5)))
82124 ::
83− ++ sum
125+ ++ sum
84126 |= a/@u
85− (add (five a) (three a))
127+ (add (five a) (three a))
86128 --
87129
88130> Hoon is not generally whitespace sensitive, but we do have two different kinds
@@ -91,7 +133,7 @@ Here is the hoon solution (which should be in your pier directory under
91133> explanation of when to use spaces vs. gaps, see the syntax section before the
92134> first exercises.
93135
94−### Lines 1-11:
136+### Lines 1-13:
95137
96138Any line that begins with `::` is a comment.
97139
@@ -110,7 +152,7 @@ takes a specific number of children, either expressions formed by other runes or
110152literals that produce their own value (some runes take *N* children, and are
111153usually closed with `==`).
112154
113−For example, the rune `?:` from line 18 is the classic 'if-then-else' statement,
155+For example, the rune `?:` from line 20 is the classic 'if-then-else' statement,
114156and thus takes three children:
115157
116158 ?: (lth a b) :: if first child evals to true
@@ -141,31 +183,15 @@ See the entire naming scheme below.
141183
142184Using this scheme, we would pronounce `?:` as 'wutcol'.
143185
144−For those who prefer to use reserved words to form expressions, you can
145−substitute any rune with that rune's keyword, which you can find in `++twig` in
146−`/arvo/hoon.hoon`. For example, here's the code for `?:` in `++twig`:
186+### Lines 14-37
147187
148−`{$if p/twig q/twig r/twig} :: ?: if/then/else`
149−
150−Instead of:
151−
152− ?:(=(1 2) 'this is true' 'this is false')
153− 'this is false'`
154−
155−You can write:
156−
157− :if(=(1 2) 'this is true' 'this is false')
158− 'this is false'
159−
160−### Lines 13-35
161−
162−Now let's quickly walk through this code line-by-line. Lines 13-35 are wrapped
188+Now let's quickly walk through this code line-by-line. Lines 14-37 are wrapped
163189in a `|%` ('[barcen](../../hoon/twig/bar-core/cen-core/)'), which produces a
164190core. Cores are a fundamental datatype in Hoon, similar to a struct, class, or
165191object. A core is just a map of names to any kind of code, whether it be
166−functions or data. Each element in this map begins with a `++` followed by the
167−name and the corresponding code. Since `|%` takes an arbitrary number of
168−children, it needs to be closed with a `--`.
192+functions or data. Each element, called an arm, in this map begins with a `++`
193+followed by the name and the corresponding code. Since `|%` takes an arbitrary
194+number of children, it needs to be closed with a `--`.
169195
170196> `++` ('luslus') is not technically a rune, since it is only used in core
171197> syntax, as shown above.
@@ -175,7 +201,7 @@ Let's step into each of the three arms within our core.
175201### `++ sum`
176202
177203 ++ sum
178− |= a/@
204+ |= a/@u
179205 (add (five a) (three a))
180206 --
181207
@@ -187,7 +213,7 @@ like a lambda in lisp. It takes two children:
187213
1882142. The body of the function itself, which is executed when the function is
189215 called (in this case, with `(sum 1.000)`). This particular function adds the
190− results of evaluating the gates `++ five` and `++three` with each of their
216+ results of evaluating the gates `++five` and `++three` with each of their
191217 respective input parameters set to `a`.
192218
193219### ++ three