git.iko.soy/urbit.org
on 4191825 help sign in
urbit.org/docs/programming/concepts.md
213 lines 8.2 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, and 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.
84### `twig` (expression)
86A [`twig`](twig) is a Hoon AST node, the result of parsing a
87source expression. A Hoon source file encodes one twig.
89As the noun that the parser produces, a twig is a tagged union of
90the form `{stem bulb}`, where `stem` (the tag) is a `cord` which
91controls the type of `bulb` (the data).
93As text, each twig has both regular and irregular syntax forms.
94Regular syntax can be either *tall* or *flat*: multiline or
95single-line. Irregular syntax is always flat. Tall twigs can
96contain flat twigs, but not vice versa.
98Regular forms always start with a *sigil*, which is either a
99*keyword* or a *rune* at the programmer's choice. A keyword is
100the stem cord,
102For most stems, tall regular form has no delimiter or terminator,
103eliminating the `)))))` problem common in functional languages.
104Hoon also uses an unusual "backstep" indentation pattern to
105control left-margin drift.
107Hoon is mildly whitespace-sensitive. It knows the difference
108between no whitespace, one-space, and more-space. But all cases
109of more-space mean the same thing. Flat syntax uses one-space,
110tall syntax more-space.
112As an example, the regular flat keyword syntax `:call(a b)` means
113the same thing as the flat rune syntax `%-(a b)`, the tall
114keyword syntax
116```
117:call a
119```
120or the tall rune syntax (here on one line, with double spaces):
121```
122:- a b
123```
125### `span` (type, as range)
127A [`span`](span) is a Hoon type. It defines a set (finite or
128infinite) of nouns and ascribes some semantics to it. There is
129no syntax for spans; they are always defined by inference (ie, by
130`mint`), usually using a constructor (`mold`).
132### `gate` (function)
134A `gate` is a Hoon function (lambda or closure). Other
135constructs Urbit are functions in the mathematical sense -- for
136instance, a Nock formula is also a function. But a gate is not a
137formula. The gate's argument is its *sample*; the result is its
138*product*.
140### `core` (object)
142A `core` has no exact equivalent in conventional languages, but
143the closest equivalent is an object. An object has methods; a
144core has functionally computed attributes (*arms*). An arm that
145produces a gate is the Hoon equivalent of a conventional method;
146think of it as a computed attribute whose value is a lambda.
148A gate is a special case of a core: a core with one arm, whose
149name is the empty string. The shape of a core is `[battery
150payload]`, where *battery* is a tree of Nock formulas
152### `mold` (type, as constructor)
154A `mold` is a constructor function (`gate`). Its sample is any
155noun; its product is a structured noun. A mold is idempotent;
156`(mold (mold x))` always equals `(mold x)`.
158Since there's no such thing as a span declaration, we use molds
159to define useful spans by example; we also use them to validate
160untrusted network input.
162### `face` (named variable)
164In a conventional language, we have a scope, environment or
165symbol table. Declaring a variable, like `var foo: atom`, adds
166the name `foo` to the table with type `atom`.
168The Hoon equivalent is `:var foo atom`. But Hoon has a
169homoiconic heap; there is no inscrutable scope or environment.
170There is just the subject, which is one noun. To "declare a
171variable" is to make a cell `[variable old-subject]`, and use it
172as the subject of the twig below.
174So the label `foo` isn't a key in a symbol table; it's in the
175type (`span`) of the new value. It's not a variable named `foo`,
176whose value is of type `atom`; it's a subtree of type `foo:atom`.
178### `limb` (attribute or variable reference)
180A [`limb`](limb), like `foo`, is Hoon's equivalent of a variable
181reference. A limb is a twig; given a subject span, `mint`
182resolves it to a Nock formula and a product span.
184To resolve limb `foo`, `mint` searches the subject depth-first,
185head-first for either a `face` named `foo`, or a `core` with the
186arm `foo`. If it finds a face, the product is a *leg*, or
187subtree of the subject. If it finds a core, it computes the arm
188formula with that core as the subject.
190A limb can also be a slot (tree address), like `+15`, which
191takes a leg directly.
193### `wing` (limb path)
195A wing is a list of limbs. Like attribute references in a
196conventional language, it uses the syntax `a.b.c`, but inside
197out: Hoon `a.b.c` means "a within b within c", the equivalent of
198`c.b.a` in any other language. All limbs but the last, here `a`,
199must be legs.
201### `mark` (type, as protocol name)
203A `mark` (really an Arvo concept, not a Hoon concept) is Urbit's
204version of a MIME type, if a MIME type was an executable
205specification. The mark is just a label that's used as a path to
206a local source file in the Arvo filesystem. This source file
207defines a core that can mold untrusted data, diff and patch,
208convert to other marks, etc.
210If this sounds like magic, it isn't quite magic. There's no way
211for different urbits to make sure they mean the same thing by the
212same mark. However, when incompatibility happens, marks ensure
213that we at least handle the situation in a predictable way.