git.iko.soy/urbit.org
on master help sign in
Merge pull request #1034 from urbit/auras-ref

auras reference

commitb498d0f954ab525f0860f77b057a69866b98ece1 authorpoprox <51337059+drbeefsupreme@users.noreply.github.com> dateTue 16 Mar 2021, 13:07 (6 years ago) parent24747348b34d79
3 files changed+83
compare with master
unifiedsplit
hoon/hoon-school/atoms-auras-and-simple-cell-types.md+2 hoon/reference/_index.md+4 hoon/reference/auras.md+77
hoon/hoon-school/atoms-auras-and-simple-cell-types.md+2
@@ -109,6 +109,8 @@ Aura Meaning Example Literal Syntax
109109
110110Some of these auras nest under others. For example, `@u` is for all unsigned auras. But there are other, more specific auras; `@ub` for unsigned binary numbers, `@ux` for unsigned hexadecimal numbers, etc.
111111
112+For a more complete list of auras, see [Auras](@/docs/hoon/reference/auras.md).
113+
112114## Aura Inference in Hoon
113115
114116Let's do more examples in the Dojo using the `?` operator. We'll focus on just the unsigned auras for now:
hoon/reference/_index.md+4
@@ -31,6 +31,10 @@ A simplified explanation of Hoon's type system.
3131
3232The full story on Hoon's type system.
3333
34+## [Auras](@/docs/hoon/reference/auras.md)
35+
36+A list of aura types for atoms.
37+
3438### [Runes](@/docs/hoon/reference/rune/_index.md)
3539
3640Syntax and semantics for Hoon's rune system.
hoon/reference/auras.mdnew file+77
@@ -0,0 +1,77 @@
1++++
2+title = "Auras"
3+weight = 70
4+template = "doc.html"
5++++
6+
7+Auras are system of nested "soft types" on [atoms](@/docs/glossary/atom.md) that
8+are used to track metadata about how a particular atom is to be interpreted.
9+This is used for type checking as well as pretty printing.
10+
11+A given aura nests under any aura whose name is a substring of the given aura,
12+i.e. `@ux` nests under `@u`, and all auras nest under the empty aura `@`. We
13+call auras "soft types" since this nesting behavior can be ignored - see
14+[below](#non-coercive).
15+
16+You can learn more about auras in [Hoon school](@/docs/hoon/hoon-school/atoms-auras-and-simple-types.md).
17+
18+```
19+Aura Meaning Example Literal Syntax
20+-------------------------------------------------------------------------
21+@ empty aura
22+@c Unicode codepoint ~-~45fed
23+@d date
24+ @da absolute date ~2018.5.14..22.31.46..1435
25+ @dr relative date (ie, timespan) ~h5.m30.s12
26+@f Loobean (for compiler, not castable) &
27+@i Internet address
28+ @if IPv4 address .195.198.143.90
29+ @is IPv6 address .0.0.0.0.0.1c.c3c6.8f5a
30+@n nil (for compiler, not castable) ~
31+@p phonemic base (ship name) ~sorreg-namtyv
32+@q phonemic base, unscrambled .~litsyn-polbel
33+@r IEEE-754 floating-point
34+ @rh half precision (16 bits) .~~3.14
35+ @rs single precision (32 bits) .6.022141e23
36+ @rd double precision (64 bits) .~6.02214085774e23
37+ @rq quad precision (128 bits) .~~~6.02214085774e23
38+@s signed integer, sign bit low
39+ @sb signed binary --0b11.1000
40+ @sd signed decimal --1.000.056
41+ @sv signed base32 -0v1df64.49beg
42+ @sw signed base64 --0wbnC.8haTg
43+ @sx signed hexadecimal -0x5f5.e138
44+@t UTF-8 text (cord) 'howdy'
45+ @ta ASCII text (knot) ~.howdy
46+ @tas ASCII text symbol (term) %howdy
47+@u unsigned integer
48+ @ub unsigned binary 0b11.1000
49+ @ud unsigned decimal 1.000.056
50+ @uv unsigned base32 0v1df64.49beg
51+ @uw unsigned base64 0wbnC.8haTg
52+ @ux unsigned hexadecimal 0x5f5.e138
53+```
54+
55+Capital letters at the end of auras indicate the bitwidth in binary powers of
56+two, starting from A.
57+
58+```
59+ @ubD signed single-byte (8-bit) decimal
60+ @tD 8-bit ASCII text
61+ @rhE half-precision (16-bit) floating-point number
62+ @uxG unsigned 64-bit hexadecimal
63+ @uvJ unsigned, 512-bit integer (frequently used for entropy)
64+```
65+
66+### Non-coercive
67+
68+Auras are non-coercive, but conversions may have to go via the empty aura, e.g.
69+```
70+> ^-(@ud ^-(@ 'foo'))
71+7.303.014
72+```
73+This is implicitly done by the irregular form of `^-`.
74+```
75+> `@ud`'foo'
76+7.303.014
77+```