7Since Everything in Hoon is a natural number, the interpreter needs to
8know both how to render them and subject them to type enforcement.
9Odors, which are just ASCII spans beginning with a `@`, carry all of the
10information necessary for the interpreter to do this. For instance, the
11interpreter knows to render an atom of odor `@t` as UTF-8 text.
13The span composing the Odor consists of two parts: a lowercase prefix
14carrying type information, and an upper-case suffix containing
15information about its size. The prefix is a taxonomy that grows more
16specific to the right. For example, atoms of the odor `@ta` are URL-safe
17ASCII text, and Atoms of the odor `@tas` are the more specific subset of
18ASCII text that is acceptable in hoon.
20The general principle of type enforcement is that atoms change freely
21either up or down the taxonomy, but not across. You can treat a `@tas`
22as a `@t`, as in a strong type system; but you can also treat a `@t` as
23a `@tas`, or an `@` as anything. However, passing a `@t` to a function
24that expects an `@ux` is a type error.
28For example, you can cast a `@t` to a `@tas`, or vice-versa:
30 ~zod/try=> =a `@t`'permitted'
36However, you cannot pass a `@ux` to a function that expects a `@t`
37without casting it to a `@` first:
39 ~zod/try=> (|=(a=@t [%foo a]) 0x20)
43 ~zod/try=> (|=(a=@t [%foo a]) `@t`a)
46Note that when explicitly casting a `@ux` to a `@t`, the interpreter
47automatically casts the `@ux` to a `@` first.
49Comprehensive list of the Hoon Odors
50------------------------------------
55 @dr relative date (ie, timespan)
56 @f yes or no (inverse boolean)
59 @r IEEE floating-point
60 @rd double precision (64 bits)
61 @rh half precision (16 bits)
62 @rq quad precision (128 bits)
63 @rs single precision (32 bits)
64 @s signed integer, sign bit low
69 @sx signed hexadecimal
72 @tas ASCII symbol (term)
78 @ux unsigned hexadecimal
83The suffix of an odor, if present, is a single upper-case character A-Z
84`c`, which indicates the size of an atom. This is possible, because in
85Hoon, a letter maps to an ASCII code number, thus a number.
87Size is specified in bits in the form of `1 << (c - 'A')` resp. `2^c`,
88since most data aligns to the power of 2 or can be composed of such
91The size of a block of size `N` can be calculated for example using
92`(bex (sub 'N' 'A'))` in bits or `(div (bex (sub 'N' 'A')) 8)` in bytes.
94Thus, `@tD` is one UTF-8 byte (whatever that means) and `@tN` is 1
95kilobyte or less of UTF-8.
126It is possible to construct an atom bigger than 4Mb in size, but the
127type system would not be able to express an odor size for it.
129There is also the datatype `++bloq` to hold a to-the-power-of block size
130(though it is just an alias for `@`).
132------------------------------------------------------------------------
138Atoms of the odor `@c` represent Unicode text, constructed with a UTF-32
139bytestream, with the lowest-significant bit first. Although we usually
140use a UTF-8 bytestream, sometimes it's useful to build atoms of one or
152 ~zod/try=> ~-i~2764.u
154 ~zod/try=> (tuft ~-i~2764.u)
156 ~zod/try=> `@ux`~-foo
157 0x6f.0000.006f.0000.0066
158 ~zod/try=> `@ux`~-i~2764.u
159 0x75.0000.2764.0000.0069
160 ~zod/try=> `@ux`(tuft ~-i~2764.u)
163------------------------------------------------------------------------
173Atoms of the odor `@da` represent absolute Urbit dates. Urbit dates
174represent 128-bit chronological time, with 2\^64 seconds from the start
175of the universe. For example, 2\^127 is 3:30:08 PM on December 5, AD
176226. The time of day and/or second fragment is optional. As the last
177example shows, BC times are also possible.
181`~~[year].[month].[date]..[hour].[minute].[second]..[millisecond]`
183Note: the time of day and/or millisecond fragment is optional.
189 ~zod/try=> ? ~2014.1.1
192 ~zod/try=> ~2014.1.1..01.01.01
194 ~zod/try=> ? ~2014.1.1..01.01.01
197 ~zod/try=> ~2014.1.1..01.01.01..1234
198 ~2014.1.1..01.01.01..1234
199 ~zod/try=> `@da`(bex 127)
201 ~zod/try=> `@da`(dec (bex 127))
202 ~226.12.5..15.30.07..ffff.ffff.ffff.ffff
203 ~zod/try=> `@ux`~2013.12.7
204 0x8000.000d.2140.7280.0000.0000.0000.0000
205 ~zod/try=> `@ux`~2013.12.7..15.30.07
206 0x8000.000d.2141.4c7f.0000.0000.0000.0000
207 ~zod/try=> `@ux`~2013.12.7..15.30.07..1234
208 0x8000.000d.2141.4c7f.1234.0000.0000.0000
209 ~zod/try=> `@ux`~2013.12.7..15.30.07..1234
210 0x8000.000d.2141.4c7f.1234.0000.0000.0000
212------------------------------------------------------------------------
216Relative date (ie, timespan)
218Atoms of the odor `@dr` atoms represent basic time intervals in
219milliseconds. There are no `@dr` intervals under a second or over a day
224`~d[day].h[hour]m[minute].s[second]..[fractionals]`
226Note: Every measurement is optional, so long as those that are present
227are in order. The largest measurement is preceded by a `~`.
231 ~zod/try=> ~d1.h19.m5.s29
233 ~zod/try=> ? ~d1.h19.m5.s29
236 ~zod/try=> `@dr`(div ~s1 1.000)
237 ~.s0..0041.8937.4bc6.a7ef
238 ~zod/try=> ~d1.h19.m5.s29..0041
241 0x1.0000.0000.0000.0000
243 0x3c.0000.0000.0000.0000
244 ~zod/try=> `@dr`(div ~d1 5)
246 ~zod/try=> (div ~m1 ~s1)
248 ~zod/try=> (div ~h1 ~m1)
250 ~zod/try=> (div ~h1 ~s1)
252 ~zod/try=> (div ~d1 ~h1)
254 ~zod/try=> `@da`(add ~2013.11.30 ~d1)
257------------------------------------------------------------------------
261Loobean(inverse boolean)
263Atoms of the odor `@f` represent loobeans, where `0` is yes and `1` is
264no. Loobeans are often represented in their cubic and runic forms shown
269`0`, `1` as numbers. `%.y`, `%.n` as [`%cube`]()s. `&`, `|` as short
288------------------------------------------------------------------------
294Atoms of the odor `@n` indicate an absence of information, as in a list
295terminator. The only value is `~`, which is just `0`.
305------------------------------------------------------------------------
311Atoms of `@p` are primarily used to represent ships names, but they can
312be used to optimize any short number for memorability. For example, it
313is great for checksums.
319Every syllable is a byte. Pairs of two bytes are separated by `-`, and
320phrases of four pairs are separated by `--`.
327 ~zod/try=> `@p`0x4321
329 ~zod/try=> `@p`0x8765.4321
331 ~zod/try=> `@p`0x8766.4321
333 ~zod/try=> `@p`(shaf %foo %bar)
334 ~ralnyl-panned-tinmul-winpex--togtux-ralsem-lanrus-pagrup
336------------------------------------------------------------------------
342Hoon does not yet support floating point, so these syntaxes don't work
343yet. But the syntax for a single-precision float is the normal English
344syntax, with a `.` prefix:
346------------------------------------------------------------------------
350Signed integer, sign bit low
352Without finite-sized integers, the sign extension trick obviously does
353not work. A signed integer in Hoon is a different way to use atoms than
354an unsigned integer; even for positive numbers, the signed integer
355cannot equal the unsigned.
357The prefix for a negative signed integer is a single `-` before the
358unsigned syntax. The prefix for a positive signed integer is `--`. The
359least significant represents the sign. The representation is similar to
366Atoms of the odor `@sb` represent signed binary numbers.
370`-0b[negative_binary]` `--0b[postive_binary]`
379 ~zod/try=> `@sd`--0b1
381 ~zod/try=> `@sd`--0b11
383 ~zod/try=> `@sb`(sum:si -0b10 -0b10)
386------------------------------------------------------------------------
392Atoms of odor `@sd` represent signed decimal numbers.
396`-[negative[decimal]()]` `--[postive_[decimal]()]`
408 ~zod/try=> (sum:si -234 --234)
411------------------------------------------------------------------------
417Atoms of odor `@sv` represent signed base32 numbers.
421`-0v[negative_base32]` The digits are, in order, `0-9`, `a-v`.
422`--0v[positive_base32]`
435 ~zod/try=> `@sd`--0vb
437 ~zod/try=> `@sd`(sum:si -0vv --0vb)
440------------------------------------------------------------------------
446Atoms of odor `@sw` represent base64 numbers.
450`-0w[negative_base64]` The digits are, in order, `0-9`, `a-z`,
451`A-Z`,`-`, and `~`. `--0w[positive_base64]` The digits are, in order,
461 ~zod/try=> `@sd`(sum:si -0w-A -0w--)
468Atoms of odor `@sx` represent signed hexadecimal numbers.
472`-[negative_hexadecimal]` `--[positive_hexadecimal]`
478 ~zod/try=> `@sd`--0x17
480 ~zod/try=> `@ux`(bex 20)
482 ~zod/try=> 0x10. 0000
484 ~zod/try=> `@sd`(sum:si --0x17 -0x0)
486 ~zod/try=> `@sd`(sum:si --0x17 -0xa)
489------------------------------------------------------------------------
495Atoms of the odor `@t` represent a
496[cord](http://en.wikipedia.org/wiki/Rope_data_structure), sequence of
497UTF-8 bytes, LSB first. It is sometimes called a cord.
514------------------------------------------------------------------------
520Atoms of the odor `@ta` represent the ASCII text subset used in hoon
521literals: `a-z`, `0-9`, `~`, `-`, `.`, `_`.
525`~.[text]` There are no escape sequences.
534 ~zod/try=> `@t`~.asdf
537------------------------------------------------------------------------
543Atoms of `@tas` represent [`++term`]()s, the most exclusive text odor.
544The only characters permitted are lowercase ASCII, except as the first
545or last character, and 0-9, except as the first character.
549`%[text]` This means a term is always [cubical]().
553 ~zod/try=> %dead-fish9
555 ~zod/try=> -:!>(%dead-fish9)
556 [%cube p=271.101.667.197.767.630.546.276 q=[%atom p=%tas]]
558------------------------------------------------------------------------
564------------------------------------------------------------------------
570Atoms of the odor `@ub` represent unsigned binary numbers.
574`0b[number]` Numbers are least-significant bit first.
588------------------------------------------------------------------------
594Atoms of `@ud` represent unsigned decimal numbers. It is the default
595print format for both `@u` and and `@u`, namely unsigned numbers with no
596printing preference, as well as opaque atoms.
600Numbers of more than three digits must be delimited by `.`s. Whitespace
601and linebreaks can appear between the dot and the next group.
617------------------------------------------------------------------------
623Atoms of the odor `@uv` represent unsigned base64 numbers.
627`0v[number]` The digits are, in order, `0-9`, `a-v`.
636 ~zod/try=> `@ud`(add 0vv 0v9)
639------------------------------------------------------------------------
647`ow[number]` The digits are, in order, `0-9`, `a-z`, `A-Z`,`-`, and `~`.
656 ~zod/try=> `@uv`(add 0w~ 0wZ)
658 ~zod/try=> `@ud``@uv`(add 0w~ 0wZ)
661------------------------------------------------------------------------
667Atoms of the odor `@ux` represent hexadecimal numbers.
671`0x`number. Numbers with more than four digits must be delimited by
672`.`s. Hex digits are lowercase only.
681 ~zod/try=> `@ux`(bex 20)
683 ~zod/try=> 0x10. 0000
686------------------------------------------------------------------------
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