5title: Atoms, auras, types
8# Urbyte 1: atoms, auras, types
10Thanks for reading Urbyte 0! In Urbyte 1, we'll look a little
11more deeply at atoms and other simple noun types.
13Let's restart our engines:
16$ urbit -FI ~zod myship
18ames: on localhost, UDP 31337.
19http: live (insecure, public) on 8080
20http: live ("secure", public) on 8443
21http: live (insecure, loopback) on 12321
27It seems limiting to have only one kind of atom, the unsigned
28decimal. How are signed integers represented? Symbols?
29Floating-point values? Dates? IP addresses? Even just hex?
31Lisp's S-expression, with its own cells and atoms, is very
32similar to Hoon's nouns. But languages in the Lisp family mark
33each atom with a dynamic tag that defines the atom's meaning.
34These tags are effectively dynamic types.
36Hoon also tracks the meaning of atoms. But Hoon is statically
37typed, so an atom description is obviously a type. An atomic type
38in Hoon is called an *aura*. The aura syntax is just an ASCII
39string starting with `@`, like `@ud` for unsigned decimal.
41Hoon has a wide (but not extensible) variety of atom syntaxes.
42Each syntax for an atom produces an appropriate predefined aura.
43And Hoon's printer can invertibly print any aura Hoon can parse.
44Because atoms make great path nodes and paths make great URLs,
45all regular atom syntaxes use only URL-safe characters.
49With the dojo command `? expression`, you tell the dojo to print
50both the product of the expression, and the product's type.
52Let's type in some aura examples:
78So decimal is aura `@ud`, hexadecimal is `@ux`. Note the cast
79syntax, which lets us change the type of an atom, converting hex
80`0x42` to a decimal `66`.
82An aura is soft type. The programmer can always insist on how
83to interpret an atom. Hoon doesn't have "dependent types"; it
84can't enforce any constraints the aura puts on the atom's value.
113`--7` means "positive 7." `+7` might have been better, but `+`
116Hoon needs `--` to distinguish positive signed numbers because
117Hoon's type system doesn't feed back into its parser. The
118expression itself needs to control whether it's `@sd` or `@ud`.
120With unlimited atom width, traditional sign extension makes no
121sense. The sign bit is the low bit. Even atoms are positive,
122odd atoms are negative.
124And Hoon has no overloading or type detection; we need to use a
125different function to add signed integers. We'll always choose
126slightly clunkier syntax in exchange for much simpler semantics.
152The `@t` aura is UTF-8 text, with the first byte low. Again,
153Hoon doesn't actually have the power to check statically that
154your UTF-8 is valid. Auras don't tell you what an atom is, just
157The familiar single-quote syntax for `@t` is an irregular form of
158the more unusual `~~` prefix. The `~.` prefix, aura `@ta`, is
159restricted to lowercase ASCII (a great common denominator). Of
160course, `~` is URL-safe and `'` is not.
162### Dates, floats, IP addresses...
167~2016.7.11..01.32.04..2c0d
1750x5460.0000.0000.0000.0000
179170.141.184.502.236.089.414.812.327.632.537.911.296
182~2016.7.11..07.32.28..842f
193`@da` is a 128-bit absolute date (64 bits for fractions of a
194second, 64 bits for seconds); `@dr` is a relative date; `@rs` is
195a single-precision IEEE real; `@if` is an IPv4 address. This is
196not all Hoon's aura syntax, just a good range of examples.
198`(add ~h6 now)` is a good example of the use and limits of
199the aura system. Unlike the signed-integer sum, offsetting a
200date can use plain atomic addition. But the product of `add` is
201a flavorless atom with no aura, `@`. So we have to cast it back
202to an absolute date `@da`.
206Does an aura represent the units of the atom, its syntax, its
207semantics, its constraints?
209Any or all of the above. Programmers can even use their own aura
210strings, which nothing in Hoon recognizes. The set of syntaxes
211that Hoon knows how to parse and/or print is fixed. But there
212are plenty of good reasons to use your own user-defined auras.
214If your program uses both fortnights and furlongs, Hoon will not
215parse a user-defined fortnight syntax. It will not print furlongs
216in the dojo. But the type system will keep you from accidentally
217passing a furlong to a function that expects a fortnight.
219Hoon does interpret the aura string in one way: auras specialize
220to the right. For example, `@u` is any unsigned integer; `@ux`
221is an unsigned integer that likes to be printed as hex.
223Hoon's typechecker lets you go up or down the specialization
224ladder. It complains if you try to move across. For example,
225`@u` can silently convert into `@ux` or `@ux` into `@u`, but
226turning `@ud` into `@ux`, `@ux` into `@da`, etc, requires an
229## Constants, symbols, loobeans and null
231An atom type isn't just an aura. There's another choice: the
232type can be *general* and contain all atoms (like the types we've
233seen above), or *constant* and contain just one atom.
235A type describes a set of values. While auras may informally
236describe a format for which not all atoms are valid, any atom can
237be cast into the aura whether valid or invalid. But in a
238constant, the type contains just one atom.
240The regular syntax for an atomic constant is just to put `%` on
241front of the constant. Like:
257The `$` on the type indicates the constant. Note that constants
258still have auras; `~h6` (6 hours) is still a `@dr`.
262There are a few special forms worth learning early: symbols,
263null, loobeans, and of course ships:
302`%symbol` is a constant with aura `@tas` (text, ASCII, symbol).
303The symbol rules, which are enforced by the Hoon parser but not
304(as we've discussed) the type system: a symbol is lowercase with
305infix hyphens ("kebab-case").
307Loobeans are not true and false, but yes (`.y` or `&`) and no
308(`.n` or `|`). This is because *yes is zero and no is one*.
309This makes sense at a certain mathematical level, though it
310was probably a mistake from a practical perspective.
312`~` is Hoon's nil: constant `0`, aura `@n`.
314And of course, `@p` is the phonemic base used for ship names.
315(It's useful for any kind of memorable number.)
319Naturally, all these atoms fit neatly into cells, and retain
320their types within the cells.
323> ? [~h6 [.3.14 %foo] 0xdead.beef]
325[~h6 [.3.14 %foo] 0xdead.beef]
327> `*`[~h6 [.3.14 %foo] 0xdead.beef]
328[398.449.671.992.126.314.905.600 [1.078.523.331 7.303.014] 3.735.928.559]
331Another fun trick is to cast any noun to the `*` type, ie,
332generic noun. We then know nothing about the noun, so we print
333all its atoms as decimals.
337And we're done! Press `^D` to exit:
344## Questions and/or exercises
346As always, these questions are optional and only for fun.
348We didn't include anywhere near all Hoon's auras or syntaxes in
349this lesson. It's just a set of examples.
351Try using the dojo's magic error erasure to stumble around the
352rest of Hoon's atom syntax. Any string that can't be extended
353into a valid expression will be trimmed back, with a beep, until
354it can. Return will beep if the expression is not complete.
355This feedback is harmless and does not use an electric shock.
356It enables stochastic reinforcement learning of Hoon syntax.
358If `~h6` is six hours, how do you write forty-five minutes? Two
359days, six hours and forty-five minutes?
361What would you expect the syntax for double-precision float to
362be? What about base64?
364Does an absolute date have to include every zillisecond, or can
365it be pruned to a day or a year?
367If there's an IP syntax, what about bitcoin addresses? What
368other auras do you think should be supported?
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list