git.iko.soy/urbit.org
on 01ac191 help sign in
urbit.org/docs/programming/hoon/twig/atom.md
110 lines 3.1 kB history raw
1---
2sort: 1
3next: true
4---
6# Atoms, constants, quasi-constants
8A constant is a twig whose product does not depend on the
9subject. If you know Nock, the formula produced is always
10is always `[1 constant]`.
12(Some of the "constant" syntax below can interpolate dynamic
13twigs. When it does, it obviously isn't constant at all.)
15## Twigs
17```
18|%
19++ twig
20 {$rock p/@tas q/@}
21 {$sand p/@tas q/@}
22 {$knit p/(list $@(@ {$~ p/twig}))}
23 {$path p/(list (each @tas twig))
24--
25```
27## Syntax
29All Hoon constants are irregular; they have no rune form. The
30stems described below are `$rock` (cold / constant), `$sand`
31(warm / open), `$knit` (iterative string), and `$path` (Unix
32style path).
34### Atoms
36Recall the `$atom` span, `{$atom p/aura q/(unit @)}`.
38Each atom constant syntax implies an aura. Note that the aura is
39used indiscriminately to convey physical units, semantic
40interpretations, parsing syntax, and/or printing syntax.
42### Hardcoded auras
44### Cold or warm, single or arbitrary
46A span is a set of nouns; an `$atom` span contains either one
47atom (*cold*) or all atoms (a *warm*).
49In general, the `%` prefix is added to indicate coldness. `42`
50is warm and `%42` is cold. `@tas` symbols (which start with `%`
51already, see below) are always cold.
53### Unsigned integer: `@ud`, `@ux`, `@uw`.
55Unsigned integers are broken into groups of 3 for decimals, and 4
56for non-decimals, separated German style by `.`; `420` plus `999`
57is `1.419`, a `@ud`.
59A hex (`@ux`) favorite is `0xcafe.babe`.
61`0w` is base64: `0-9`, `a-z` + 10, `A-Z` + 36, `-` and `~`. For
62giant numbers, you can put whitespace/newlines after the `.`.
64### Boolean and null: `@f`, `@n`.
66Booleans in Hoon (`@f`) are `&` for yes (`@f`) and `|` for no.
67Remember that `&` is `0` and `|` is `1` (which is why we say
68"yes" and "no" rather than "true" and "false").
70Nil (aura `@n`) is `~` (with the value `0`).
72### Atomic string
74`'text'` in single quotes, `@t`, is a UTF-8 string LSB first.
76`%symbol`, `@tas`, containing only `a-z`, `0-9` and `-`, starting
77with `a-z`, and ending with `a-z0-9`, is a valid symbolic name.
79`%$` is an empty `@tas`, ie, `0` with span `@tas`.
81### Signed integer: `@sd`
83Signed integers (`@sd`) are encoded with sign bit *low*. This
84means we need a special syntax for positive signed integers,
85since their atomic value can't be their unsigned value. For
86example, `-3` is the atom `7`, whereas `--3` encodes to `6`.
88### Iterative string
90Hoon also has list-shaped strings (less compact, more editable).
91Use double quotes: `"hello, world"`. The mold is `tape` or
92`(list char)`, where `char` is a UTF-8 byte.
94Within a quoted string, interpolate with `{}`: `"hello, {(weld
95"wo" "rld")}"`. It's also worth noting that `<`, `gar`, and `>`,
96`gal` (angle brackets) stringify any twig: `"hello, {<mul 6
977>}"`. (Obviously, an interpolated string is not a constant.)
99### Path
101The path `/foo/bar/baz` is the constant `[%foo %bar %baz ~]`.
102A path can be dynamically interpolated with `[]`:
104```
105/foo/[:(if & %bar %rab)]/baz`
106```
108equals `/foo/bar/baz`.