a602330 · urbit.org · git.iko.soy

docs/hoon/basic.md+16−20

compare with master

unifiedsplit

@@ -10,11 +10,11 @@ A `span` is a set of nouns and an interpretation of these nouns.

10Officially, we don't use the word "type" in Hoon. But if we had

11to say "type," it would mean `span`.

12

13−## Span and mold

13+## Type, span and mold

14

15There is no Hoon syntax for a span. The programmer never defines

16a span explicitly. It is always produced as the inferred range

17−of an expression (twig).

17+of an expression (`twig`).

18

19But we still need simple, well-formed expressions that produce

20regular and well-shaped ranges, for three reasons.

@@ -37,15 +37,13 @@ definition of a noun. Don't actually call a mold unless you're

37actually validating untrusted foreign data. As a beginner,

38hopefully you aren't!

39

40−## The `span` mold (simplified)

40+## `span`: a set of nouns

41

42−Usually in Hoon we define the semantics of a primitive by the

42+Below is the mold for `span`. You haven't seen this syntax before,

43−state the span of all nouns that implement that primitive. We

43+and we haven't explained it yet; just treat it as pseudocode.

44−state this span as the icon of a mold. That mold is produced by

45−a kernel arm `span`:

46

44

47−This is a slightly simplified version of `span`. We'll undo and

45+This is a slightly simplified version of `span`. We undo and explain the

48−explain the simplifications below.

46+simplifications in the [advanced types](../advanced) section.

49

47

50```

48```

51++ term @tas

49++ term @tas

@@ -61,13 +59,11 @@ explain the simplifications below.

61 ==

59 ==

62```

60```

63

61

64−This is a syntactically correct Hoon twig, but treat it as

65−pseudocode. If a span is an atom, it's either the atomic string

62+If a span is an atom, it's either the atomic string `noun` or

66−`noun` or `void`; if a cell, it's a tuple with one of the heads

63+`void`; if a cell, it's a tuple with one of the heads `atom`,

67−`atom`, `cell`, `core`, etc. We'll go through each of these

64+`cell`, `core`, etc. We'll go through each of these cases below.

68−cases below.

69

65

70−### `$noun` and `$void`

66+### `?($noun $void)`

71

67

72`$noun` is the set of all nouns. `$void` is the set of no nouns.

68`$noun` is the set of all nouns. `$void` is the set of no nouns.

73

69

@@ -76,7 +72,7 @@ cases below.

76`{$cell p/span q/span}` is the set of all cells with head `p` and

72`{$cell p/span q/span}` is the set of all cells with head `p` and

77tail `q`.

73tail `q`.

78

74

79−### `{$fork p/(set span)}

75+### `{$fork p/(set span)}`

80

76

81`{$fork p/(set span)}` is the union of all spans in the set `p`.

77`{$fork p/(set span)}` is the union of all spans in the set `p`.

82

78

@@ -89,17 +85,17 @@ the product when we compile `q` against subject `p`.

89This is "manual laziness." Hoon is a strict language, so we have

85This is "manual laziness." Hoon is a strict language, so we have

90to express

86to express

91

87

92−### `{$face p/term q/span}

88+### `{$face p/term q/span}`

93

89

94A `{$face p/term q/span}` wraps the label `p` around the span

90A `{$face p/term q/span}` wraps the label `p` around the span

95`q`. `p` is a `term` or `@tas`, an atomic ASCII string which

91`q`. `p` is a `term` or `@tas`, an atomic ASCII string which

96obeys symbol rules: lowercase and digit only, infix hyphen,

92obeys symbol rules: lowercase and digit only, infix hyphen,

97first character must be lowercase.

93first character must be lowercase.

98

94

99−See [`:limb`](twig/limb/limb) for how labels are resolved. It's

95+See [`:limb`](../twig/limb/limb) for how labels are resolved. It's

100nontrivial.

96nontrivial.

101

97

102−### `{%atom p/term q/(unit atom))}

98+### `{%atom p/term q/(unit atom))}`

103

99

104An `$atom` is an atom, with two twists. `q` is a `unit`, Hoon's

100An `$atom` is an atom, with two twists. `q` is a `unit`, Hoon's

105equivalent of a nullable pointer or a Haskell `Maybe`. If `q`

101equivalent of a nullable pointer or a Haskell `Maybe`. If `q`

@@ -161,7 +157,7 @@ statically, by casting through the empty aura `@`. Hoon is not

161dependently typed and can't statically enforce data constraints

157dependently typed and can't statically enforce data constraints

162(for example, it can't enforce that a `@tas` is really a symbol).

158(for example, it can't enforce that a `@tas` is really a symbol).

163

159

164−### `{$core p/span q/(map term span)}

160+### `{$core p/span q/(map term span)}`

165

161

166A `$core` is a code-data cell. The data (or *payload*) is the

162A `$core` is a code-data cell. The data (or *payload*) is the

167tail; the code (or *battery*) is the head. `p`, a span, is the

163tail; the code (or *battery*) is the head. `p`, a span, is the

docs/hoon/syntax.md+1−1

@@ -9,7 +9,7 @@ title: Syntax

9Hoon's semantics are simple, but unusual. Hoon's syntax is

10complex, and unusual. Sorry.

11

12−## Motivation

12+# Motivation

13

14An excuse: the normal human brain doesn't have hardware support

15for math, but it does have hardware support for syntax. Learning

docs/hoon/twig/atom.md+1−1

@@ -1,6 +1,6 @@

1---

2sort: 1

3−next: true

3+

4---

5

6# Atoms and strings

docs/hoon/twig/atom/knit.md+1−1

@@ -1,6 +1,6 @@

1---

2sort: 3

3−next: true

3+

4---

5

6# `:knit`

docs/hoon/twig/atom/rock.md+1−1

@@ -1,6 +1,6 @@

1---

2sort: 2

3−next: true

3+

4---

5

6# `:rock`

docs/hoon/twig/atom/sand.md+2−2

@@ -1,9 +1,9 @@

1---

2sort: 1

3−next: true

3+

4---

5

6−# `:sand``

6+# `:sand`

7

8`{$sand p/term q/@}`; a constant, warm atom.

9

docs/hoon/twig/bar-core.md+2−2

@@ -1,9 +1,9 @@

1---

2sort: 5

3−next: true

3+

4---

5

6−# Cores (`|` runes)

6+# Core, `|` ("bar")

7

8Core twigs are flow twigs. The compiler essentially pins a Nock

9formula, or battery of formulas, to the subject.

docs/hoon/twig/bar-core/cab-door.md+1

@@ -1,5 +1,6 @@

1---

2sort: 5

3+

3---

4---

4

5

5# `:door |_ "buccab"`

6# `:door |_ "buccab"`

docs/hoon/twig/bar-core/cen-core.md+1

@@ -1,5 +1,6 @@

1---

2sort: 1

3+

3---

4---

4

5

5# `:core |% "barcen"`

6# `:core |% "barcen"`

docs/hoon/twig/bar-core/dot-trap.md+1

@@ -1,5 +1,6 @@

1---

2sort: 3

3+

3---

4---

4

5

5# `:trap. |. "bardot"`

6# `:trap. |. "bardot"`

docs/hoon/twig/bar-core/hep-loop.md+1

@@ -1,5 +1,6 @@

1---

2sort: 4

3+

3---

4---

4

5

5# `:loop |- "barhep"`

6# `:loop |- "barhep"`

docs/hoon/twig/bar-core/tis-gate.md+1

@@ -1,5 +1,6 @@

1---

2sort: 2

3+

3---

4---

4

5

5# `:gate |= "bartis"`

6# `:gate |= "bartis"`

docs/hoon/twig/buc-mold.md+2−2

@@ -1,9 +1,9 @@

1---

2sort: 7

3−next: true

3+

4---

5

6−# Molds (`$` runes)

6+# Mold, `$` ("buc")

7

8A *mold* is a `gate` (function) that helps us build simple and

9rigorous data structures. (In fact, since "mold" sounds nasty,

docs/hoon/twig/buc-mold/base.md+2−2

@@ -1,11 +1,11 @@

1---

2sort: 1

3−next: true

3+

4---

5

6# `:base`

7

8−`{$base p/$@(?($noun $cell $bean $null) {$atom p/aura})}`: atom mold

8+`{$base p/$@(?($noun $cell $bean $null) {$atom p/aura})}`: trivial molds.

9

10## Produces

11

docs/hoon/twig/buc-mold/cen-book.md+1−1

@@ -1,6 +1,6 @@

1---

2sort: 4

3−next: true

3+

4---

5

6# `:book $% "buctis"`

docs/hoon/twig/buc-mold/col-bank.md+1−1

@@ -1,6 +1,6 @@

1---

2sort: 2

3−next: true

3+

4---

5

6# `:bank $: "buccol"`

docs/hoon/twig/buc-mold/hep-lamb.md+2−2

@@ -1,9 +1,9 @@

1---

2sort: 8

3−next: true

3+

4---

5

6−# `:lamb $-, "buchep"

6+# `:lamb $-, "buchep"`

7

8`{$lamb p/moss q/moss}`: mold which normalizes to an example gate.

9

docs/hoon/twig/buc-mold/ket-bush.md+1−1

@@ -1,6 +1,6 @@

1---

2sort: 6

3−next: true

3+

4---

5

6# `:bush $^ "bucket"`

docs/hoon/twig/buc-mold/pat-claw.md+2−2

@@ -1,9 +1,9 @@

1---

2sort: 5

3−next: true

3+

4---

5

6−# `:claw $@ "bucpat"

6+# `:claw $@ "bucpat"`

7

8`{$claw p/moss q/moss}`: mold which normalizes a union tagged by depth.

9

docs/hoon/twig/buc-mold/tis-coat.md+1−1

@@ -1,6 +1,6 @@

1---

2sort: 3

3−next: true

3+

4---

5

6# `:coat $= "buctis"`

docs/hoon/twig/buc-mold/wut-pick.md+2−2

@@ -1,9 +1,9 @@

1---

2sort: 7

3−next: true

3+

4---

5

6−# `:pick $? "bucwut"

6+# `:pick $? "bucwut"`

7

8`{$pick p/(list moss)}`: mold which normalizes a general union.

9

docs/hoon/twig/cen-call.md+6−8

@@ -1,16 +1,14 @@

1---

2sort: 6

3−next: true

3+

4---

5

6−# Make and call, `%`

6+# Call, `%` ("cen")

7

8−We've already covered the irregular-only twigs `$wing` and

8+We've already covered `$wing` and `$limb`. These are simple

9−`$limb`. These are simple forms of the *invocation* family of

9+forms of the *invocation* family of twigs, `%`, whose general

10−twigs, `%`, whose general form is `$make`, `%=`.

10+form is `$make`, `%=`.

11

12## Stems

13

14−<list dataPreview="true" className="runes" linkToFragments="true"></list>

14+<list dataPreview="true" className="runes"></list>

15−

16−<kids className="runes"></kids>

docs/hoon/twig/cen-call/cab-keep.md+1

@@ -1,5 +1,6 @@

1---

2sort: 2

3+

3---

4---

4

5

5# `:keep %_ "cencab"`

6# `:keep %_ "cencab"`

docs/hoon/twig/cen-call/sig-open.md+1−1

@@ -2,7 +2,7 @@

2sort: 3

3---

4

5−# `:open %~ "censig"

5+# `:open %~ "censig"`

6

7`{$cnsg p/wing q/seed r/seed}`: call with multi-armed door.

8

docs/hoon/twig/col-cell.md+1−1

@@ -1,6 +1,6 @@

1---

2sort: 3

3−next: true

3+

4---

5

6# Cells, `:` ("col")

docs/hoon/twig/col-cell/ket-conq.md+1−1

@@ -2,7 +2,7 @@

2sort: 3

3---

4

5−# `:conq :^ "colket"

5+# `:conq :^ "colket"`

6

7`{$conq p/seed q/seed r/seed s/seed}`: construct a quadruple (4-tuple).

8

docs/hoon/twig/dot-nock.md+3−5

@@ -1,14 +1,12 @@

1---

2sort: 10

3−next: true

3+

4---

5

6−# Intrinsics (`.` runes)

6+# Nock, `.` (dot)

7

8Anything Nock can do, Hoon can do also.

9

10## Twigs

11

12−<list dataPreview="true" className="runes" linkToFragments="true"></list>

12+<list dataPreview="true" className="runes"></list>

13−

14−<kids className="runes"></kids>

docs/hoon/twig/ket-cast.md+3−5

@@ -1,9 +1,9 @@

1---

2sort: 9

3−next: true

3+

4---

5

6−# Type manipulation (`^` runes)

6+# Cast, `^` ("ket")

7

8`$cast`, `$like`, and `$name` let us adjust spans without

9violating type constraints.

@@ -13,6 +13,4 @@ it never allows invalid nests, it sometimes rejects valid nests.

13

14## Twigs

15

16−<list dataPreview="true" className="runes" linkToFragments="true"></list>

16+<list dataPreview="true" className="runes"></list>

17−

18−<kids className="runes"></kids>

docs/hoon/twig/ket-cast/bar-iron.md+1−1

@@ -2,7 +2,7 @@

2sort: 5

3---

4

5−# `:iron ^| "ketbar"

5+# `:iron ^| "ketbar"`

6

7`{$iron p/seed}`: convert a gold core to an iron core (contravariant).

8

docs/hoon/twig/ket-cast/lus-like.md+1−1

@@ -2,7 +2,7 @@

2sort: 1

3---

4

5−# `:like ^+ "ketlus"

5+# `:like ^+ "ketlus"`

6

7`{$like p/seed q/seed}`: typecast by example (seed).

8

docs/hoon/twig/ket-cast/sig-burn.md+1−1

@@ -2,7 +2,7 @@

2sort: 6

3---

4

5−# `:burn ^~ "ketsig"

5+# `:burn ^~ "ketsig"`

6

7`{$burn p/seed}`: fold constant at compile time.

8

docs/hoon/twig/ket-cast/wut-lead.md+1−1

@@ -2,7 +2,7 @@

2sort: 4

3---

4

5−# `:lead ^? "ketwut"

5+# `:lead ^? "ketwut"`

6

7`{$lead p/seed}`: convert any core to a lead core (bivariant).

8

docs/hoon/twig/limb.md−1

@@ -1,6 +1,5 @@

1---

2sort: 2

3−next: true

4---

3---

5

4

6# Limbs and wings

5# Limbs and wings

docs/hoon/twig/limb/limb.md+1−1

@@ -1,6 +1,6 @@

1---

2sort: 1

3−next: true

3+

4---

5

6# `:limb`

docs/hoon/twig/limb/wing.md+1−2

@@ -1,6 +1,5 @@

1---

2sort: 2

3−next: true

4---

3---

5

4

6# `:wing`

5# `:wing`

@@ -25,7 +24,7 @@ Irregular: `a.b` finds limb `a` within limb `b` of the subject.

25

24

26It may be slightly hard to follow the formal definition above.

25It may be slightly hard to follow the formal definition above.

27

26

28−Intuitively that Hoon wings are written in the opposite order

27+Intuitively, Hoon wings are written in the opposite order

29from attribute dot-paths in most languages. Hoon `a.b.c` is Java

28from attribute dot-paths in most languages. Hoon `a.b.c` is Java

30`c.b.a`; it means "a within b within c."

29`c.b.a`; it means "a within b within c."

31

30

docs/hoon/twig/sem-make.md+3−5

@@ -1,14 +1,12 @@

1---

2sort: 11

3−next: true

3+

4---

5

6−# Random macros (`;` runes)

6+# Make, `;` ("sem")

7

8Miscellaneous useful macros.

9

10## Twigs

11

12−<list dataPreview="true" className="runes" linkToFragments="true"></list>

12+<list dataPreview="true" className="runes"></list>

13−

14−<kids className="runes"></kids>

docs/hoon/twig/sig-hint.md+3−5

@@ -1,15 +1,13 @@

1---

2sort: 12

3−next: true

3+

4---

5

6−# Hints (`~` runes)

6+# Hints, `~` ("sig")

7

8Twigs that use Nock `10` to pass non-semantic info to the

9interpreter.

10

11## Twigs

12

13−<list dataPreview="true" className="runes" linkToFragments="true"></list>

13+<list dataPreview="true" className="runes"></list>

14−

15−<kids className="runes"></kids>

docs/hoon/twig/sig-hint/fas-funk.md+2−1

@@ -1,7 +1,8 @@

1---

2sort: 1

3+---

3

4

4−# `:funk ~/ "sigfas"

5+# `:funk ~/ "sigfas"`

5

6

6`{$funk p/term q/seed}`: jet registration for gate with

7`{$funk p/term q/seed}`: jet registration for gate with

7registered context.

8registered context.

docs/hoon/twig/tis-flow.md+3−5

@@ -1,9 +1,9 @@

1---

2sort: 4

3−next: true

3+

4---

5

6−# Subject flow (`=` runes)

6+# Flow, `=` ("tis")

7

8Flow twigs change the subject. (Or more precisely, a flow twig

9compiles at least one of its subtwigs with a different subject.)

@@ -30,6 +30,4 @@ There are many flow stems, all small variations on these three.

30

31## Twigs

32

33−<list dataPreview="true" className="runes" linkToFragments="true"></list>

33+<list dataPreview="true" className="runes"></list>

34−

35−<kids className="runes"></kids>

docs/hoon/twig/tis-flow/lus-pin.md+1−1

@@ -2,7 +2,7 @@

2sort: 3

3---

4

5−# `:pin =+ "tislus"

5+# `:pin =+ "tislus"`

6

7`{$pin p/seed q/seed}`: combine a new noun with the subject.

8

docs/hoon/twig/wut-test.md+2−5

@@ -1,9 +1,8 @@

1---

2sort: 8

3−next: true

4---

3---

5

4

6−# Tests (`?` runes)

5+# Test, `?` ("wut")

7

6

8Hoon has the usual branches and logical tests. For pattern

7Hoon has the usual branches and logical tests. For pattern

9matching, it also has a `$fits` twig that tests whether a value

8matching, it also has a `$fits` twig that tests whether a value

@@ -28,6 +27,4 @@ side is taken), it fails with an error.

28

27

29## Twigs

28## Twigs

30

29

31−<list dataPreview="true" className="runes" linkToFragments="true"></list>

30+<list dataPreview="true" className="runes"></list>

32−

33−<kids className="runes"></kids>

docs/hoon/twig/wut-test/gar-sure.md+1−1

@@ -2,7 +2,7 @@

2sort: 11

3---

4

5−# `:sure ?< "wutgar"

5+# `:sure ?< "wutgar"`

6

7`{$sure p/seed q/seed}`: positive assertion.

8

docs/hoon/twig/wut-test/hep-case.md+1−1

@@ -4,7 +4,7 @@ sort: 12

4

5# `:case ?- "wuthep"`

6

7−`{$case p/wing q/(list (pair moss seed))}` Switch against a

7+`{$case p/wing q/(list (pair moss seed))}`: switch against a

8union, with no default.

9

10## Expands to

docs/hoon/twig/wut-test/pam-and.md+1−1

@@ -2,7 +2,7 @@

2sort: 8

3---

4

5−# `:and ?& "wutpam"

5+# `:and ?& "wutpam"`

6

7`{$and p/(list seed)}`: logical and.

8

docs/hoon/twig/wut-test/tis-fits.md+1−1

@@ -2,7 +2,7 @@

2sort: 6

3---

4

5−# `:fits ?= "wuttis"

5+# `:fits ?= "wuttis"`

6

7`{$fits p/moss q/wing}`: test pattern match.

8

docs/hoon/twig/zap-wild.md+3−5

@@ -1,12 +1,10 @@

1---

2sort: 13

3−next: true

3+

4---

5

6−# Special tools (`!` runes)

6+# Wild, `!` ("zap")

7

8## Twigs

9

10−<list dataPreview="true" className="runes" linkToFragments="true"></list>

10+<list dataPreview="true" className="runes"></list>

11−

12−<kids className="runes"></kids>

docs/using/install.md+6−7

@@ -7,13 +7,12 @@ navhome: /main

7

8# Install

9

10−<div class="row"><div class="col-md-8">

10+Urbit is designed to run on any Unix box with an internet connection. Debian

11+(jessie), OS X, FreeBSD and Fedora all work well.

11

12

12−Urbit is designed to run on any Unix box with an internet connection. Debian, OS X, FreeBSD and Fedora all work well.

13+Urbit is alpha software. It’s not yet completely stable, its crypto hasn’t

13−

14−Urbit is alpha software. It’s not yet completely stable, its crypto hasn’t been audited and there are plenty of rough edges. Urbit is lots of fun to play with, but not quite ready for your important or sensitive data. Just so you know what you're getting into.

14+been audited, and there are plenty of rough edges. Urbit is lots of fun to play

15−

15+with, but not quite ready for your important or sensitive data.

16−</div></div>

17

16

18## Build from source

17## Build from source

19

18

@@ -80,4 +79,4 @@ Once your dependencies are installed the rest is easy:

80 make

79 make

81 curl -o urbit.pill https://bootstrap.urbit.org/latest.pill

80 curl -o urbit.pill https://bootstrap.urbit.org/latest.pill

82

81

83−After running `make` your Urbit executable lives at `bin/urbit`. The `.pill` file is a compiled binary of Arvo that Urbit uses to bootstrap itself.

82+After running `make`, your Urbit executable lives at `bin/urbit`. The `.pill` file is a compiled binary of Arvo that Urbit uses to bootstrap itself.