12 1 :: A noun is an atom or a cell.
13 2 :: An atom is a natural number.
14 3 :: A cell is an ordered pair of nouns.
16An **atom** is a natural number - ie, an unsigned integer. Nock does not
17limit the size of **atoms**, or know what an **atom** means.
19For instance, the **atom** `97` might mean the number `97`, or it might
20mean the letter `a` (ASCII 97). A very large **atom** might be the
21number of grains of sand on the beach - or it might be a GIF of your
22children playing on the beach. Typically when we represent strings or
23files as **atoms**, the first byte is the low byte. But even this is
24just a convention. An **atom** is an **atom**.
26A **cell** is an ordered pair of any two **nouns** - **cell** or
27**atom**. We group cells with square brackets:
34*Nouns* are the dumbest data model ever. **Nouns** make JSON look like
35XML and XML look like ASN.1. It may also remind you of Lisp's
36S-expressions - you can think of nouns as "S-expressions without the S."
38To be exact, a *noun* is an S-expression, except that classic
39S-expressions have multiple **atom** types ("S" is for "symbol"). Since
40Nock is designed to be used with a higher-level type system (such as
41Hoon's), it does not need low-level types. An **atom** is just an
42unsigned integer of any size.
44For instance, it's common to represent strings (or even whole text
45files) as atoms, arranging them LSB first - so "foo" becomes `0x6f6f66`.
46How do we know to print this as "foo", not `0x6f6f66`? We need external
47information - such as a Hoon type. Similarly, other common atomic
48types - signed integers, floating point, etc — are all straightforward
51It's also important to note that, unlike Lisp, Nock cannot create
52cyclical data structures. It is normal and common for **nouns** in a
53Nock runtime system to have acyclic structure - shared subtrees. But
54there is no Nock computation that can make a child point to its parent.
55One consequence: Nock has no garbage collector. (Nor can dag structure
56be detected, as with Lisp eq.)
58There is also no single syntax for **nouns**. If you have **nouns** you
59have Nock; if you have Nock you have Hoon; if you have Hoon, you can
60write whatever parser you like.
62------------------------------------------------------------------------
69Nock is a pure (stateless) function from **noun** to **noun**. In our
70pseudocode (and only in our pseudocode) we express this with the prefix
73A Nock program is given meaning by a process of reduction. To compute
74`nock(x)`, where `x` is any **noun**, we step through the rules from the
75top down, find the first left-hand side that matches `x`, and reduce it
76to the right-hand side (in more mathematical notation, we might write
77line 5 as `nock(a) -> *a`, a style we do use in documentation)
79When we use variable names, like `a`, in the pseudocode spec, we simply
80mean that the rule fits for any **noun** `a`.
82So `nock(x)` is `*x`, for any **noun** `x`. And how do we reduce `*x`?
83Looking up, we see that lines 23 through 39 reduce `*x` - for different
86Normally `a` in `nock(a)` is a **cell** `[s f]`, or
90Intuitively, the formula is your function and the subject is its
91argument. Hoon, or any other high-level language built on Nock, will
92build its own function calling convention which does not map directly to
95------------------------------------------------------------------------
100 6 :: [a b c] [a [b c]]
102Brackets associate to the right.
108 [2 [6 [[28 29] [30 31]]]]
109 [2 [6 [[28 29] [30 [62 63]]]]]
116 [2 6 [28 29] 30 62 63]
118While this notational convenience is hardly rocket science, it's
119surprising how confusing it can be, especially if you have a Lisp
120background. Lisp's "S-expressions" are very similar to **nouns**, except
121that Lisp has multiple types of **atom**, and Lisp's syntax
122automatically adds list terminators to groups.
124For those with Lisp experience, it's important to note that Nock and
125Hoon use tuples or "improper lists" much more heavily than Lisp. The
126list terminator, normally 0, is never automatic. So the Lisp list
130becomes the Nock **noun**
134which is equivalent to
138Note that we can and do use unnecessary brackets anyway, for emphasis.
140------------------------------------------------------------------------
152Here we define three of Nock's four axiomatic functions: **Cell-test**,
153**Increment** and **Equals** (the fourth axiomatic function, called
154**Address**, is defined in lines 16 through 21). These functions are
155just pseudocode, not actual Nock syntax, and are only used to define the
156behaviour of certain Nock operators.
158We should note that in Nock and Hoon, `0` (pronounced "yes") is true,
159and `1` ("no") is false. This convention is the opposite of
160old-fashioned booleans, so we try hard to say "yes" and "no" instead of
163------------------------------------------------------------------------
167`?` (pronounced "wut") tests whether is a **noun** is a **cell**. Again,
168`0` means "yes", `1` means "no":
173------------------------------------------------------------------------
177`+` (pronounced "lus") adds `1` to an **atom**:
182------------------------------------------------------------------------
186`=` (pronounced "tis") tests a cell for equality. `0` means "yes", `1`
193Testing an **atom** for equality makes no sense and logically fails to
196Because `+` works only for **atoms**, whereas `=` works only for
197**cells**, the error rules match first for `+` and last for `=`.
199------------------------------------------------------------------------
207 19 :: /[(a + a) b] /[2 /[a b]]
208 20 :: /[(a + a + 1) b] /[3 /[a b]]
211We define a **noun** as a binary tree - where each node branches to a
212left and right child - and assign an address, or **axis**, to every
213element in the tree. The root of the tree is `/1`. The left child
214(**head**) of every node at `/a` is `/2a`; the right child (**tail**) is
215`/2a+1`. (Writing `(a + a)` is just a clever way to write `2a`, while
216minimizing the set of pseudocode forms.)
218`1` is the root. The **head** of every **axis** `n` is `2n`; the
219**tail** is `2n+1`. Thus a simple tree:
226If the value of every leaf is its tree address, this tree is
230Let's use the example `[[97 2] [1 42 0]]`. So
232 /[1 [97 2] [1 42 0]] -> [[97 2] [1 42 0]]
234because `/1` is the root of the tree, ie, the whole **noun**.
236Its left child (**head**) is `/2` (i.e. `(1 + 1)`):
238 /[2 [97 2] [1 42 0]] -> [97 2]
240And its right child (**tail**) is `/3` (i.e. `(1 + 1 + 1)`):
242 /[3 [97 2] [1 42 0]] -> [1 42 0]
244And delving into `/3`, we see `/(3 + 3)` and `/(3 + 3 + 1)`:
246 /[6 [97 2] [1 42 0]] -> 1
247 /[7 [97 2] [1 42 0]] -> [42 0]
249It's also fun to build nouns in which every atom is its own axis:
256 [[4 5] [12 13] 14 15]
257 [[4 [10 11]] [12 13] 14 15]
258 [[[8 9] [10 11]] [12 13] 14 30 31]
260------------------------------------------------------------------------
265 23 :: *[a [b c] d] [*[a b c] *[a d]]
267The practical domain of the Nock function is always a **cell**. When `a`
268is an **atom**, `*a`, or `nock(a)`, is always an error. Conventionally,
269Nock proper is always a function of a **cell**. The **head** of this
270**cell** is the **subject**, the **tail** is the **formula**
274and the result of passing a **noun** through the Nock function is called
277 nock([subject formula]) => product
281 *[subject formula] => product
283The **subject** is your data and the **formula** is your code. And the
284**product** is your code's output.
286Notice that `a` in the Nock rules is always the **subject**, except line
28739, which is a crash default for malformed **nouns** that do not
290A **formula** is always a **cell**. But when we look inside that
291**cell**, we see two basic kinds of **formulas**:
294 [formula-x formula-y]
296An **operator** is always an **atom** (`0` through `10`). A **formula**
297is always a **cell**. Line 23 distinguishes these forms:
299 23 :: *[a [b c] d] [*[a b c] *[a d]]
301If your code contains multiple **formulas**, the **subject** will
302distribute over those **formulas**.
304In other words, if you have two Nock **formulas** `x` and `y`, a
305**formula** that computes the pair of them is just the **cell** `[x y]`.
307 *[subject [x y]] -> [*[subject x] *[subject y]]
309No **atom** is a valid **formula**, and every **formula** that does not
310use line 23 has an atomic **head**.
312Suppose you have two **formulas** `f` and `g`, each of which computes
313some function of the **subject** `s`. You can then construct the
314**formula** `h` as `[f g]`; and `h(s) = [f(s) g(s)]`.
320The **subject** `s` is `[19 42]`. The **formula** `h` is `[[0 3] 0 2]`.
324The **head** of `h` is `f`, which is `[0 3]`. The **tail** of `h` is
325`g`, which is `[0 2]`.
329by the distribution rule, `*[s [f g]]` is
335 [*[[19 42] [0 3]] *[[19 42] 0 2]]
337`*[s f]` is `f(s)` and produces `42`. `*[s g]` is `g(s)` and produces
340Since `h(s)` is `[f(s) g(s)]`, `h(s)` is `[42 19]`:
342 *[[19 42] [0 3] 0 2] -> [42 19]
344------------------------------------------------------------------------
349 25 :: *[a 0 b] /[b a]
351Operator 0 is Nock's tree address or **axis** operator, using the tree
352addressing structure defined in lines 16 through 20. `*[a 0 b]` simply
353returns the value of the part of `a` at **axis** `b`. For any subject
354`a`, the formula `[0 b]` produces `/[b a]`.
358 *[[19 42] 0 3] -> /[3 19 42] -> 42.
360------------------------------------------------------------------------
367`1` is the constant, or **Just operator**. It produces its operand `b`
368without reference to the **subject**.
374**Operator 1** is named **Just** because it produces "just" its operand.
376------------------------------------------------------------------------
381 27 :: *[a 2 b c] *[*[a b] *[a c]]
383**Operator 2** is the **Fire operator**, which brings us the essential
384magic of recursion. Given the **formula** `[2 b c]`, `b` is a
385**formula** for generating a new **subject**; `c` is a **formula** for
386generating a new **formula**. To compute `*[a 2 b c]`, we evaluate both
387`b` and `c` against the current **subject** `a`.
389A common use of **Fire** is to evaluate data inside the **subject** as
394 *[[[40 43] [4 0 1]] [2 [0 4] [0 3]]] -> 41
396 *[[[40 43] [4 0 1]] [2 [0 5] [0 3]]] -> 44
398**Operator 2** is called **Fire** because it "fires" Nock **formulas**
399at its (possibly modified) **subject**.
401------------------------------------------------------------------------
406 28 :: *[a 3 b] ?*[a b]
408**Operator 3** applies the **Cell-test** function defined in lines 8 and
4099 to the product of `*[a b]`.
411**Operator 3** is called **Depth** because it tests the "depth" of a
412noun. **Cell-test** properly refers to the pseudocode function `?`.
414------------------------------------------------------------------------
419 29 :: *[a 4 b] +*[a b]
421**Operator 4** applies the **Increment** function defined in lines 10
422and 11 to the product of `*[a b]`.
424**Operator 4** is called **Bump** because it "bumps" the atomic product
425`*[a b]` up by 1. **Increment** properly refers to the pseudocode
428------------------------------------------------------------------------
433 30 :: *[a 5 b] =*[a b]
435**Operator 5** applies the Equals function defined in lines 12, 13 and
43614 to the product of \*[a b].
438**Operator 5** is called the **Same** operator, because it tests if the
439head and tail of the product of `*[a b]` are the same. "Equals" properly
440refers to the pseudocode function "=".
442------------------------------------------------------------------------
447 32 :: *[a 6 b c d] *[a 2 [0 1] 2 [1 c d] [1 0] 2 [1 2 3] [1 0] 4 4 b]
449**Operator 6** is a primitive known to every programmer - **If**. Its
450operands, a **test formula** `b`, a **then formula** `c` and an **else
453If the **test** `b` applied to the **subject** evaluates to `0` ("yes"),
457then **If** produces the result of `c`, the **then formula**, applied to
462Else, if applying the **test** to the **subject** produces `1` ("no"),
466**Operator 6** produces the result of `d`, the **else formula**, applied
471If `*[a b]` produces any value other than `0` ("yes") or `1` ("no"),
474Let's examine the internals of **Operator 6**:
476**If** could have been defined as a built-in pseudocode function, like
482Then **Operator 6** could have been restated quite compactly:
484 :: *[a 6 b c d] *[a $[*[a b] c d]]
486However, this is unnecessary complexity. **If** can be written as a
487macro using the primitive operators:
489 32 :: *[a 6 b c d] *[a 2 [0 1] 2 [1 c d] [1 0] 2 [1 2 3] [1 0] 4 4 b]
491Reducing the right-hand side (an excellent exercise for the reader)
494 *[a *[[c d] [0 *[[2 3] [0 ++*[a b]]]]]]
496Which is the reduced pseudocode form of **Operator 6**.
498Additionally, we could simplify the semantics of **If**, at the expense
499of breaking the system, by creating a macro that works as if and only if
500`*[a b]` produces either `0` or `1`.
502This simpler **If** would be:
504 :: *[a 6 b c d] *[a 2 [0 1] 2 [1 c d] [1 0] [4 4 b]]
508 *[a *[[c d] [0 ++*[a b]]]]
510Let's examine the internals of this macro with a test example:
512 *[[40 43] [6 [3 0 1] [4 0 2] [4 0 1]]]
514Fitting this to the reduced form:
516 *[[40 43] *[[4 0 2] [4 0 3]] [0 ++*[[40 43] [3 0 1]]]]]
524 *[[40 43] *[[[4 0 2] [4 0 3]] [0 ++0]]]]
526which gets incremented twice
528 *[[40 43] *[[[4 0 2] [4 0 3]] [0 2]]]
530and is used as an axis to select the head of [[4 0 2] [4 0 3]]
534which increments `40` to produce `41`. Had the **test** produced a "no"
535instead of a "yes", **If** would have incremented the **tail** of the
536subject instead of the **head**.
538The real **If** is only slightly more complicated:
540 :: *[a 6 b c d] *[a *[[c d] [0 *[[2 3] [0 ++*[a b]]]]]]
542There is an extra step in the real **If** to prevent unexpected
543behaviour if the test produces a value other than 0 ("yes") or 1 ("no").
544The real **If** will crash if this happens and the naive **If** may not
545(the reader will find it a useful exercise to figure out why).
547It's worth noting that practical, compiler-generated Nock never does
548anything as funky as these **Operator 6** macro internals.
550------------------------------------------------------------------------
555 33 :: *[a 7 b c] *[a 2 b 1 c]
557**Operator 7** implements function composition. To use a bit of math
558notation, if we define the formula `[7 b c]` as a function `d(x)`:
562This is apparent from the reduced pseudocode form of **Operator 7**:
568 *[[42 44] [7 [4 0 3] [3 0 1]]] -> 1
570The above sequentially applies the **formulas** `[4 0 3]` and `[3 0 1]`
571to our subject `[42 44]`, first incrementing the **head**, then testing
574------------------------------------------------------------------------
579 34 :: *[a 8 b c] *[a 7 [[7 [0 1] b] 0 1] c]
581**Operator 8** pushes a new **noun** onto our **subject**, not at all
582unlike pushing a new variable onto the stack.
584The internals of **Operator 8** are similar to **Operator 7**, except
585that the **subject** for `c` is not simply the **product** of `b`, but
586the ordered pair of the **product** of `b` and the original **subject**.
588This is apparent from the reduced pseudocode form of **Operator 8**:
592**Operator 8** evaluates the **formula** `c` with the **cell** of
593`*[a b]` and the original **subject** `a`. In math notation, if we
594define `[8 b c]` as `d(x)`:
598Suppose, for the purposes of the **formula** `c`, we need not just the
599**subject** `a`, but some intermediate **noun** computed from the
600**subject** that will be useful in the calculation of `c`. **Operator
6018** applies **formula** `c` to a new **subject** that is the pair of the
602intermediate value and the old **subject**.
604In higher-level languages that compile to Nock, variable declarations
605are likely to generate an **Operator 8**, because the variable is
606computed against the present **subject**, and used in a calculation
607which depends both on the original **subject** and the new variable.
609------------------------------------------------------------------------
614 35 :: *[a 9 b c] *[a 7 c 2 [0 1] 0 b]
616**Operator 9** is the **Call** operator and is used for calling and
617applying **formulas** inside **noun** structures called **cores**
619A **noun** can contain both data and code. By convention, all
620interesting flow control in Nock is done with **cores**, which are
621**cells** whose head is code (containing one or more **formulas**) and
622whose **tail** is data (possibly containing other **cores**):
626All flow structures in other languages not built on Nock correspond to
627**cores**. Functions and/or closures are **cores**, objects are
628**cores**, modules are **cores**, even loops are **cores** (Nock, of
629course, does not have a loop operator).
631The head of a **core** is called the **battery** and the tail is called
636The **payload** of a core is any useful data needed for computation.
638The **battery** of a **core** is a **noun** containing one or more
639**arms**, which are **formulas** whose **subject** is the entire
642For example, in the case of the **battery** containing three **arms**:
646Where `arm1` is at **axis** `/2` in the **battery**, `arm2` is at `/6`,
647and `arm3` is at `/7`. The **axes** will differ depending on the number
650Of course, because the **subject** of an **arm** is the entire **core**,
651an **arm** can invoke itself (or any other **arm** in the **battery**).
652Hence, it can loop. And this is what a loop is - the simplest of
655Also, by convention, we have terms for different kinds of **cores**,
656depending on their structure:
658A **trap** is a **core** whose battery contains a single **arm**. By
659convention, this arm is called `$` (pronounced 'buc'), which is the
660empty-name. All **traps** have the following structure:
664A **door** is a **core** with a **payload** of the form
665`[sample context]`. The **sample** is dynamic data (such as the
666arguments of a function) and the **context** is any data that might be
667useful (such as other **cores**, variables, or the entire kernel of your
668OS). All **doors** have the following structure:
670 [battery [sample context]]
672A **gate** is a **core** that is both a **door** and a **trap**.
673**Gates** are the Nock equivalent of lambdas or functions. All **gates**
678**Operator 9** constructs a **core** and activates it by calling one of
681Looking reduced pseudocode form of **Call**:
683 *[*[a c] *[*[a c] 0 b]]
685**Call** applies a **formula** `c` to the **subject** `a`, where
686`*[a c]` produces a **core**. **Call** then calls an **arm** `b` of the
687**core** produced by `*[a c]` and reflexively applies it to the same
690------------------------------------------------------------------------
695 36 :: *[a 10 [b c] d] *[a 8 c 7 [0 3] d]
696 37 :: *[a 10 b c] *[a c]
698**Operator 10** serves a hint to the interpreter.
700If `b` is an atom and `c` is a **formula**, the **formula** `[10 b c]`
701appears to be equivalent to `c`. Likewise if `[b c]` is a **cell**,
702`[10 [b c] d]` appears to be equivalent to `d`. **Operator 10** is
703actually a hint operator. The `b` or `[b c]`is discarded information -
704it is not used, formally, in the computation. It may help the
705interpreter compute the expression more efficiently, however.
707Every Nock computes the same result - but not all at the same speed.
708What hints are supported? What do they do? Hints are a higher-level
709convention which do not, and should not, appear in the Nock spec. Some
710are defined in Hoon. Indeed, a naive Nock interpreter not optimized for
711Hoon will run Hoon quite poorly. When it gets the product, however, the
712product will be right. (Why is the `c` in `[b c]` computed? Because `c`
713could crash. A correct Nock cannot simply ignore it, and treat both
714variants of `10` as equivalent.)
716------------------------------------------------------------------------
721**operator 11** retrieves data from the global namespace at the path it is given.
723nock 11 is an additional nock operation provided by arvo to provide access to the global namespace. It's provided by arvo, so even though it's not technically a part of the nock, any code that arvo runs has access to it. When nock running on top of arvo hits nock 11, it either produces a value or blocks. The most common usage is with clay, where ^(%cx /path/to/file) will produce the referred-to-file.
730The nock function is defined for every **noun**, but on many **nouns**
731it does nothing useful. For instance, if `a` is an **atom**, `*a`
732reduces to... `*a`. In theory, this means that Nock spins forever in an
733infinite loop. In other words, Nock produces no result - and in
734practice, your interpreter will stop.
736Another way to see this is that Nock has "crash-only" semantics. There
737is no exception mechanism. The only way to catch Nock errors is to
738simulate Nock in a higher-level virtual Nock - which, in fact, we do all
739the time. A simulator (or a practical low-level interpreter) can report,
740out of band, that Nock would not terminate. It cannot recognize all
741infinite loops, of course (cf. Halting problem), but it can recognize
742common and obvious ones, which is usually sufficient in practice.
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list