7 1 :: A noun is an atom or a cell.
8 2 :: An atom is a natural number.
9 3 :: A cell is an ordered pair of nouns.
11An **atom** is a natural number - ie, an unsigned integer. Nock does not
12limit the size of **atoms**, or know what an **atom** means.
14For instance, the **atom** `97` might mean the number `97`, or it might
15mean the letter `a` (ASCII 97). A very large **atom** might be the
16number of grains of sand on the beach - or it might be a GIF of your
17children playing on the beach. Typically when we represent strings or
18files as **atoms**, the first byte is the low byte. But even this is
19just a convention. An **atom** is an **atom**.
21A **cell** is an ordered pair of any two **nouns** - **cell** or
22**atom**. We group cells with square brackets:
29*Nouns* are the dumbest data model ever. **Nouns** make JSON look like
30XML and XML look like ASN.1. It may also remind you of Lisp's
31S-expressions - you can think of nouns as "S-expressions without the S."
33To be exact, a *noun* is an S-expression, except that classic
34S-expressions have multiple **atom** types ("S" is for "symbol"). Since
35Nock is designed to be used with a higher-level type system (such as
36Hoon's), it does not need low-level types. An **atom** is just an
37unsigned integer of any size.
39For instance, it's common to represent strings (or even whole text
40files) as atoms, arranging them LSB first - so "foo" becomes `0x6f6f66`.
41How do we know to print this as "foo", not `0x6f6f66`? We need external
42information - such as a Hoon type. Similarly, other common atomic
43types - signed integers, floating point, etc — are all straightforward
46It's also important to note that, unlike Lisp, Nock cannot create
47cyclical data structures. It is normal and common for **nouns** in a
48Nock runtime system to have acyclic structure - shared subtrees. But
49there is no Nock computation that can make a child point to its parent.
50One consequence: Nock has no garbage collector. (Nor can dag structure
51be detected, as with Lisp eq.)
53There is also no single syntax for **nouns**. If you have **nouns** you
54have Nock; if you have Nock you have Hoon; if you have Hoon, you can
55write whatever parser you like.
57------------------------------------------------------------------------
64Nock is a pure (stateless) function from **noun** to **noun**. In our
65pseudocode (and only in our pseudocode) we express this with the prefix
68A Nock program is given meaning by a process of reduction. To compute
69`nock(x)`, where `x` is any **noun**, we step through the rules from the
70top down, find the first left-hand side that matches `x`, and reduce it
71to the right-hand side (in more mathematical notation, we might write
72line 5 as `nock(a) -> *a`, a style we do use in documentation)
74When we use variable names, like `a`, in the pseudocode spec, we simply
75mean that the rule fits for any **noun** `a`.
77So `nock(x)` is `*x`, for any **noun** `x`. And how do we reduce `*x`?
78Looking up, we see that lines 23 through 39 reduce `*x` - for different
81Normally `a` in `nock(a)` is a **cell** `[s f]`, or
85Intuitively, the formula is your function and the subject is its
86argument. Hoon, or any other high-level language built on Nock, will
87build its own function calling convention which does not map directly to
90------------------------------------------------------------------------
95 6 :: [a b c] [a [b c]]
97Brackets associate to the right.
103 [2 [6 [[28 29] [30 31]]]]
104 [2 [6 [[28 29] [30 [62 63]]]]]
111 [2 6 [28 29] 30 62 63]
113While this notational convenience is hardly rocket science, it's
114surprising how confusing it can be, especially if you have a Lisp
115background. Lisp's "S-expressions" are very similar to **nouns**, except
116that Lisp has multiple types of **atom**, and Lisp's syntax
117automatically adds list terminators to groups.
119For those with Lisp experience, it's important to note that Nock and
120Hoon use tuples or "improper lists" much more heavily than Lisp. The
121list terminator, normally 0, is never automatic. So the Lisp list
125becomes the Nock **noun**
129which is equivalent to
133Note that we can and do use unnecessary brackets anyway, for emphasis.
135------------------------------------------------------------------------
147Here we define three of Nock's four axiomatic functions: **Cell-test**,
148**Increment** and **Equals** (the fourth axiomatic function, called
149**Address**, is defined in lines 16 through 21). These functions are
150just pseudocode, not actual Nock syntax, and are only used to define the
151behaviour of certain Nock operators.
153We should note that in Nock and Hoon, `0` (pronounced "yes") is true,
154and `1` ("no") is false. This convention is the opposite of
155old-fashioned booleans, so we try hard to say "yes" and "no" instead of
158------------------------------------------------------------------------
162`?` (pronounced "wut") tests whether is a **noun** is a **cell**. Again,
163`0` means "yes", `1` means "no":
168------------------------------------------------------------------------
172`+` (pronounced "lus") adds `1` to an **atom**:
177------------------------------------------------------------------------
181`=` (pronounced "tis") tests a cell for equality. `0` means "yes", `1`
188Testing an **atom** for equality makes no sense and logically fails to
191Because `+` works only for **atoms**, whereas `=` works only for
192**cells**, the error rules match first for `+` and last for `=`.
194------------------------------------------------------------------------
202 19 :: /[(a + a) b] /[2 /[a b]]
203 20 :: /[(a + a + 1) b] /[3 /[a b]]
206We define a **noun** as a binary tree - where each node branches to a
207left and right child - and assign an address, or **axis**, to every
208element in the tree. The root of the tree is `/1`. The left child
209(**head**) of every node at `/a` is `/2a`; the right child (**tail**) is
210`/2a+1`. (Writing `(a + a)` is just a clever way to write `2a`, while
211minimizing the set of pseudocode forms.)
213`1` is the root. The **head** of every **axis** `n` is `2n`; the
214**tail** is `2n+1`. Thus a simple tree:
221If the value of every leaf is its tree address, this tree is
225Let's use the example `[[97 2] [1 42 0]]`. So
227 /[1 [97 2] [1 42 0]] -> [[97 2] [1 42 0]]
229because `/1` is the root of the tree, ie, the whole **noun**.
231Its left child (**head**) is `/2` (i.e. `(1 + 1)`):
233 /[2 [97 2] [1 42 0]] -> [97 2]
235And its right child (**tail**) is `/3` (i.e. `(1 + 1 + 1)`):
237 /[3 [97 2] [1 42 0]] -> [1 42 0]
239And delving into `/3`, we see `/(3 + 3)` and `/(3 + 3 + 1)`:
241 /[6 [97 2] [1 42 0]] -> 1
242 /[7 [97 2] [1 42 0]] -> [42 0]
244It's also fun to build nouns in which every atom is its own axis:
251 [[4 5] [12 13] 14 15]
252 [[4 [10 11]] [12 13] 14 15]
253 [[[8 9] [10 11]] [12 13] 14 30 31]
255------------------------------------------------------------------------
260 23 :: *[a [b c] d] [*[a b c] *[a d]]
262The practical domain of the Nock function is always a **cell**. When `a`
263is an **atom**, `*a`, or `nock(a)`, is always an error. Conventionally,
264Nock proper is always a function of a **cell**. The **head** of this
265**cell** is the **subject**, the **tail** is the **formula**
269and the result of passing a **noun** through the Nock function is called
272 nock([subject formula]) => product
276 *[subject formula] => product
278The **subject** is your data and the **formula** is your code. And the
279**product** is your code's output.
281Notice that `a` in the Nock rules is always the **subject**, except line
28239, which is a crash default for malformed **nouns** that do not
285A **formula** is always a **cell**. But when we look inside that
286**cell**, we see two basic kinds of **formulas**:
289 [formula-x formula-y]
291An **operator** is always an **atom** (`0` through `10`). A **formula**
292is always a **cell**. Line 23 distinguishes these forms:
294 23 :: *[a [b c] d] [*[a b c] *[a d]]
296If your code contains multiple **formulas**, the **subject** will
297distribute over those **formulas**.
299In other words, if you have two Nock **formulas** `x` and `y`, a
300**formula** that computes the pair of them is just the **cell** `[x y]`.
302 *[subject [x y]] -> [*[subject x] *[subject y]]
304No **atom** is a valid **formula**, and every **formula** that does not
305use line 23 has an atomic **head**.
307Suppose you have two **formulas** `f` and `g`, each of which computes
308some function of the **subject** `s`. You can then construct the
309**formula** `h` as `[f g]`; and `h(s) = [f(s) g(s)]`.
315The **subject** `s` is `[19 42]`. The **formula** `h` is `[[0 3] 0 2]`.
319The **head** of `h` is `f`, which is `[0 3]`. The **tail** of `h` is
320`g`, which is `[0 2]`.
324by the distribution rule, `*[s [f g]]` is
330 [*[[19 42] [0 3]] *[[19 42] 0 2]]
332`*[s f]` is `f(s)` and produces `42`. `*[s g]` is `g(s)` and produces
335Since `h(s)` is `[f(s) g(s)]`, `h(s)` is `[42 19]`:
337 *[[19 42] [0 3] 0 2] -> [42 19]
339------------------------------------------------------------------------
344 25 :: *[a 0 b] /[b a]
346Operator 0 is Nock's tree address or **axis** operator, using the tree
347addressing structure defined in lines 16 through 20. `*[a 0 b]` simply
348returns the value of the part of `a` at **axis** `b`. For any subject
349`a`, the formula `[0 b]` produces `/[b a]`.
353 *[[19 42] 0 3] -> /[3 19 42] -> 42.
355------------------------------------------------------------------------
362`1` is the constant, or **Just operator**. It produces its operand `b`
363without reference to the **subject**.
369**Operator 1** is named **Just** because it produces "just" its operand.
371------------------------------------------------------------------------
376 27 :: *[a 2 b c] *[*[a b] *[a c]]
378**Operator 2** is the **Fire operator**, which brings us the essential
379magic of recursion. Given the **formula** `[2 b c]`, `b` is a
380**formula** for generating a new **subject**; `c` is a **formula** for
381generating a new **formula**. To compute `*[a 2 b c]`, we evaluate both
382`b` and `c` against the current **subject** `a`.
384A common use of **Fire** is to evaluate data inside the **subject** as
389 *[[[40 43] [4 0 1]] [2 [0 4] [0 3]]] -> 41
391 *[[[40 43] [4 0 1]] [2 [0 5] [0 3]]] -> 44
393**Operator 2** is called **Fire** because it "fires" Nock **formulas**
394at its (possibly modified) **subject**.
396------------------------------------------------------------------------
401 28 :: *[a 3 b] ?*[a b]
403**Operator 3** applies the **Cell-test** function defined in lines 8 and
4049 to the product of `*[a b]`.
406**Operator 3** is called **Depth** because it tests the "depth" of a
407noun. **Cell-test** properly refers to the pseudocode function `?`.
409------------------------------------------------------------------------
414 29 :: *[a 4 b] +*[a b]
416**Operator 4** applies the **Increment** function defined in lines 10
417and 11 to the product of `*[a b]`.
419**Operator 4** is called **Bump** because it "bumps" the atomic product
420`*[a b]` up by 1. **Increment** properly refers to the pseudocode
423------------------------------------------------------------------------
428 30 :: *[a 5 b] =*[a b]
430**Operator 5** applies the Equals function defined in lines 12, 13 and
43114 to the product of \*[a b].
433**Operator 5** is called the **Same** operator, because it tests if the
434head and tail of the product of `*[a b]` are the same. "Equals" properly
435refers to the pseudocode function "=".
437------------------------------------------------------------------------
442 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]
444**Operator 6** is a primitive known to every programmer - **If**. Its
445operands, a **test formula** `b`, a **then formula** `c` and an **else
448If the **test** `b` applied to the **subject** evaluates to `0` ("yes"),
452then **If** produces the result of `c`, the **then formula**, applied to
457Else, if applying the **test** to the **subject** produces `1` ("no"),
461**Operator 6** produces the result of `d`, the **else formula**, applied
466If `*[a b]` produces any value other than `0` ("yes") or `1` ("no"),
469Let's examine the internals of **Operator 6**:
471**If** could have been defined as a built-in pseudocode function, like
477Then **Operator 6** could have been restated quite compactly:
479 :: *[a 6 b c d] *[a $[*[a b] c d]]
481However, this is unnecessary complexity. **If** can be written as a
482macro using the primitive operators:
484 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]
486Reducing the right-hand side (an excellent exercise for the reader)
489 *[a *[[c d] [0 *[[2 3] [0 ++*[a b]]]]]]
491Which is the reduced pseudocode form of **Operator 6**.
493Additionally, we could simplify the semantics of **If**, at the expense
494of breaking the system, by creating a macro that works as if and only if
495`*[a b]` produces either `0` or `1`.
497This simpler **If** would be:
499 :: *[a 6 b c d] *[a 2 [0 1] 2 [1 c d] [1 0] [4 4 b]]
503 *[a *[[c d] [0 ++*[a b]]]]
505Let's examine the internals of this macro with a test example:
507 *[[40 43] [6 [3 0 1] [4 0 2] [4 0 1]]]
509Fitting this to the reduced form:
511 *[[40 43] *[[4 0 2] [4 0 3]] [0 ++*[[40 43] [3 0 1]]]]]
519 *[[40 43] *[[[4 0 2] [4 0 3]] [0 ++0]]]]
521which gets incremented twice
523 *[[40 43] *[[[4 0 2] [4 0 3]] [0 2]]]
525and is used as an axis to select the head of [[4 0 2] [4 0 3]]
529which increments `40` to produce `41`. Had the **test** produced a "no"
530instead of a "yes", **If** would have incremented the **tail** of the
531subject instead of the **head**.
533The real **If** is only slightly more complicated:
535 :: *[a 6 b c d] *[a *[[c d] [0 *[[2 3] [0 ++*[a b]]]]]]
537There is an extra step in the real **If** to prevent unexpected
538behaviour if the test produces a value other than 0 ("yes") or 1 ("no").
539The real **If** will crash if this happens and the naive **If** may not
540(the reader will find it a useful exercise to figure out why).
542It's worth noting that practical, compiler-generated Nock never does
543anything as funky as these **Operator 6** macro internals.
545------------------------------------------------------------------------
550 33 :: *[a 7 b c] *[a 2 b 1 c]
552**Operator 7** implements function composition. To use a bit of math
553notation, if we define the formula `[7 b c]` as a function `d(x)`:
557This is apparent from the reduced pseudocode form of **Operator 7**:
563 *[[42 44] [7 [4 0 3] [3 0 1]]] -> 1
565The above sequentially applies the **formulas** `[4 0 3]` and `[3 0 1]`
566to our subject `[42 44]`, first incrementing the **head**, then testing
569------------------------------------------------------------------------
574 34 :: *[a 8 b c] *[a 7 [[7 [0 1] b] 0 1] c]
576**Operator 8** pushes a new **noun** onto our **subject**, not at all
577unlike pushing a new variable onto the stack.
579The internals of **Operator 8** are similar to **Operator 7**, except
580that the **subject** for `c` is not simply the **product** of `b`, but
581the ordered pair of the **product** of `b` and the original **subject**.
583This is apparent from the reduced pseudocode form of **Operator 8**:
587**Operator 8** evaluates the **formula** `c` with the **cell** of
588`*[a b]` and the original **subject** `a`. In math notation, if we
589define `[8 b c]` as `d(x)`:
593Suppose, for the purposes of the **formula** `c`, we need not just the
594**subject** `a`, but some intermediate **noun** computed from the
595**subject** that will be useful in the calculation of `c`. **Operator
5968** applies **formula** `c` to a new **subject** that is the pair of the
597intermediate value and the old **subject**.
599In higher-level languages that compile to Nock, variable declarations
600are likely to generate an **Operator 8**, because the variable is
601computed against the present **subject**, and used in a calculation
602which depends both on the original **subject** and the new variable.
604------------------------------------------------------------------------
609 35 :: *[a 9 b c] *[a 7 c 2 [0 1] 0 b]
611**Operator 9** is the **Call** operator and is used for calling and
612applying **formulas** inside **noun** structures called **cores**
614A **noun** can contain both data and code. By convention, all
615interesting flow control in Nock is done with **cores**, which are
616**cells** whose head is code (containing one or more **formulas**) and
617whose **tail** is data (possibly containing other **cores**):
621All flow structures in other languages not built on Nock correspond to
622**cores**. Functions and/or closures are **cores**, objects are
623**cores**, modules are **cores**, even loops are **cores** (Nock, of
624course, does not have a loop operator).
626The head of a **core** is called the **battery** and the tail is called
631The **payload** of a core is any useful data needed for computation.
633The **battery** of a **core** is a **noun** containing one or more
634**arms**, which are **formulas** whose **subject** is the entire
637For example, in the case of the **battery** containing three **arms**:
641Where `arm1` is at **axis** `/2` in the **battery**, `arm2` is at `/6`,
642and `arm3` is at `/7`. The **axes** will differ depending on the number
645Of course, because the **subject** of an **arm** is the entire **core**,
646an **arm** can invoke itself (or any other **arm** in the **battery**).
647Hence, it can loop. And this is what a loop is - the simplest of
650Also, by convention, we have terms for different kinds of **cores**,
651depending on their structure:
653A **trap** is a **core** whose battery contains a single **arm**. By
654convention, this arm is called `$` (pronounced 'buc'), which is the
655empty-name. All **traps** have the following structure:
659A **door** is a **core** with a **payload** of the form
660`[sample context]`. The **sample** is dynamic data (such as the
661arguments of a function) and the **context** is any data that might be
662useful (such as other **cores**, variables, or the entire kernel of your
663OS). All **doors** have the following structure:
665 [battery [sample context]]
667A **gate** is a **core** that is both a **door** and a **trap**.
668**Gates** are the Nock equivalent of lambdas or functions. All **gates**
673**Operator 9** constructs a **core** and activates it by calling one of
676Looking reduced pseudocode form of **Call**:
678 *[*[a c] *[*[a c] 0 b]]
680**Call** applies a **formula** `c` to the **subject** `a`, where
681`*[a c]` produces a **core**. **Call** then calls an **arm** `b` of the
682**core** produced by `*[a c]` and reflexively applies it to the same
685------------------------------------------------------------------------
690 36 :: *[a 10 [b c] d] *[a 8 c 7 [0 3] d]
691 37 :: *[a 10 b c] *[a c]
693**Operator 10** serves a hint to the interpreter.
695If `b` is an atom and `c` is a **formula**, the **formula** `[10 b c]`
696appears to be equivalent to `c`. Likewise if `[b c]` is a **cell**,
697`[10 [b c] d]` appears to be equivalent to `d`. **Operator 10** is
698actually a hint operator. The `b` or `[b c]`is discarded information -
699it is not used, formally, in the computation. It may help the
700interpreter compute the expression more efficiently, however.
702Every Nock computes the same result - but not all at the same speed.
703What hints are supported? What do they do? Hints are a higher-level
704convention which do not, and should not, appear in the Nock spec. Some
705are defined in Hoon. Indeed, a naive Nock interpreter not optimized for
706Hoon will run Hoon quite poorly. When it gets the product, however, the
707product will be right. (Why is the `c` in `[b c]` computed? Because `c`
708could crash. A correct Nock cannot simply ignore it, and treat both
709variants of `10` as equivalent.)
711------------------------------------------------------------------------
716**operator 11** retrieves data from the global namespace at the path it is given.
718nock 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.
725The nock function is defined for every **noun**, but on many **nouns**
726it does nothing useful. For instance, if `a` is an **atom**, `*a`
727reduces to... `*a`. In theory, this means that Nock spins forever in an
728infinite loop. In other words, Nock produces no result - and in
729practice, your interpreter will stop.
731Another way to see this is that Nock has "crash-only" semantics. There
732is no exception mechanism. The only way to catch Nock errors is to
733simulate Nock in a higher-level virtual Nock - which, in fact, we do all
734the time. A simulator (or a practical low-level interpreter) can report,
735out of band, that Nock would not terminate. It cannot recognize all
736infinite loops, of course (cf. Halting problem), but it can recognize
737common 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