git.iko.soy/urbit.org
on 6d45ede help sign in
urbit.org/docs/hoon/twig.md
75 lines 2.8 kB history raw
1---
2navhome: /docs
3sort: 6
4next: true
5title: Expressions
6---
8# Expressions
10A Hoon expression is called a `twig`. A `twig` is an AST node:
11the noun that the Hoon compiler makes when it parses a source
12expression.
14The definition of `twig` is the definition of Hoon. So let's
15define the syntax and semantics of Hoon, a twig at a time. But
16first, basic twig anatomy.
18## Twig anatomy and jargon
20A twig is a tagged union (`book`) with the form `{stem bulb}`,
21where the `stem` is an atomic symbol. The bulb for each stem has
22its own type, which varies by stem. (Compare with Lisp, where
23every AST node is a tag and a list of child nodes.)
25There are no user-level macros. All stems are built into Hoon.
26Most stems are implemented as internal macros, however.
28The bulb is usually a tuple, sometimes a list or map. An element
29of this structure is a *subexpression* or just *leg*.
31Usually a subexpression is itself a `twig`; sometimes it's a
32`@tas` (symbol) or a `wing` (reference path).
34## Moldy moss; woody seed
36When defining each page in the `twig` book, we never use `twig`
37itself as a leg. Instead, we use the mold `moss` to describe
38twigs whose product is used as a mold, and `seed` for twigs whose
39product could be anything. Both `moss` and `seed` are just
40aliases for `twig`, but they serve as documentation.
42For adjectives, we say *moldy* and *woody* respectively. An
43example of X is the woody form of X; a mold producing X is its
44moldy form.
46For instance, `[%foo %bar]` is woody: a twig producing the noun
47`[7.303.014 7.496.034]`. `{$foo $bar}` is moldy: a twig
48producing a function whose product is always `[7.303.014
497.496.034]`.
51This mold, of course, is a noun (a gate). The value of that noun
52is not `[7.303.014 7.496.034]`, or anything remotely like it.
53The noun is a pile of code. It is probably a big pile of code,
54because most cores include a lot of formulas, contexts, etc,
55generally including the whole standard library. (Having a
56pointer to the standard library does not burden a noun much,
57unless of course you're trying to print that noun and you don't
58have a span that describes it.)
60And of course, Hoon is a functional language, so seeds sometimes
61produce a mold -- because we do pass around functions as values.
62Don't worry about this issue. It will totally make sense soon.
64But writing `[%foo %bar]` where you mean `{$foo $bar}`, or the
65reverse, is a common beginner's mistake in Hoon. At least it
66always results in a compiler error (since the noun types are so
67different). There's really no way around learning not to make
68this mistake the hard way, but designating subexpressions as
69`moss` or `seed` can't hurt.
71## Twig categories
73Most twigs fit into clear categories by meaning and rune prefix:
75<div><list/></div>