2b772a8 · urbit.org · git.iko.soy

git.iko.soy/urbit.org

on master help sign in

basic done; split into two sections

2b772a8Henry Ault11 years ago

docs/programming/system/basic.md+31−130

compare with master

unifiedsplit

@@ -7,13 +7,13 @@ title: Hoon refresher / crash course

8# Basic Hoon

10−(This recapitulates material you've already learned in Core Hoon.

10+This recapitulates material you've already learned in Core Hoon.

11It 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

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

13+glance, read it over again.

15Our 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

17of the fundamentals of hoon. To do this we'll walk through two

18simple programs: the first [Project

19Euler](https://projecteuler.net/) problem and

@@ -23,7 +23,7 @@ To run this code, you'll need an urbit, and you'll need the

23`%examples` desk from `~zod`. If you haven't installed

24urbit yet, check out the [installation

25instructions](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

27operation](http://urbit.org/docs/user/basic) of your urbit.

29If you haven't pulled the examples desk from `~zod`, do

@@ -34,8 +34,8 @@ so now:

34 [time passes...]

35 merged with strategy %init

37−The merge could take several minutes; you'll know it's done when

37+This merge could take several minutes; you'll know it's done when

38−"merged with strategy %init" is printed. Mount the new files to

38+"merged with strategy %init" is printed. Next, mount the new files to

39your Unix pier directory:

41 ~fintud-macrep:dojo> |mount /=examples=

@@ -66,6 +66,7 @@ under `/examples/gen/euler1.hoon`):

67```

68:: project euler 1

69+:: project euler 1

69:: https://projecteuler.net/problem=1

70:: https://projecteuler.net/problem=1

70:: run in dojo with +euler1

71:: run in dojo with +euler1

71::

72::

@@ -75,20 +76,20 @@ under `/examples/gen/euler1.hoon`):

75:- %noun

76:- %noun

76=< (sum 1.000)

77=< (sum 1.000)

77::

78::

78−:::: ~fintud-macrep

79+:::: ~sivtyv-barnel

79 ::

80 ::

80|%

81|%

81++ three

82++ three

82− |= a=@

83+ |= a/@

83− =| b=@

84+ =| b/@

84 |- ^- @u

85 |- ^- @u

85 ?: (lth a b)

86 ?: (lth a b)

86 0

87 0

87 (add b $(b (add 3 b)))

88 (add b $(b (add 3 b)))

89++ five

90++ five

90− |= a=@

91+ |= a/@

91− =| b=@

92+ =| b/@

92 |- ^- @

93 |- ^- @

93 ?: (lte a b)

94 ?: (lte a b)

94 0

95 0

@@ -97,17 +98,19 @@ under `/examples/gen/euler1.hoon`):

97 (add b $(b (add b 5)))

98 (add b $(b (add b 5)))

99++ sum

100++ sum

100− |= a=@u

101+ |= a/@u

101 (add (five a) (three a))

102 (add (five a) (three a))

102--

103--

103```

104```

104

105

106+<blockquote class=“blockquote”>

105> Hoon is not generally whitespace sensitive, but we do have two

107> Hoon is not generally whitespace sensitive, but we do have two

106> different kinds of whitespace: a single space and a gap, which

108> different kinds of whitespace: a single space and a gap, which

107> is two or more spaces or a linebreak. Tabs are taboo. Do not

109> is two or more spaces or a linebreak. Tabs are taboo. Do not

108> use them. Really. For a more detailed explanation of when to

110> use them. Really. For a more detailed explanation of when to

109> use spaces vs. gaps, see the syntax section before the first

111> use spaces vs. gaps, see the syntax section before the first

110> excercises.

112> excercises.

113+<blockquote class=“blockquote”>

111

114

112### Lines 1-11:

115### Lines 1-11:

113

116

@@ -123,11 +126,11 @@ more detail later.

123

126

124### How to form expressions

127### How to form expressions

125

128

126−Hoon does not use reserved words to form expressions. Instead,

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,

127−expressions are formed with runes, which are diagraphs of two

130+expressions are formed with runes--diagraphs of two

128ascii symbols. Each rune takes a specific number of

131ascii symbols. Each rune takes a specific number of

129children--either expressions formed by other runes or literals

132children--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 `==`).

131

134

132For example, the rune `?:` from line 17 is the classic

135For example, the rune `?:` from line 17 is the classic

133'if-then-else' statement, and thus takes three children:

136'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.

182### `++ sum`

185### `++ sum`

183

186

184 ++ sum

187 ++ sum

185− |= a=@

188+ |= a/@

186 (add (five a) (three a))

189 (add (five a) (three a))

187 --

190 --

188

191

@@ -201,8 +204,8 @@ Let's step into each of the three arms within our core.

201### ++ three

204### ++ three

202

205

203 ++ three

206 ++ three

204− |= a=@

207+ |= a/@

205− =| b=@

208+ =| b/@

206 |- ^- @u

209 |- ^- @u

207 ?: (lth a b)

210 ?: (lth a b)

208 0

211 0

@@ -263,7 +266,7 @@ refer to our cheatsheat at the bottom.

263```

266```

264Review

267Review

265

268

266−|% start core (collection of named ++ arms)

269+|% start core (collection of named ++ arms; an "object")

267|= define function

270|= define function

268=| define variable from type with default value

271=| define variable from type with default value

269|- drop a recursion point

272|- drop a recursion point

@@ -274,14 +277,6 @@ Review

274

277

275New material

278New material

276

279

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−

285- There are two syntaxes for writing Hoon: tall form and wide

280- There are two syntaxes for writing Hoon: tall form and wide

286 form.

281 form.

287

282

@@ -304,109 +299,15 @@ New material

304 =((mod b 3) 0). In this case = is actually an irregular form

299 =((mod b 3) 0). In this case = is actually an irregular form

305 of .=, which tests its two children for equality.

300 of .=, which tests its two children for equality.

306

301

307− Another irregular form is [a b] for :-(a b)

308−

309 Surrounding a function with () is an irregular wide form

302 Surrounding a function with () is an irregular wide form

310− syntax for calling a function with n arguments.

303+ syntax for calling a function with n arguments. More on this later.

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.

375

304

376−Hoon is unique in that this context is a first-class value.

305+- :- makes a cell of values. The irregular wide form of this is

377−Scheme allows a sort of reification of the context through

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])

378−continutations, and some may see a parallel to Forth's stack, but

379−Hoon takes takes the concept one step further.

380

307

381−Our starting subject is the standard library, which is defined in

308+- Cords are one datatype for text in hoon. They're just a big

382−`/arvo/hoon.hoon` and `/arvo/zuse.hoon`. This is where functions

309+ atom formed from adjacent unicode bytes -- a "c string". To

383−like `add` are defined. When we define a core with `|%`, we

310+ produce a cord enclose text within single quotes. To set the type

384−don't throw away the subject (i.e. the standard library); rather,

311+ of an argument to a cord, use @t.

385−we stack the new core on top of the old subject so that both are

386−accessible.

387−

388−**Exercises**:

389

312

390−- Pass `++sum` its arguments (`2000` and `3000`) from the

313+```

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.

docs/programming/system/subject.mdnew file+99

@@ -0,0 +1,99 @@

1+## The subject

3+Now we're going to cover the boiler plate that we skimmed over

4+earlier.

6+ :- %say |= *

7+ :- %noun

8+ =< (sum [1.000 2.000])

10+This program is a cell of two elements: the first, `%say`, tells

11+the interpreter what to produce--in this case a value.

12+

13+The second element is `|=`, which we know produces a function.

14+`|=`'s first child is its argument(s), which in this case is any

15+noun (`*`). Its second child is the remainder of the program.

16+

17+Similarly, the rest of the program is a cell of the literal

18+`%noun`, which tells the shell that we're producing a value of

19+type `noun`, and the second child contains the code that we run

20+to actually produce our value of the type `noun`.

21+

22+`=<` is a rune that takes two children. The second child is the

23+context against which we run the first child. So in this case, we

24+are running the expression `(sum 1.000)` against everything

25+contained within the `|%`. In Hoon, we call the code executed the

26+"formula" and its context the "subject".

27+

28+```

29+::::::::::::::::::::::::::::::

30+=< (sum 1.000) :: formula

31+::::::::::::::::::::::::::::::

32+|% ::

33+++ three ::

34+ |= a=@ ::

35+ =| b=@ ::

36+ |- ^- @u ::

37+ ?: (lth a b) ::

38+ 0 ::

39+ (add b $(b (add 3 b))) ::

40+ ::

41+++ five ::

42+ |= a=@ :: subject

43+ =| b=@ ::

44+ |- ^- @ ::

45+ ?: (lte a b) ::

46+ 0 ::

47+ ?: =((mod b 3) 0) ::

48+ $(b (add b 5)) ::

49+ (add b $(b (add b 5))) ::

50+ ::

51+++ sum ::

52+ |= a=@u ::

53+ (add (five a) (three a)) ::

54+-- ::

55+::::::::::::::::::::::::::::::

56+```

57+

58+In nearly every language there is a similar concept of a

59+"context" in which expressions are executed. For example, in C

60+this includes things like the call stack, stack variables, and so

61+on.

62+

63+Hoon is unique in that this context is a first-class value.

64+Scheme allows a sort of reification of the context through

65+continutations, and some may see a parallel to Forth's stack, but

66+Hoon takes takes the concept one step further.

67+

68+Our starting subject is the standard library, which is defined in

69+`/arvo/hoon.hoon` and `/arvo/zuse.hoon`. This is where functions

70+like `add` are defined. When we define a core with `|%`, we

71+don't throw away the subject (i.e. the standard library); rather,

72+we stack the new core on top of the old subject so that both are

73+accessible.

74+

75+**Exercises**:

76+

77+- Pass `++sum` its arguments (`2000` and `3000`) from the

78+ commandline.

79+

80+- Comment out all of the arms of the `|%`. Now add another arm

81+ and call it `++add`, have it accept two arguments and procduce

82+ 42 (regardless of input). Change the `=<` line to `[(add 5 7)

83+ (^add 5 7)]`. Can you recognize what's happening?

84+

85+Cheatsheet:

86+

87+- To pass arguments from the command line to a program, you

88+ replace the `*` in the first line of the boiler plate to

89+ `[^ [[arg=TYPE ~] ~]]` where `TYPE` is replaced with the

90+ type of argument you're expecting. Then `+euler1 a` from

91+ the dojo sets `arg` to `a`.

92+- The empty list is `~`

93+- Lisp-style cons (construct a cell/prepend an element) is

94+ `[new-element list]`

95+- For example, the first three positive integers are `[1 2 3

96+ ~]`

97+- `gte` tests whether `a` is greater than or equal to `b`.

98+- `mod` runs the modulo operation on two atoms.

99+- See the [basic math section]() for more info.