git.iko.soy/urbit.org
on 01ac191 help sign in
urbit.org/docs/programming/hoon/concepts.md
227 lines 8.8 kB history raw
1---
2sort: 3
3next: true
4title: Concepts
5---
7# Concepts and terminology
9Usually, a new language is an improvement on one you already
10know. If it isn't, it probably at least shares concepts with a
11large family of relatives. These concepts come with words, like
12*type* or *function*, that map cleanly onto its semantics.
14In Hoon we throw away almost all these words and invent new
15ones, which mean almost the same things. But why?
17## Motivation
19Hoon has no close relatives. The normal jargon of programming
20maps poorly onto its semantics. For example, although Hoon is a
21typed language, the term "type" is not formally defined in Hoon.
22"Type" is a great word, but Hoon has three quite separate
23concepts which could comfortably claim it. We say "type" all the
24time; we mean `span`, or `mold`, or `mark`, or possibly all
25three.
27Other common programming concepts used only informally in Hoon
28are "function," "object," "event," "expression," "variable,"
29"label," "closure", "environment," "scope," and probably a few
30more. We do use these words informally, but we're always making
31an analogy whose precision depends on context.
33## Overview
35This document is a quick overview of Hoon, structured as a
36glossary of a few major concepts: `noun` (data), `nock`
37(interpreter), `mint` (compiler), `span` (type), `twig`
38(expression), `gate` (function), `mold` (constructor), `core`
39(object), `mark` (protocol).
41### `noun` (data value)
43A value in Hoon is called a [`noun`](noun). A noun is either a
44unsigned integer of any size (`atom`), or an ordered pair of any
45two nouns (`cell`). Nouns are like Lisp S-expressions, but
46simpler (Lisp atoms effectively have dynamic type bits).
48The simplest noun syntax uses brackets, like `[a b]` for the cell
49of `a` and `b`. Brackets nest right; `[a b c d]` is `[a [b [c
50d]]]`. You'll also see braces: `{a b c d}`.
52A noun list, by convention, points right and is zero-terminated.
53Hoon uses tuples (improper nouns) more freely than Lisp; only
54genuinely iterative structures are null-terminated lists.
56When an atom is used as a string (a `cord`), the bytes are always
57UTF-8 in LSB first order. When you see `foo`, `$foo`, `%foo`,
58etc, this refers to the integer `0x6f.6f66`, aka `7.303.014`.
59(Hoon syntax breaks integer atoms in the German style.)
61One common operation on nouns is `slot`, a tree addressing
62scheme which maps an atom to a subtree. The whole noun is slot
63`1`; the left child of `n` is `2n`, the right child `2n+1`.
65### `nock` (interpreter)
67Hoon compiles itself to the [Nock](../nock) VM. Nock is a
68Turing-complete, non-lambda combinator function. The function
69takes a cell `{subject formula}`, and produces a noun `product`.
71To program in Hoon, this is all you need to know about Nock. But
72it's still fun and useful to [learn more](../nock).
74## Compilation concepts
76### `mint` (compiler)
78[`mint`](mint) is the Hoon compiler. It maps a cell `{span twig}` to a
79cell `{span nock}`, where a `span` is a type, a `twig` is a compiled
80expression (AST), and a `nock` is a Nock formula. `mint` accepts
81a subject type and a source expression; it produces a product type
82and an executable formula.
84Calculating the output type from the input type and the source
85code is called "type inference." If you've used another typed
86functional language, like Haskell, Hoon's type inference does the
87same job but with less intelligence.
89Haskell infers backward and forward; Hoon only infers forward.
90Hoon can't figure out the type of a noun from how you use it,
91only from how you make it. Hoon can infer tail recursion, but
92not head recursion.
94Low-powered type inference means you need more type annotations,
95which makes your program more readable anyway. Also, the dumber
96the compiler, the easier it is for a dumb human to understand
97what the compiler is thinking.
99### `twig` (expression)
101A [`twig`](twig) is a Hoon AST node, the result of parsing a
102source expression. A Hoon source file encodes one twig.
104As the noun that the parser produces, a twig is a tagged union of
105the form `{stem bulb}`, where `stem` (the tag) is a `cord` which
106controls the type of `bulb` (the data).
108As text, each twig has both regular and irregular syntax forms.
109Regular syntax can be either *tall* or *flat*: multiline or
110single-line. Irregular syntax is always flat. Tall twigs can
111contain flat twigs, but not vice versa.
113Regular forms always start with a *sigil*, which is either a
114*keyword* or a *rune* at the programmer's choice. A keyword is
115the stem cord,
117For most stems, tall regular form has no delimiter or terminator,
118eliminating the `)))))` problem common in functional languages.
119Hoon also uses an unusual "backstep" indentation pattern to
120control left-margin drift.
122Hoon is mildly whitespace-sensitive. It knows the difference
123between no whitespace, one-space, and more-space. But all cases
124of more-space mean the same thing. Flat syntax uses one-space,
125tall syntax more-space.
127As an example, the regular flat keyword syntax `:call(a b)` means
128the same thing as the flat rune syntax `%-(a b)`, the tall
129keyword syntax
131```
132:call a
134```
135or the tall rune syntax (here on one line, with double spaces):
136```
137:- a b
138```
140### `span` (type, as range)
142A [`span`](span) is a Hoon type. It defines a set (finite or
143infinite) of nouns and ascribes some semantics to it. There is
144no syntax for spans; they are always defined by inference (ie, by
145`mint`), usually using a constructor (`mold`).
147### `gate` (function)
149A `gate` is a Hoon function (lambda or closure). Other
150constructs Urbit are functions in the mathematical sense -- for
151instance, a Nock formula is also a function. But a gate is not a
152formula. The gate's argument is its *sample*; the result is its
153*product*.
155### `core` (object)
157A `core` has no exact equivalent in conventional languages, but
158the closest equivalent is an object. An object has methods; a
159core has functionally computed attributes (*arms*). An arm that
160produces a gate is the Hoon equivalent of a conventional method;
161think of it as a computed attribute whose value is a lambda.
163A gate is a special case of a core: a core with one arm, whose
164name is the empty string. The shape of a core is `[battery
165payload]`, where *battery* is a tree of Nock formulas
167### `mold` (type, as constructor)
169A `mold` is a constructor function (`gate`). Its sample is any
170noun; its product is a structured noun. A mold is idempotent;
171`(mold (mold x))` always equals `(mold x)`.
173Since there's no such thing as a span declaration, we use molds
174to define useful spans by example; we also use them to validate
175untrusted network input.
177### `face` (named variable)
179In a conventional language, we have a scope, environment or
180symbol table. Declaring a variable, like `var foo: atom`, adds
181the name `foo` to the table with type `atom`.
183The Hoon equivalent is `:var foo atom`. But Hoon has a
184homoiconic heap; there is no inscrutable scope or environment.
185There is just the subject, which is one noun. To "declare a
186variable" is to make a cell `[variable old-subject]`, and use it
187as the subject of the twig below.
189So the label `foo` isn't a key in a symbol table; it's in the
190type (`span`) of the new value. It's not a variable named `foo`,
191whose value is of type `atom`; it's a subtree of type `foo:atom`.
193### `limb` (attribute or variable reference)
195A [`limb`](limb), like `foo`, is Hoon's equivalent of a variable
196reference. A limb is a twig; given a subject span, `mint`
197resolves it to a Nock formula and a product span.
199To resolve limb `foo`, `mint` searches the subject depth-first,
200head-first for either a `face` named `foo`, or a `core` with the
201arm `foo`. If it finds a face, the product is a *leg*, or
202subtree of the subject. If it finds a core, it computes the arm
203formula with that core as the subject.
205A limb can also be a slot (direct tree address), like `+15`.
207### `wing` (limb path)
209A wing is a list of limbs. Like attribute references in a
210conventional language, it uses the syntax `a.b.c`, but inside
211out: Hoon `a.b.c` means "a within b within c", the equivalent of
212`c.b.a` in any other language. All limbs but the last, here `a`,
213must be legs.
215### `mark` (type, as protocol name)
217A `mark` (really an Arvo concept, not a Hoon concept) is Urbit's
218version of a MIME type, if a MIME type was an executable
219specification. The mark is just a label that's used as a path to
220a local source file in the Arvo filesystem. This source file
221defines a core that can mold untrusted data, diff and patch,
222convert to other marks, etc.
224If this sounds like magic, it isn't quite magic. There's no way
225for different urbits to make sure they mean the same thing by the
226same mark. However, when incompatibility happens, marks ensure
227that we at least handle the situation in a predictable way.