git.iko.soy/urbit.org
on master help sign in
lus runes
commite215c37bc8c5b44c8bf6926c368ffcf3d72ebb2c authorjoshuareagan <joshuareagan@gmail.com> dateFri 12 Oct 2018, 14:44 (8 years ago) parent5a942e0
5 files changed+204
compare with master
unifiedsplit
docs/reference/rune/lus.udon+18 docs/reference/rune/lus/bar.udon+54 docs/reference/rune/lus/bus.udon+44 docs/reference/rune/lus/lus.udon+41 docs/reference/rune/lus/tar.hoon+47
docs/reference/rune/lus.udonnew file+18
@@ -0,0 +1,18 @@
1+:- :~ navhome/'/docs/'
2+ next/'true'
3+ sort/'8'
4+ title/'Arms + ("lus")'
5+ ==
6+;>
7+
8+# Arms `+` "lus"
9+
10+A core is a cell of `[battery payload]`. The battery is made of one or more arms, each of which is a computation on its parent core.
11+
12+Arm runes are used to define arms in a core, and thus can only be used from within an expression that produces a multi-arm core. That means arm runes cannot be used to mark the beginning of a first-class expression -- there is no such thing in Hoon as an arm without a core.
13+
14+There are various arm runes you can use to produce different kinds of arms. Normal arms use `++`; arms defining a structure (or 'mold') use `+$`; and constructor arms use `+*`.
15+
16+## Runes
17+
18+;list(datapreview "true", classname "runes");
docs/reference/rune/lus/bar.udonnew file+54
@@ -0,0 +1,54 @@
1+:- :~ navhome/'/docs/'
2+ next/'true'
3+ sort/'4'
4+ title/'+| "lusbar"'
5+ ==
6+;>
7+
8+# `+| "lusbar"`
9+
10+Chapter label.
11+
12+## Syntax
13+
14+Regular: *1-fixed*.
15+
16+```
17++| %label
18+```
19+
20+## Discussion
21+
22+The `+|` doesn't produce an arm. It instead provides a label for the arms that follow it. The arms of a core can be divided into *chapters* for 'organization'. Chapter labels aren't part of the underlying noun of the core; they're stored as type system metadata only.
23+
24+See `tome` in the Hoon standard library.
25+
26+## Examples
27+
28+Let's look at what the Hoon compiler's parser, `ream`, does with the `+|` rune:
29+
30+```
31+> (ream '|% +| %numbers ++ two 2 ++ three 3 --')
32+[ %brcn
33+ p=~
34+ q
35+ { [ p=%numbers
36+ q=[p=~ q={[p=%three q=[%sand p=%ud q=3]] [p=%two q=[%sand p=%ud q=2]]}]
37+ ]
38+ }
39+]
40+```
41+
42+Notice that `p.q` has the label `%numbers`. Contrast with:
43+
44+```
45+> (ream '|% ++ two 2 ++ three 3 --')
46+[ %brcn
47+ p=~
48+ q
49+ { [ p=%$
50+ q=[p=~ q={[p=%three q=[%sand p=%ud q=3]] [p=%two q=[%sand p=%ud q=2]]}]
51+ ]
52+ }
53+]
54+```
docs/reference/rune/lus/bus.udonnew file+44
@@ -0,0 +1,44 @@
1+:- :~ navhome/'/docs/'
2+ next/'true'
3+ sort/'2'
4+ title/'+$ "lusbus"'
5+ ==
6+;>
7+
8+# `+$ "lusbus"`
9+
10+Produce a structure arm (type definition).
11+
12+## Syntax
13+
14+Regular: *2-fixed*.
15+
16+```
17++$ p=term q=spec
18+```
19+
20+`p` is an arm name, and `q` is any structure expression.
21+
22+## Discussion
23+
24+Arms produced by `+$` are essentially type definitions. They should be used when one wants to define custom types using core arms.
25+
26+The Hoon subexpression, `q`, must be a structure expression. That is, it must be either a basic structure expression (`*`, `~`, `^`, `?`, and `@`), or a complex expression made with the `$` family of runes (including irregular variants). Names of structures are also permitted (e.g., `tape`).
27+
28+## Examples
29+
30+```
31+> =c |%
32+ +$ atom-pair $:(@ @)
33+ +$ flag-atom $:(? @)
34+ --
35+
36+> `atom-pair.c`[12 14]
37+[12 14]
38+
39+> `atom-pair.c`[12 [22 33]]
40+nest-fail
41+
42+> `flag-atom.c`[& 22]
43+[%.y 22]
44+```
docs/reference/rune/lus/lus.udonnew file+41
@@ -0,0 +1,41 @@
1+:- :~ navhome/'/docs/'
2+ next/'true'
3+ sort/'1'
4+ title/'++ "luslus"'
5+ ==
6+;>
7+
8+# `++ "luslus"`
9+
10+Produce a normal arm.
11+
12+## Syntax
13+
14+Regular: *2-fixed*.
15+
16+```
17+++ p=term q=hoon
18+```
19+
20+`p` is the arm name, and `q` is any Hoon expression.
21+
22+## Discussion
23+
24+All arms must have a name (e.g., `add`). An arm is computed by name resolution. (This resolution is implicit in the case of `$` arms. See `|=`, `|-`, and `|^`.) The `++` rune is used for explicitly giving a name to an arm.
25+
26+Any Hoon expression, `q`, may be used to define the arm computation.
27+
28+## Examples
29+
30+```
31+> =c |%
32+ ++ two 2
33+ ++ increment |=(a=@ +(a))
34+ --
35+
36+> two.c
37+2
38+
39+> (increment.c 11)
40+12
41+```
docs/reference/rune/lus/tar.hoonnew file+47
@@ -0,0 +1,47 @@
1+:- :~ navhome/'/docs/'
2+ next/'true'
3+ sort/'3'
4+ title/'+* "lustar"'
5+ ==
6+;>
7+
8+# `+* "lustar"`
9+
10+Produce a type constructor arm.
11+
12+## Syntax
13+
14+Regular: *2-fixed*.
15+
16+```
17++* p=term [q=term] r=spec
18+```
19+
20+`p` is the arm name, `q` is the name of the argument for the constructor function enclosed in square brackets, and `r` is a structure expression that defines the constructor function.
21+
22+## Discussion
23+
24+Arms produced by `+*` are essentially type constructors. They are used to construct new types from ones you already have. Consider `list`, which takes some type -- e.g., `@`, `tape`, etc. -- and returns a new type, e.g., `(list @)`, `(list tape)`, etc.
25+
26+The Hoon subexpression, `r`, must be a structure expression. That is, it must be either a basic structure expression (`*`, `~`, `^`, `?`, and `@`), or a complex expression made with the `$` family of runes (including irregular variants).
27+
28+## Examples
29+
30+```
31+> =c |%
32+ +* triple [a] [a a a]
33+ +* wrap-flag [a] [? a]
34+ --
35+
36+> `(triple.c @)`[12 14 16]
37+[12 14 16]
38+
39+> `(triple.c ?)`[12 14 16]
40+nest-fail
41+
42+> `(triple.c ?)`[& | |]
43+[%.y %.n %.n]
44+
45+> `(wrap-flag.c @)`[& 22]
46+[%.y 22]
47+```