git.iko.soy/urbit.org
on master help sign in
runes page
5fad682Galen Wolfe-Pauly
docs/system/hoon/runes.md+74−113
compare with master
unifiedsplit
@@ -5,119 +5,80 @@ sort: 1
5Runes
5Runes
6=====
6=====
7
7
8−<list></list>
8+#### Make friends with them.
9+
10+This is the full list of runes.
11+
12+<div class="book">
13+
14+## `$ buc` (molds)
15+
16+<list dataPath="docs/system/hoon/runes/bc" dataPreview="true" className="runes" childIsFragment="true"></list>
17+
18+---
19+
20+## `| bar` (cores)
21+
22+<list dataPath="docs/system/hoon/runes/br" dataPreview="true" className="runes" childIsFragment="true"></list>
23+
24+---
25+
26+## `: col` (tuples)
27+
28+<list dataPath="docs/system/hoon/runes/cl" dataPreview="true" className="runes" childIsFragment="true"></list>
29+
30+---
31+
32+## `% cen` (invocations)
33+
34+<list dataPath="docs/system/hoon/runes/cn" dataPreview="true" className="runes" childIsFragment="true"></list>
35+
36+---
37+
38+## `. dot` (nock)
39+
40+<list dataPath="docs/system/hoon/runes/dt" dataPreview="true" className="runes" childIsFragment="true"></list>
41+
42+---
43+
44+## `# hax` (printing)
45+
46+<list dataPath="docs/system/hoon/runes/hx" dataPreview="true" className="runes" childIsFragment="true"></list>
47+
48+---
49+
50+## `^ ket` (casting)
51+
52+<list dataPath="docs/system/hoon/runes/kt" dataPreview="true" className="runes" childIsFragment="true"></list>
53+
54+---
55+
56+## `~ sig` (hints)
57+
58+<list dataPath="docs/system/hoon/runes/sg" dataPreview="true" className="runes" childIsFragment="true"></list>
9
59
10---
60---
11
61
12−Rune basics
62+## `; sem` (composition)
13−-----------
63+
14−
64+<list dataPath="docs/system/hoon/runes/sm" dataPreview="true" className="runes" childIsFragment="true"></list>
15−For example, the rune `?:`, pronounced "wutcol", is a rune that accepts
65+
16−three `++twig` expressions to form an "if-then-else statement," where
66+---
17−`p` is the predicate, `q` is the "then" statement, and `r` is the "else"
67+
18−statement:
19−
20− [%wtcl p=twig q=twig r=twig]
21−
22−In a program, it is used like so:
23−
24− ++ add
25− |= [a=@ b=@]
26− ^- @
27− ?: =(0 a) b
28− $(a (dec a), b +(b))
29−
30−Here the `=(0 a)` is `p`, the `b` is `q`, and the bottom line is the
31−`r`.
32−
33−There are several benefits to using runes in lieu of reserved words.
34−First, it prevents the programmer from accidentally misusing a reserved
35−word as a variable name, which also allows her to be sure that any word
36−in her progam is an identifier. Next, as the first ASCII symbol of the
37−rune digraphs bears semantic significance, the programmer can look at
38−any rune and immediately have a basic, intuitive understanding as to
39−what it does.
40−
41−Next, rune syntax addresses several issues that arise in other
42−languages. First, it produces cleaner, less verbose code that
43−conveniently flows downward. To highlight the verbosity Hoon avoids by
44−implementing runes, here is the C equivalent of the `++add` source code
45−printed above:
46−
47− attribute add {
48− function(left-operand: atom, right-operand: atom)
49− produce atom
50− if equals(0, left-operand) {
51− right-operand
52− } else {
53− recurse(left-operand (decrement left-operand)),
54− right-operand (increment right-operand))
55− }
56− }
57−
58−What is more, Hoon solves two problems that arise in functional
59−programming languages with very deep expression trees: first, the
60−collection of huge piles of closing parens at the end of large blocks;
61−and second, the fact that the depth of expression trees are thus bounded
62−by the width of the text box, as subexpressions tend to be indented.
63−Some languages solve the bracket-terminator problem by parsing
64−whitespace in order to use indentation to express tree depth:
65−
66− ?:
67− &
68− 47
69− 52
70−
71−While this is actually valid Hoon, it does not solve the width problem.
72−
73−To address this problem, most Hoon `++twigs` have a short, fixed
74−fan-out. Thus, the parser does not need significant whitespace nor a
75−terminator to determine how many twigs follow a `?:`--it already knows
76−that the answer is three. A smart parser allows the Hoon programmer to
77−format her code using a [backstep pattern]() that allows her to descend
78−into a deep tree without losing right margin.
79−
80−Lastly, but perhaps most significantly, code is meant to be seen, and
81−not read. Anyone who has even slight experience coding Hoon will tell
82−you that they can understand and connect with properly formatted Hoon
83−code on a deeper, more intuitive level that cannot be explained but must
84−be experienced. One doesn't read `++add`, she sees it.
85−
86−Names and Categories
87−--------------------
88−
89−While the second glyph in a rune means little or nothing, the first
90−defines a rough semantic category:
91−
92− | bar Core construction
93− $ buc Tile construction
94− % cen Invocations
95− : col Tuple construction
96− . dot Nock operations
97− # hax Pretty printing
98− ^ ket Type conversions
99− ; sem Composers (and XML generators)
100− ~ sig Hints
101− = tis Subject modifiers
68+## `= tis` (subject modifiers)
102− ? wut Conditionals, booleans, and tests
69+
103− ! zap Special operations
70+<list dataPath="docs/system/hoon/runes/ts" dataPreview="true" className="runes" childIsFragment="true"></list>
104−
71+
105−As shown above, each glyph has its own monosyllabic name, designed to be
72+---
106−pronounced quickly in combination with another glyph to form a rune
73+
107−name. As languages are often read-aloud, this saves the programmer from
74+## `? wut` (conditional)
108−having to say "dollar sign, question mark"--"bucwut" is much more
75+
109−compact.
76+<list dataPath="docs/system/hoon/runes/wt" dataPreview="true" className="runes" childIsFragment="true"></list>
110−
77+
111−Irregular pronuncations
78+---
112−-----------------------
79+
113−
80+## `! zap` (special)
114−To avoid a few tongue-twisters, some runes have irregular pronunciations
81+
115−that should be noted:
82+<list dataPath="docs/system/hoon/runes/zp" dataPreview="true" className="runes" childIsFragment="true"></list>
116−
83+
117− -- hephep phep
84+</div>
118− +- lushep slep
119− ++ luslus slus
120− == tistis stet
121−
122−Note: these runes are not members of any of the categories above, but
123−are mostly used to....
docs/system/hoon/runes/basics.mdnew file+116
@@ -0,0 +1,116 @@
1+--
2+sort: 0
3+---
4+
5+Rune basics
6+-----------
7+
8+For example, the rune `?:`, pronounced "wutcol", is a rune that accepts
9+three `++twig` expressions to form an "if-then-else statement," where
10+`p` is the predicate, `q` is the "then" statement, and `r` is the "else"
11+statement:
12+
13+ [%wtcl p=twig q=twig r=twig]
14+
15+In a program, it is used like so:
16+
17+ ++ add
18+ |= [a=@ b=@]
19+ ^- @
20+ ?: =(0 a) b
21+ $(a (dec a), b +(b))
22+
23+Here the `=(0 a)` is `p`, the `b` is `q`, and the bottom line is the
24+`r`.
25+
26+There are several benefits to using runes in lieu of reserved words.
27+First, it prevents the programmer from accidentally misusing a reserved
28+word as a variable name, which also allows her to be sure that any word
29+in her progam is an identifier. Next, as the first ASCII symbol of the
30+rune digraphs bears semantic significance, the programmer can look at
31+any rune and immediately have a basic, intuitive understanding as to
32+what it does.
33+
34+Next, rune syntax addresses several issues that arise in other
35+languages. First, it produces cleaner, less verbose code that
36+conveniently flows downward. To highlight the verbosity Hoon avoids by
37+implementing runes, here is the C equivalent of the `++add` source code
38+printed above:
39+
40+ attribute add {
41+ function(left-operand: atom, right-operand: atom)
42+ produce atom
43+ if equals(0, left-operand) {
44+ right-operand
45+ } else {
46+ recurse(left-operand (decrement left-operand)),
47+ right-operand (increment right-operand))
48+ }
49+ }
50+
51+What is more, Hoon solves two problems that arise in functional
52+programming languages with very deep expression trees: first, the
53+collection of huge piles of closing parens at the end of large blocks;
54+and second, the fact that the depth of expression trees are thus bounded
55+by the width of the text box, as subexpressions tend to be indented.
56+Some languages solve the bracket-terminator problem by parsing
57+whitespace in order to use indentation to express tree depth:
58+
59+ ?:
60+ &
61+ 47
62+ 52
63+
64+While this is actually valid Hoon, it does not solve the width problem.
65+
66+To address this problem, most Hoon `++twigs` have a short, fixed
67+fan-out. Thus, the parser does not need significant whitespace nor a
68+terminator to determine how many twigs follow a `?:`--it already knows
69+that the answer is three. A smart parser allows the Hoon programmer to
70+format her code using a [backstep pattern]() that allows her to descend
71+into a deep tree without losing right margin.
72+
73+Lastly, but perhaps most significantly, code is meant to be seen, and
74+not read. Anyone who has even slight experience coding Hoon will tell
75+you that they can understand and connect with properly formatted Hoon
76+code on a deeper, more intuitive level that cannot be explained but must
77+be experienced. One doesn't read `++add`, she sees it.
78+
79+Names and Categories
80+--------------------
81+
82+While the second glyph in a rune means little or nothing, the first
83+defines a rough semantic category:
84+
85+ | bar Core construction
86+ $ buc Tile construction
87+ % cen Invocations
88+ : col Tuple construction
89+ . dot Nock operations
90+ # hax Pretty printing
91+ ^ ket Type conversions
92+ ; sem Composers (and XML generators)
93+ ~ sig Hints
94+ = tis Subject modifiers
95+ ? wut Conditionals, booleans, and tests
96+ ! zap Special operations
97+
98+As shown above, each glyph has its own monosyllabic name, designed to be
99+pronounced quickly in combination with another glyph to form a rune
100+name. As languages are often read-aloud, this saves the programmer from
101+having to say "dollar sign, question mark"--"bucwut" is much more
102+compact.
103+
104+Irregular pronuncations
105+-----------------------
106+
107+To avoid a few tongue-twisters, some runes have irregular pronunciations
108+that should be noted:
109+
110+ -- hephep phep
111+ +- lushep slep
112+ ++ luslus slus
113+ == tistis stet
114+
115+Note: these runes are not members of any of the categories above, but
116+are mostly used to....