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