notes-computer-programming-hoon-hoonCheatSheet

Difference between revision 21 and current revision

No diff available.

This cheat sheet contains lists of 'Hoon' words and symbols and short descriptions of what they are or what they do. Note that we unabashedly map Hoon concepts to the closest corresponding concept in other programming languages, even if the concepts are not quite the same. For example, in biology, bird wings and bat wings are said to be analogous but not homologous, because they have similar function but they are not quite the same and indeed the common ancestor of birds and bats did not have wings. In this table, we map analogous concepts to each other even if they are not homologous; if bat wings and bird wings were here, we would map bat wings to bird wings. For example, we map 'gate' to 'function; see the section "Gates and lambda" from Hoon tutorial section 4 for more discussion of this.

Please note that i am writing this in the process of learning Hoon, and i don't understand most of what is written here yet, so there are probably many mistakes and misconceptions in this document.

Note: this is NOT meant to become a complete language reference; it is supposed to cover only those things that you need to know in order to understand the tutorial, and perhaps a few of the other most important language constructs.

Nock->English

Alphabetical

add: addition

Arm: "A core formula is called an arm. An arm is almost like an object-oriented method, but not quite - a method would be an arm that produces a function on an argument. The arm is just a function of the core, ie, a computed attribute." "a computed expression". Note that an Arm expects to be called with the entire Core that it is a part of as its subject. Can also be thought of as consisting of both a symbol (the fieldname) and also a twig (the arm itself). If we Pull a Wing in a Core and the result is computed by a formula, then that result is an Arm; but if we Pull a Wing in a Core and the result is defined as a subtree of the Core, then that result is a Leg. [1] [2] [3] [4]

Ash: geometric polymorphism. 'dry'.

Atom: a natural number. Also a type stem %atom.

Axil: 'base' tile; see table Tiles.

Axis/Axes: a type of limb which is a fieldname/field selector. [5]

Bark: naming tile; see table Tiles.

Base: see table 'Tiles'

Battery: The head of a Core; code, containing one or more Formulas.

bean: short for Loobean (boolean)

Book: "a core which contains only code and constant data". "A core whose payload is either another core, or a constant (%cube)" Contrast to Cart [6] [7]

Bulb: The tail of a kelp. [8]

Bull: alias type [9]

bunt: a tile reduction. [10]

bush: pair/tag tile; see table Tiles. [11]

by: Maps container. "++by is the container for all the map arms. The contained arms inherit its sample, the map a." "Note: ++by is not used alone, but is used to call the arms it contains." [12]

Cart: "a core containing dynamic state". Contrast to Book. [13]

Cell: ordered pair of nouns. Syntax: [a b]. Groups to the right, so e.g. [2 6 14 15] is short for [2 [6 [14 15]]]. Also a type stem %cell.

clam: a tile reduction. A clam just produces a gate which executes a whip to the given tile (e.g. it produces a closure which remembers the tile you give it, as passes that to the whip reduction when it is called) [14]

Coil: todo. see http://doc.urbit.org/doc/hoon/tut/3/

Context: todo. Also indicated by '+>', or 'gras'. [15]

Core: a "core is just a cell whose tail is data (possibly containing other cores) and whose head is code (containing one or more formulas). The tail is the payload and the head is the battery...To activate a core, pick a formula out of the battery, and use the entire core (_not_ just the payload) as the subject." or "a core is a [code data] cell - [battery payload]. Essentially, an object. The battery, at the Nock level, is a tree of formulas, each of whose subject is the core itself.". " A core is a noun of the form [battery payload] where the battery is a tree of formulas, each invoked with the entire core as the subject, and the payload is any noun.". "There are three main ways we can talk about a core: its variance model, %gold, %iron, %zinc or %lead, %gold by default; the inference approach of each of its feet, %ash or %elm, informally dry or wet, dry or ash by default; and its payload pattern, which makes it a gate, reef, book, trap or tray. There are also several ways of using cores: you can pull, kick, slam or slug them." %core is also a type stem. [16] [17] [18]

Cord: string. syntax: 'this is a string'; 'to escape a \'quote\', use \'backslash\. [19]

cube: todo type stem. Related to constants.

cue: unmarshall

dec: decrement. [20]

Dry: geometric polymorphism. ash. [21]

Elm: generic polymorphism. 'wet'. [22]

f(x): f(x) (?where f and x are alphanumerics?) is the irregular form of %=(f x). [23]

Face: todo type stem. presumably short for 'interface'

Fern: plain selection tile; see table Tiles.

Fish: a tile reduction. [24]

Foot: todo. http://web.archive.org/web/20131005080850/http://www.urbit.org/2013/08/22/Chapter-5-types.html says that the formulas in a battery are called '%foot's, but i haven't seen that elsewhere yet. [25]

Fork: todo type stem.

Formula: In Nock, Nock instructions are generally cells of the form [subject formula]. "Intuitively, the formula is your function and the subject is its argument. We call them something different because Hoon, or any other high-level language built on Nock, will build its own function calling convention which does not map directly to *[subject formula]....Basically, the subject is your data and the formula is your code.". [26]

Frond: A case within a kelp. [27]

Gate: a core serving as a function. "A gate is a trap whose payload has the form [sample context], sample being dynamic data and context being anything." I think a Gate is of the form [formula payload] (contrast to a Core, which is [battery payload], where a Battery can be a structure with many Formulas), but i'm not sure. Syntax: ++gatename to indicate the gate named 'gatename'. todo. see also table 'Gate, parts of'. see also http://doc.urbit.org/doc/hoon/tut/4/ . "Every gate is a trap. Every gate is a tray." [28] [29]

gen: todo, i see this all over the place in the tutorial, but i don't know what it is. e.g. in http://doc.urbit.org/doc/hoon/tut/6/ in ++open. Is this just an internal variable name in the interpreter for the AST we are currently processing?

Geometric polymorphism: [30]

Glyph: A punctuation character. Hoon assigns non-standard names to them, see table "Glyphs (Hoon glyph names)", below.

Gold: polymorphism with variance: invariant. [31]

Gonad: todo, see http://doc.urbit.org/doc/hoon/tut/7/

Herb: function (custom) tile; see table Tiles.

Hold: %hold is the pseudolazy evaluation type stem. [32]

homo: homogenize the type of a list. [33]

Hoon: Language name. Synonym for rune. What else?

homo: homogenize. "homogenizes the type of a list, producing its sample noun unchanged" [34]

Icon: the type of a tile? [35]

Iron: polymorphism with variance: contravariant. [36]

jam: marshall

Kelp: tag selection tile; see table Tiles. The head of a kelp must be a leaf. The head of a kelp is called a stem, and the tail is called a bulb. Cases of a kelp are called fronds. [37]

Kick: "To pull %$ - the empty name - on a core is to kick it. To replace the sample with a in gate g then kick the gate, is to slam g with a." [38]

Lead: polymorphism with variance: bivariant. [39]

Leaf: constant atom tile; see table Tiles.

Leg: "part of a typed noun (a fragment, as in Nock /)". If we Pull a Wing in a Core and the result is computed by a formula, then that result is an Arm; but if we Pull a Wing in a Core and the result is defined as a subtree of the Core, then that result is a Leg. [40] [41]

Limb: Part of a Wing. "a name or axis (which of course applies to all nouns, not just cores) is a limb. A list of limbs is a wing." "Each limb in the wing can be either a tree address (like +3, meaning Nock’s /3) or a name (like foo).". See also "name resolution" in http://doc.urbit.org/doc/hoon/tut/2/ . [42] [43]

Line: see table 'Tiles'

Loobean: boolean (note that 1 is false and 0 is true). syntax: .y == & == 0, .n ==

=== 1. [44]

map: todo. ++ map: "A map is a tree of [p=* q=*] cells where n is the node, and l and r are branches." [45]

Mint: within the Hoon interpreter, the function (gate) ++mint contains the semantics of Hoon. That is, ++mint maps [type twig] to [type nock]. ++mint is found within ++ut. [46]

mul: multiplication

Natural hoon: a hoon which is not synthetic, e.g. which is not defined in terms of other hoons. See table below.

Nest: ++nest is the predicate function isSuperTypeOf, e.g. (nest a b) tests whether a is a supertype of b. Convention: we write (nest sut ref), e.g. 'sut' is the purported supertype and ref is the purported subtype. Nest is conservative in that it only returns True if it can prove that sut is a supertype of ref; so sometimes it may return False when sut is a supertype of ref, but it can't determine that. [47]

Nil: An odor whose only value is '~' (the atom 0).

Noun: an atom or a cell

Odor: a second type system on top of the 'real' type system that tells you whether an Atom should be interpreted as an integer, a string, etc. See also http://doc.urbit.org/doc/hoon/tut/1/, http://doc.urbit.org/doc/hoon/lan/odor/. [48] [49]

Payload: The tail of a Core. Data, possibly containing other Cores. I think a Payload is usually of the form [sample context], but i'm not sure [50].

Play: ++play is like ++mint except ++play only does type inference. [51] [52]

Product: output of a twig

Pull: "To access a wing or limb in a core is to pull it." "To pull %$ - the empty name - on a core is to kick it. To replace the sample with a in gate g then kick the gate, is to slam g with a." "(The archaic usage of "call" for slam is discouraged, but common. Please at least do not use "call" to mean pull.)" [53]

put: todo (seen in http://doc.urbit.org/doc/hoon/tut/5/ but not in http://doc.urbit.org/doc/hoon/lib/ , todo, tell them)

Reed: atom/cell tile; see table Tiles. [54]

Reef: "A stack of cores in which the core below is the context of the one above, all the way down to the innermost core whose payload is a simple constant (for hoon.hoon, always the Kelvin version)". "Every reef is a book". "A book whose payload is either another reef, or a cube, is a reef. Effectively, a reef is an entirely constant core." [55] [56]

Rune: two glyphs. The first glyph (character) in a Hoon indicates its category, see table "Rune categories" below. Runes can also be named using the Symbol syntax, using the Glyph (hoon glyph names) lookup table. Synonym: 'hoon'

Sample: the argument being passed to a function (gate). Also indicated by '+<', or 'glus'. [57]

slam: "To pull %$ - the empty name - on a core is to kick it. To replace the sample with a in gate g then kick the gate, is to slam g with a." "(The archaic usage of "call" for slam is discouraged, but common. Please at least do not use "call" to mean pull.)" "Slamming is a special case of slug, which pulls any limb on a tray after replacing the sample." [58]

snag: returns the list element found at a given list index.

span: an atom of URL-safe ASCII text (i.e. the odor @ta)

Slug: To Slug is to Pull "any limb on a tray after replacing the sample. To replace the sample with a on tray t, then pull m, is to slug t to m with a." [59]

Stem: The head of a kelp. Must be a leaf. [60]

Subject: input to a twig

Sut: short for 'subject type'

Symbol: A Hoon symbol. Syntax: the character % followed by a Term. [61]

synthetic hoon: a macro

Tape: bytestring. syntax: "this is a tape"; "concatenate tapes" . "using periods"; weld "or concatenate with" " weld"; "interpolate {{weld "wi" "th"}} double braces". [62]

Term: @tas. a string each of whose characters are one of (a) lowercase ASCII, (b) - except as the first or last character, or (c) 0-9 except as the first character. [63] (todo: perhaps he meant to say lowercase ASCII letters, not all of ASCII?). ++term produces the clam of Term. See also Symbol. [64] [65]

Tile: Syntactic sugar which is reduced to a twig (a normal AST) at compile time (the question of whether tiles are a special type of twig is tricky; on the one hand, twigs are said to be ASTs, and are said to contain tiles, and every subtree of an AST is an AST by definition; on the other hand, tiles are spoken of as different from twigs, and as being reduced to twigs; i suspect that formally speaking there are really two kinds of twigs, 'tile-less ASTs' and 'ASTs' (my terminology), and that tiles are ASTs but not tile-less ASTs, but that the word 'twig' is being used both for that i called tile-less AST and also for what i called AST). Tiles have to do with producing or identifying nouns of a type. The type that a given tile operates with respect to is called the Icon of the tile. There are 4 tile reductions: bunt (produce the default value of the icon type), clam (produce a gate which converts values of another type to values of the icon type), fish (test if a value is a member of the icon type), whip (converts values of another type to values of the icon type). See http://doc.urbit.org/doc/hoon/tut/5/. See also http://doc.urbit.org/doc/hoon/lan/tile/ . [66]

tile constructor: Todo. Hoons that construct tiles. Also called 'tile hoons'. [67]

Trap: "Any core with one arm named %$ is a trap" [68]

Tray: "A tray is any core whose payload has the form [sample context]." [69]

turn: transform. "++turn takes a list a and the clam of a noun b. ++turn produces a new list with all the values of a produced by b.". i think this like 'map' in other languages, except that the function we are mapping over the list is not b but the clam of a noun b? todo, not sure [70]

Type: type. See also Type Stem. See also http://doc.urbit.org/doc/hoon/lan/type/ . There is also Odors. To prettyprint the type of variable x in the interpreter, use ':type; x'. To print the internal type of variable x in the interpreter, use '-:!>(x)'.

Type Stem: one of %atom, %cell, %core, %cube, %face, %fork, %hold, or %bull. See also http://doc.urbit.org/doc/hoon/lan/type/ . [71] [72] [73]

Tusk: list of twigs [74]

Twig: (valid) AST, after reducing tiles. For validity conditions, see http://doc.urbit.org/doc/hoon/lan/twig/ .

Ut: within the Hoon interpreter, the gate ++ut contains ++mint. [75]

void: todo. can be produced by !!.

Weed: example tile; see table Tiles.

Wet: generic polymorphism. 'elm'. [76]

Whip: normalize. a tile reduction. see $@. [77]

Wing: a list of Limbs. a way to reference either a leg or an arm. [78]. Composed of Limbs. "A wing is a dot-separated list, reading outside to in from right to left. Each element is a limb." Limbs are joined using the period character as separator, and run from right to left; e.g. "c.b.a" means "start with a, find the value attached to field b, then within that value, find the value attached to field c". See also "name resolution" in http://doc.urbit.org/doc/hoon/tut/2/ . [79] [80]

Zinc: polymorphism with variance: covariant. [81]

Leading numbers

0: True. Synonyms: &, .y. A Loobean (boolean) value.

0v: prefix for unsigned Base32 odor (@uv)

0w: prefix for unsigned Base64 odor (@uw)

 1: False. Synonyms: |, .n. A Loobean (boolean) value.
==== Leading punctuation: | ('bar'; core construction) ====

|: False literal. Synonyms: |, .n. A Loobean (boolean) value.

|n: where n is an integer literal (actually, i'm not sure about this. Would a constant in a variable work too?). A type of axis limb. Indicates the tail of the list ocurring after the list element with index n. See also &n.

|%: core constructor syntax. "|% (barcen, or %brcn), followed by any number of arms ++ ... , followed by a terminator -- ... The arm is a symbol and a twig. The subject of the twig is the core.". "uses its own subject as the payload, creating the familiar reef effect as the stack of cores piles up" "produces a %gold core (cores, link). |% takes an associative array of names (++term) and expressions (++foot), each pair of which is called an arm. A dry, or %ash, arm is denoted with ++, a wet, or %elm, arm is denoted with +-. |% can take an arbitrary number of arms, but the arm array must be terminated with a --". [http://doc.urbit.org/doc/hoon/tut/4/] [http://doc.urbit.org/doc/hoon/lan/rune/#barcen]

|.: "create a |% with one arm, our %$" "produces a dry %gold trap (cores, link). |. takes a twig." [http://doc.urbit.org/doc/hoon/tut/3/] [http://doc.urbit.org/doc/hoon/lan/rune/#bardot]

|-: todo. Something about looping. "produces a dry %gold trap and kicks it (cores, link). |- takes a twig." [http://doc.urbit.org/doc/hoon/tut/3/] [http://doc.urbit.org/doc/hoon/lan/rune/#barhep]

|=: build a gate from a tile. "the tile in |= is always bunted to create the default sample.". |=(p q) "produces a dry %gold gate with arm twig q, sample [%bctr p].", where q is a twig, p is a tile, and bctr is compile-time bunt (i.e. the default of tile p). Often you see constructions like "|=(argument1Name=argument1Type argument2Name=argument2Type)". [http://doc.urbit.org/doc/hoon/tut/5/] [http://doc.urbit.org/doc/hoon/lan/rune/#bartis]

|*: like |= but uses generic rather than geometric polymorphism. |*(p q) "produces a vulcanized wet gate with arm twig q, sample [%bctr p], where p is a tile.". bctr is $*, which produces the bunt (default value) its argument as a compile-time constant. [http://doc.urbit.org/doc/hoon/tut/6/] [http://doc.urbit.org/doc/hoon/lan/rune/#bartar]

|_: |_(p q) means 'Use q as the subject $*(p), where $*(p) is the bunt of p computed as a compile-time constant'

Leading punctuation: $ ('buc'; tiles and tiling)

$@: whip (normalize). $@(p q) normalizes wing p into tile q. [82] [83]

$: the empty symbol. "In practice, $ is used for “the nameless function or loop we’re inside.”". also, the leaf tile cell constructor. [84] [85]

$:: ($: p q) is a tile hoon that declares a tile autocons, where p and q are tiles [86]

$,: clam [87] [88]

$_: "produces the bunt (default value) for p." [89] [90]

$*: $*(p) "produces the bunt (default value) for (tile) p as a compile-time constant". "bunts tile p and folds it statically to a constant with %ktsg" todo. [91] [92]

$=: bark tile constructor. $=(p q) wraps the name p around the tile q. "a=* parses as [%bark %a %noun]." "This is another case where the tile syntax matches the twig syntax, but only in the irregular form. The twig equivalent of %bark is of course ^= (kettis, %ktts). But the tile is $=". -- [93] [94]

 $|: reed tile construtor [http://doc.urbit.org/doc/hoon/lan/rune/#bucbar]

$&: bush tile constructor [95]

$%: kelp tile constructor (discriminated union). "takes a list of lines, which are labeled cases, closed by ==" [96] [97] [98] todo: there is a little typo ('labeeled') in http://doc.urbit.org/doc/hoon/lan/rune/#buccen

$?: fern tile constructor. "A non-empty list of cases; its icon is naturally a %fork. The programmer is responsible for ensuring that the cases are actually orthogonal (unlike with the structured forks, %bush, %kelp and %reed). A good general practice is to use ferns only with leaves." Has irregular form ?(). [99]. Todo: the irregular form of $? is listed in http://doc.urbit.org/doc/hoon/lan/rune/#bucwut , and in http://doc.urbit.org/doc/hoon/lan/tile/ , but not in http://doc.urbit.org/doc/hoon/lan/rune/irregular/ . Todo: http://doc.urbit.org/doc/hoon/lan/tile/ contains a broken link to http://doc.urbit.org/doc/hoon/lan/rune/#bcwt (should be http://doc.urbit.org/doc/hoon/lan/rune/#bucwut ). Todo: http://doc.urbit.org/doc/hoon/lan/rune/#bucwut says "See the discussion of tiles in chapter 9" but presumably now should say Chapter V.

 $+: "a tile for a gate which accepts p and produces q". $+(p q) is equivalent to $_(|+(p _q)). [http://doc.urbit.org/doc/hoon/tut/6/] [http://doc.urbit.org/doc/hoon/lan/rune/#buclus]

$(): $ refers to "the nameless function or loop we’re inside", and this is a call to that function, e.g. a recursive call. Inside the parens is a list of pairs of parameter names and arguments, e.g. $(a b, c d) means "recursively call this function with b passed as argument 'a' and d passed as argument 'c'".

Leading punctuation: _

_ is not a hoon first character:

__: not a hoon. terminator for URL-safe cell syntax, e.g. [3 4] is ._3_4__

_: as a prefix, $_

Leading punctuation: % ('cen'; invocations)

%: prefix indicating a symbol, i.e. a 'cubical' constant, i.e. a constant whose type's extension is a singleton set consisting only of itself

%:: (%: p q): pull "%$ from the tray p with its sample set to q". [100]

%= "query with changes", or "resolve with changes". %=(p q) "evaluates p with the changes specified in q." . i think (but in this case i'm not very certain, in fact it think i probably got it wrong) "%= query tram" means "resolve the wing 'query' (call the result of this 'result'). 'tram' contains a list of pairs of the form 'query2 replace'. For each pair in 'tram', resolve the wing 'query2' as applied to 'result', and replace that with 'replace'. Finally, evaluation 'result' after applying all changes.", see [101] [102]. TODO: the reference manual entry at http://doc.urbit.org/doc/hoon/lan/rune/#cen says "See the explanation in Chapter 7." but i can't find a mention of '%=' in http://doc.urbit.org/doc/hoon/tut/7/ . "If q is empty, %= just pulls wing p with no changes. Otherwise, we get p with the wings in q set to the provided twigs". Irregular form of '%=(a b)' is 'a(b)'. [103]. [104]

%$: the symbol '$' (i think) [105]

%-: todo. something to do with function calling? %-(p q) "slams the gate p with [%cltr q]", where q is a list of twigs (tusk). [106] [107]

%~: %~(p q r) "pulls p from the tray q with its sample set to r". Irregular syntax ~(p q r). [108]

%*: (%* p q r) "pull the wing p from a tray q with changes r" [109]

%&: todo. http://doc.urbit.org/doc/hoon/lan/rune/#cenpam is not defined in the rune reference, although it appears in expansions given there. Tell them. Perhaps this is just the literal '&', the same as &$ is the literal '$'? Or maybe, because i see it being used like '[%& 2]', it means to select index 2 from the current subject?

Leading punctuation: : ('col'; tuples)

:-: cell constructor. :-(a b) means [a b]. [110] [111]

not a hoon. comment delimiter until end-of-line (everything to the right of :: on the same line is a comment)

:~: produces a null-terminated tuple. irregular syntax: ~[]. [112]

:_: reversed cell constructor. ':_(p q)' produces '[q p]'.

:*: produce a tuple (while also doing some black magic related to string interpolation and %clzz. [113])

:+: quoting. (:+ p q r) produces the cell [p q r]. [114]

Leading punctuation: ,

, is not a hoon first character:

,: irregular form of $,. So ,p is short for $,p. $,p is a rune that produces a normalizing gate (clam) for p. [115]

Leading punctuation: "

" is not a hoon first character:

"": tape (bytestring) delimiters

Leading punctuation: . ('dot': nock operators)

.: Between strings, string concatenation. Between limbs, in a wing, concatenation of limbs into a wing. As a limb (axis), like Nock's +1, that is, a reference to the location indicated by the wing up to that point, without evaluating the function, if any; for example, see ..$. [116]. Convenience separator between triples of digits when prettyprinting integers. Convenience separator between sets of digits when prettyprinting IP addresses. Prefix for IP addresses. Prefix for floating point. Perhaps this is also for Nock '/' selection into cells (seeing the curious use of .6 in [117]?.

.: todo: i don't understand how . is used in ++weld in http://doc.urbit.org/doc/hoon/tut/6/

.~: prefix for double-precision floating point. not a hoon.

.~~: prefix for triple-precision floating point

.~~~: prefix for quad-precision floating point

._: not a hoon. prefix for URL-safe cell syntax, also separator, e.g. [3 4] is ._3_4__

..$: "refers to the nameless function we’re inside, without actually calling it.". http://web.archive.org/web/20131014210126/http://www.urbit.org/2013/08/22/Chapter-6-hoons.html

.y: True literal. Synonyms: &, .y. A Loobean (boolean) value.

 .n: False literal. Synonyms: |, .n. A Loobean (boolean) value.

..$:

.+: increment an atom. Nock 4. [118]

.=: equality predicate. Nock 5. [119]

.^: "nock operator 11, which in virtual userspace nock (mock) loads a file from the global namespace" [120]

.*: "calculates the nock of subject p, formula q." Like Nock 2. [121]

.?: test if cell or atom. "if the noun is a cell, it returns the loobean & (true); if the noun is an atom, it returns the loobean

(false).". Nock 3. [122]

Leading punctuation: <, >

< and > are not hoon first characters:

<>: matched delimiters surrounding prettyprint syntax for a core. not a hoon.

<: Part of +-<> axis limb syntax to select via chains of head/tail. [123]

>: Part of +-<> axis limb syntax to select via chains of head/tail. [124]

Leading punctuation: -

-: Prefix for negative signed integer literals. Also a digit in base64 odor (@uw). Also 'head', part of +-<> axis limb syntax to select via chains of head/tail. If applied to a Core, selects the Battery; if applied to a Gate, selects the formula (todo is this correct?). What else? [125] [126] [127]

 --: Prefix for positive signed integer literals. Also, terminator for core constructor syntax (see |%). not a hoon.

-.: 'head'. todo how is this different from '-', above? Usage of +-<> axis limb syntax to select via chains of head/tail. [128]

Leading punctuation: ^ ('ket': type conversions)

^: cell of nouns, axil constructor syntax. as a prefix in a limb, ^ means 'skip the first match we find and return the second', ^^ means 'skip the first two matches we find and return the third', etc. E.g. i think ^$ means 'the function or loop enclosing the function or loop that we are inside'. [129]

^$: see '^'. not a hoon.

^^$: see ^

^.: "(^. p q) casts q to the type of (p q)" e.g. '^.(p q)' is equivalent to '^+((a b) b'. [130] [131]

^-: type cast to icon of tile. "casts q to ~(bunt al p), ie, the icon of p." "a purely static operation with no runtime effect whatsoever.". Often you see the following at the beginning of a gate: a line "++ gatename", followed by a line "

[gateInputArgument1Name=gateInputArgument1Type gateInputArgument2Name=gateInputArgument2Type]" to give what the input arguments are, and their types, followed by a line "^- [outputArgument1Name=outputArgument1Type outputArgument2Name=outputArgument2Type]" to give what the output arguments are, and their types. [132] [133]

^=: variable assignment. ^=(b 0) means 'b=0'. ^=(p q) "wraps q in the toga p" [134] [135] . Note: [136] says this has irregular form p=q, but [137] says it has no irregular form. TODO: see if i am mistaken, and tell them if not.

^~: "tells the compiler to compute a constant expression at compile time" "tries to execute p statically at compile time; if this fails, p remains dynamic." [138] [139]

 ^|: convert a gold core into an iron core. [http://doc.urbit.org/doc/hoon/tut/6/] [http://doc.urbit.org/doc/hoon/lan/rune/#ketbar]

^&: convert a gold core into a zinc core. [140] [141]

^?: convert a gold core into a lead core. [142] [143]

^+: type cast. "casts the product of q to the type of p, verifying that it contains the type of q." [144]

Leading punctuation: +

+ is not a hoon first character:

+: 'tail' Part of +-<> axis limb syntax to select via chains of head/tail; if this axis limb is applied to a Core, it selects the payload. Also first part of +n and ++, see below. Also irregular form of .+ (increment). [145] [146]

+.: 'tail' (todo how does this differ from '+', above?). Usage of +-<> axis limb syntax to select via chains of head/tail. [147]

+n: where n is an natural number. axis n. [148]

 ++: (geometric/ash/dry) arm constructor within core constructor syntax (see |%). todo ++ .. == syntax. also a prefix indicating a gate (function), e.g. ++nest refers to the function named 'nest'. not a hoon. [http://doc.urbit.org/doc/hoon/tut/4/]

+-: like ++ but generic/elm/wet. not a hoon. [149]

+(): irregular form of '.+'. [150]

X(+ Y): merge a wing into another wing with one of the wing's legs overwriting the other corresponding legs. e.g. =X [a=1 b=2 c=3]; =Y [b=4 c=5]; X(+ Y) returns [a=1 b=4 c=5]. This is really just a special case of the C(W X) syntax (see below) with the wing '+' using the axis limb syntax (see '+' above).

+<: 'head(tail)'; the +-<> axis limb syntax that, if applied to a Gate, selects the sample (the head of the payload). [151]

+>: 'tail(tail)'; the +-<> axis limb syntax that, if applied to a Gate, selects the context (the tail of the payload). [152]

Leading punctuation: (

(): grouping, except when a list is inside (see p(list), below) [153]

p(list): %=(p list), where p is anything and list is any list. (evaluate p with the changes specified in q)

C(W X): where C is a Cell which is a Wing, W is a wing, X is a new value: take C, follow the wing W, replace what you find there with X to create C', and return C'. E.g. =foo [a=1 b=2 c=[p=3 q=4]]; foo(q.c 7) evaluates to [a=1 b=2 c=[p=3 q=7]] (todo write that without the (erroneus?) semicolon). (todo: is this just a special case of p(list), above?) "this works only if C is already a wing, otherwise you have to use %*" [154]

Leading punctuation: &

& is not a hoon first character:

&: True literal. Synonyms: &, .y. A Loobean (boolean) value. Also, first part of literal list index syntax &n.

 &n: where n is an integer literal (actually, i'm not sure about this. Would a constant in a variable work too?). A type of axis limb. Indicates the list element with index n. See also |n, snag.

Leading punctuation: ; ('sem'; miscellaneous macros

;~: "used to make strings, interpreted or not." See Gonads in [155] [156]

Leading punctuation: ~ ('sig'; hints)

~: nil literal (in Nil odor, @n) (note: nil is used as a list terminator). Prefix for date or time literals. Part of prefix for text literals (~~, ~., ~-). Also a digit in base64 odor (@uw). Also used for escapes within text literals. Prefix for phonemic literals. Part of prefix for jam/cue marshalled literals (~0w). Part of irregular prefix for :~ (~[]). Part of irregular prefix for %~ (~()). Todo: i don't understand how '~' is used in http://doc.urbit.org/doc/hoon/tut/6/, example ++ open, line "[%tsls *] [%tsgr [p.gen [~ 1]] q.gen]".

~~: prefix for unicode text literals ('cords', odor @t). Not a hoon.

~.: prefix for URL-safe unicode text literals ('spans', odor @ta). Not a hoon.

~-: prefix for UTF-32 codepoints (odor @c). Not a hoon.

~0w: prefix for jam/cue marshalled literals

~[]: irregular prefix for :~

~(): irregular prefix for %~

~/: a jetted arm. "[%sgfs p=term q=twig] is a synthetic hoon that implements one common case - a gate arm in a book, ie, a library function - of the %sgcn jet hint. %sgfs assumes the parent axis is 7 and there are no children." See also the discussion of jet propulsion in http://doc.urbit.org/doc/hoon/tut/7/. [157] TODO: this appears to have been left out of http://doc.urbit.org/doc/hoon/lan/rune/ (yet it still appears in http://doc.urbit.org/doc/hoon/tut/3/ and http://doc.urbit.org/doc/hoon/tut/6/ . Tell them!

~

: (~p q) presents the product of p in the stack trace if q crashes. Idiom: if q is '!!' (crash), then (~'message' ~~) reports 'message' in the stack trace [158] [159]

~&: print. For example, '~&(>> q r)' prints q and then computes r. The numbers of '>'s in the '>>' is the log level, for zero, up to '>>>' for three. [160] [161]

~!: debug type of. '~!(p q)' is "for debugging uses only, semantically equivalent to its own twig q. But if compilation fails within q, ~! will show the type of p on the stacktrace." [162]

~>: hint. "applies arbitrary hint p to q" [163]

~

: print, but only if there is a crash. [164] [165]

~_: '~_(p q)' "inserts p, a trap producing tank, in the trace of q." "useful if you want to define and present your own debugging representation of an ongoing computation, which will appear in the trace of any crash within that computation." [166] [167]

Leading punctuation: *

*: noun. as a prefix, $*
*(p): irregular form short for $*.
==== Leading punctuation: ` ====

`p`q: typecast q to the icon of tile p. Irregular form of ^-(p q).


==== Leading punctuation: = ('tis'; compositions) ====

=: variable assignment, irregular form of '^='. Also equality predicate, irregular form of '.=', e.g. '=(a b)' means '.=(a b)'. [http://doc.urbit.org/doc/hoon/tut/3/]

=+: same as Nock instruction 8. "the old subject becomes the context, and the new subject adds the sample". "=+(a b) is =>([a .] b)" "pushes p on the subject and sends it to q." [http://doc.urbit.org/doc/hoon/tut/3/] [http://doc.urbit.org/doc/hoon/tut/4/] [http://doc.urbit.org/doc/hoon/tut/6/] [http://doc.urbit.org/doc/hoon/lan/rune/#tislus]

==: tall closing delimiter. [http://web.archive.org/web/20131012021359/http://www.urbit.org/2013/08/22/Chapter-4-syntax.html]. not a hoon. TODO: seems that this is nowhere defined in the new tutorial. Perhaps tell them?

=>: "=>(a b) means "use a as the subject of b.". Like Nock instruction 7. =>(p q) "uses the product of p as the subject of q" [http://doc.urbit.org/doc/hoon/lan/rune/#tisgar] [http://doc.urbit.org/doc/hoon/tut/3/]

=<: => with the argument order reversed. =<(p q) "uses the product of q as the subject of p." [http://doc.urbit.org/doc/hoon/tut/3/] [http://doc.urbit.org/doc/hoon/lan/rune/#tisgal]

=*: alias type. "creates a %bull, or alias, type." [http://doc.urbit.org/doc/hoon/lan/rune/#tistar]

Leading punctuation: ? ('wut'; conditionals, booleans, tests)

?: loobean axil syntax. todo e.g. http://doc.urbit.org/doc/hoon/tut/6/. [168]

?:: if. "?: t a b" yields a iff t is True, and b iff t is False. [169] [170] [171]

?.: unless. same as ?: but with different order. [172] [173]

?=: fish. "testing if a noun matches a type" "Note that ?= only works on a wing and more specifically leg - that is, it has to be testing a fragment of the subject." [174] [175] [176]

?&: logical AND. [177] [178]

 ?|: logical OR. [http://doc.urbit.org/doc/hoon/tut/6/] [http://doc.urbit.org/doc/hoon/lan/rune/#wutbar]

?(): fern tile constructor (irregular form of $?)

?~: isNil. ?~(p q r) "produces q if p is ~, r otherwise". ?~(a b c) is short for ?:(?=(~ a) b c). [179] [180] [181]

?-: a 'case' or 'switch' statement that depends on the type of the thing being switched upon. Synthetic hoon based on ?: and ?=. [182] [183] [184]

?+: like ?- but also takes a default. [185] [186] [187]

?@: isAtom; (?@ p q r) "q if p is an atom, r otherwise" [188] [189]

?>: assert. '?>(p q)' asserts that p is True (True is also called & or 0) before computing q. [190] [191]

?^: ?^(p q r) "evaluates r if p is equal to the bunt for its tile, otherwise q is evaluated" [192] [193]

Leading punctuation: ! ('zap'; special operations)

!!: always crash. produces type %void. [194]

!:: generate debug trace. "Every twig within a !: generates trace information" [195]

!>: '!>(p)' "produces a vase (a [type noun] cell) with the value p" [196]

!_: debug. "puts debugging information in the stack trace." [197] !,: "inserts twig q as a constant, typed with the type of twig p." [198] !%: ?? not in http://doc.urbit.org/doc/hoon/lan/rune/ todo !/: debug. "should never be compiled. When compiled with error checking turned on, it reports its subject as an error." [199] !;: "produces the product of twig q as a [type noun] pair, with twig p defining the type of the type." [200] !=: "produces the formula of twig p as a noun." [201]

Leading punctuation: other [], @, '', ``, {}

[]: cell constructor (irregular form). e.g. [3 4]. [202]

@: '@' by itself means an atom. @ is also a prefix for odor names.

``: cast an atom to a different odor, e.g. `@ud`'foo' casts the string 'foo' to an unsigned decimal.

: cord (string) delimiters

[[image: ?]]: string interpolation

English->Hoon

addition: add
Atom: atom
atom/cell tile: reed
Argument to a function: sample
AST: twig
base type tile: axil
boolean: loobean
bivariant: lead
bytestring: tape
constant atom tile: leaf
constant example tile: weed?
constant type stem: cube
Contravariant: iron
coerce: atoms can be coerced between odors, and in addition whip may have something to do with coercion, but i'm not sure, todo
Covariant: zinc
custom tile: herb
default: to take the default of a tile is to 'bunt'
discriminated union tile: kelp
disjunctive type stem: fork
example tile: weed
Fieldname: axis/axes
fork type stem: fork
Function: gate
function tile: herb
get an element in a list: snag
index into a list: snag
Input to a function/gate: sample
Input to a twig: subject
interface type stem: face
intersection type: there is none [http://doc.urbit.org/doc/hoon/tut/2/]
invariant: gold
lazy (pseudo) evaluation type stem: hold
marshall: jam (unmarshall is 'cue')
multiplication: mul
namespace type stem: face
naming tile: bark
nil: nil
Output of a twig: product
pair/tag tile: bush
Pattern: 
pattern match: fish
pseudolazy evaluation type stem: hold
selection tile, plain: fern
selection tile, tag: kelp
S-expr: cell, sort of (as noted in http://doc.urbit.org/doc/nock/tut/1/ , Lisp's syntax automatically adds a nil to groups, e.g. '(2 6 7) is short for '(2 6 7 . nil), which would be [2 6 7 0] in Nock/Hoon)
Symbol: symbol
Type: type, icon
True: 0, or &, or .y
Tuple: cell
Type: type, also odor
union type stem: fork
unmarshall: cue (marshall is 'jam')
Validate: "clam generates a validator function for" a tile's icon
Variance, in polymorphism: gold (invariant), lead (bivariant), zinc (covariant), or iron (contravariant).

Glyphs (Hoon glyph names)

ace  space      gal  <          per  )
bar  |          gar  >          sel  [
bas  \          hax  #          sem  ;
buc  $          hep  -          ser  ]
cab  _          kel  {          sig  ~
cen  %          ker  }          soq  '
col  :          ket  ^          tar  *
com  ,          lus  +          tec  `
doq  "          pam  &          tis  =
dot  .          pat  @          wut  ?
fas  /          pel  (          zap  !

from [203]

Irregular names for some pairs of glyphs

--    hephep    phep    
+-    lushep    slep
++    luslus    slus
==    tistis    stet
+<    lusgal    glus
+>    lusgar    gras
-<    hepgal    gelp
->    hepgar    garp     

from [204]

Rune categories

The first glyph (character) in a Hoon indicates its category.

|  bar    core construction
$  buc    tiles and tiling
%  cen    invocations
:  col    tuples
.  dot    nock operators
^  ket    type conversions
;  sem    miscellaneous macros
~  sig    hints
=  tis    compositions
?  wut    conditionals, booleans, tests
!  zap    special operations

from [205]

Type stems

[%atom p=term]
[%cell p=type q=type]
[%core p=type q=coil]
[%cube p=* q=type]
[%face p=term q=type]
[%fork p=type q=type]
[%hold p=(list ,[p=type q=twig])]

Tiles

[p=tile q=tile]                     ::  ordered pair
[%axil p=base]                      ::  base type
[%bark p=term q=tile]               ::  name
[%bush p=tile q=tile]               ::  pair/tag
[%fern p=[i=tile t=(list tile)]]    ::  plain selection
[%herb p=twig]                      ::  function
[%kelp p=[i=line t=(list line)]]    ::  tag selection
[%leaf p=term q=@]                  ::  constant atom
[%reed p=tile q=tile]               ::  atom/cell
[%weed p=twig]                      ::  example

where:

line is  ,[p=[%leaf p=odor q=@] q=tile]
base is  ?([%atom p=odor] %noun %cell %bean %null)

from [206]

Tile reductions

bunt	$_ 	    _
clam	$,	    ,
fish	?=	    
whip	$@

"if a tile appears where we expect a twig, the normal tile-to-twig conversion is always %bccm. Ie, using a tile as a twig generates a gate producing the icon."

also: $*, to "bunt tile p and fold it statically to a constant with %ktsg"; prefix '*'

from [207]

Odors

@c              UTF-32 codepoint
@d              date
  @da           absolute date
  @dr           relative date (ie, timespan)
@f              yes or no (inverse boolean)
@n              nil
@p              phonemic base
@r              IEEE floating-point
  @rd           double precision  (64 bits)
  @rh           half precision (16 bits)
  @rq           quad precision (128 bits)
  @rs           single precision (32 bits)
@s              signed integer, sign bit low
  @sb           signed binary
  @sd           signed decimal
  @sv           signed base32
  @sw           signed base64
  @sx           signed hexadecimal
@t              UTF-8 text (cord)
  @ta           ASCII text (span)
    @tas        ASCII symbol (term)
@u              unsigned integer
  @ub           unsigned binary
  @ud           unsigned decimal
  @uv           unsigned base32
  @uw           unsigned base64
  @ux           unsigned hexadecimal


odor sizes:

A   1 bit
B   2 bits
C   4 bits
D   1 byte
E   2 bytes
F   4 bytes
G   8 bytes
H   16 bytes
I   32 bytes
J   64 bytes
K   128 bytes
L   256 bytes
M   512 bytes
N   1K
O   2K
P   4K
Q   8K
R   16K
S   32K
T   64K
U   128K
V   256K
W   512K
X   1MB
Y   2MB
Z   4MB

Natural (non-synthetic) hoons

++  play
  ~/  %play
  =>  .(vet |)
  |=  gen=twig
  ^-  type
  ?-  gen
    [^ *]      (cell $(gen p.gen) $(gen q.gen))
    [%bcpt *]  $(gen (~(whip al q.gen) p:(seep %read p.gen)))
    [%brcn *]  (core sut %gold sut [[%0 0] p.gen])
    [%cnts *]  =+  lar=(foil (seek %read p.gen))
               =+  mew=(snub q.gen)
               =+  rag=q.q.lar
               %-  fire
               |-  ^-  (list ,[p=type q=foot])
               ?@  mew
                 rag
               $(mew t.mew, rag q:(tock p.i.mew ^$(gen q.i.mew) rag))
    [%dtkt *]  %noun
    [%dtls *]  [%atom %$]
    [%dtzy *]  ?:(=(%f p.gen) ?>((lte q.gen 1) bean) [%atom p.gen])
    [%dtzz *]  [%cube q.gen ?:(.?(q.gen) %noun [%atom p.gen])]
    [%dttr *]  %noun
    [%dtts *]  bean
    [%dtwt *]  bean
    [%ktbr *]  (wrap(sut $(gen p.gen)) %iron)
    [%ktls *]  $(gen p.gen)
    [%ktpm *]  (wrap(sut $(gen p.gen)) %zinc)
    [%ktsg *]  $(gen p.gen)
    [%ktts *]  (conk(sut $(gen q.gen)) p.gen)
    [%ktwt *]  (wrap(sut $(gen p.gen)) %lead)
    [%sgzp *]  ~_(duck(sut ^$(gen p.gen)) $(gen q.gen))
    [%sggr *]  $(gen q.gen)
    [%tsgr *]  $(gen q.gen, sut $(gen p.gen))
    [%tstr *]  $(gen r.gen, sut (busk p.gen q.gen))
    [%wtcl *]  =+  [fex=(gain p.gen) wux=(lose p.gen)]
               %+  fork
                 ?:(=(%void fex) %void $(sut fex, gen q.gen))
               ?:(=(%void wux) %void $(sut wux, gen r.gen))
    [%zpcb *]  ~_((show %o p.gen) $(gen q.gen))
    [%zpcm *]  (play p.gen)
    [%zpcn ~]  p:seed
    [%zpfs *]  %void
    [%zpsm *]  (cell $(gen p.gen) $(gen q.gen))
    [%zpts *]  %noun
    [%zpzp ~]  %void
    *          =+  doz=~(open ap gen)
               ?:  =(doz gen)
                 ~_  (show [%c 'hoon'] [%q gen])
                 ~|(%play-open !!)
               $(gen doz)
  ==

from http://doc.urbit.org/doc/hoon/tut/3/

in order, the non-synthetic glyphs listed above are:

tiles and tiling:
bcpt	$@	whip?

core construction:
brcn	|%	core constructor	

invocation:
cnts	%=	evaluate with changes/query with changes (can sometimes be used as a function call)

nock operators:
dtkt	.^	"nock operator 11, which in virtual userspace nock (mock) loads a file from the global namespace" [http://doc.urbit.org/doc/hoon/lan/rune/#dotket]
dtls	.+	increment
dtzy	dtzy	"produces a non-cubed atomic constant of odor p and value q" [http://doc.urbit.org/doc/hoon/lan/rune/#dotzey]
dtzz	dtzz	"produces an cubed noun constant of value q and odor p, if q is an atom." [http://doc.urbit.org/doc/hoon/lan/rune/#dotzaz]
dttr	.*	"calculates the nock of subject p, formula q." Like Nock 2. [http://doc.urbit.org/doc/hoon/lan/rune/#dottar]
dtts	.=	equality predicate
dtwt	.?	test if cell or atom. "if the noun is a cell, it returns the loobean & (true); if the noun is an atom, it returns the loobean | (false).". Nock 3. [http://doc.urbit.org/doc/hoon/lan/rune/#dotwut]

type conversions:
ktbr	^|	turn a gold core into an iron core. [http://doc.urbit.org/doc/hoon/tut/6/]
ktls	^+	type cast. "casts the product of q to the type of p, verifying that it contains the type of q." [http://doc.urbit.org/doc/hoon/lan/rune/#ketlus]
ktpm	^&	turn a gold core into a zinc core. [http://doc.urbit.org/doc/hoon/tut/6/]
ktsg	^~	"tells the compiler to compute a constant expression at compile time" [http://doc.urbit.org/doc/hoon/tut/5/]	
ktts	^=	variable assignment. ^=(b 0) means 'b=0'. [http://doc.urbit.org/doc/hoon/tut/3/]
ktwt	^?	turn a gold core into a lead core. [http://doc.urbit.org/doc/hoon/tut/6/]

hints:
sgzp	~!	debug: "for debugging uses only, semantically equivalent to its own twig q. But if compilation fails within q, ~! will show the type of p on the stacktrace." [http://doc.urbit.org/doc/hoon/lan/rune/#sigzap]
sggr	~>	hint. "applies arbitrary hint p to q" [http://doc.urbit.org/doc/hoon/lan/rune/#siggar]

compositions:
tsgr	=>	"=>(a b) means "use a as the subject of b."". Like Nock instruction 7. [http://doc.urbit.org/doc/hoon/tut/3/]
tstr	=*	alias type. "creates a %bull, or alias, type." [http://doc.urbit.org/doc/hoon/lan/rune/#tistar]

conditionals, booleans, tests:
wtcl	?:	if. i think "?: t a b" yields a iff t is True, and b iff t is False. [http://web.archive.org/web/20131014210126/http://www.urbit.org/2013/08/22/Chapter-6-hoons.html]  [http://doc.urbit.org/doc/hoon/tut/3/] [http://doc.urbit.org/doc/hoon/lan/rune/#wutcol]

special operations:
zpcb	!_	debug. "puts debugging information in the stack trace." [http://doc.urbit.org/doc/hoon/lan/rune/#zapcab]
zpcm	!,	"inserts twig q as a constant, typed with the type of twig p." [http://doc.urbit.org/doc/hoon/lan/rune/#zapcom]
zpcn	!%	?? not in http://doc.urbit.org/doc/hoon/lan/rune/ todo
zpfs	!/	debug. "should never be compiled. When compiled with error checking turned on, it reports its subject as an error." [http://doc.urbit.org/doc/hoon/lan/rune/#zapfas]
zpsm	!;	"produces the product of twig q as a [type noun] pair, with twig p defining the type of the type." [http://doc.urbit.org/doc/hoon/lan/rune/#zapsem]
zpts	!=	"produces the formula of twig p as a noun." [http://doc.urbit.org/doc/hoon/lan/rune/#zaptis]
zpzp	!!	crash (void)

Glyphs (Hoon glyph names)

ace  space      gal  <          per  )
bar  |          gar  >          sel  [
bas  \          hax  #          sem  ;
buc  $          hep  -          ser  ]
cab  _          kel  {          sig  ~
cen  %          ker  }          soq  '
col  :          ket  ^          tar  *
com  ,          lus  +          tec  `
doq  "          pam  &          tis  =
dot  .          pat  @          wut  ?
fas  /          pel  (          zap  !

from [208]

Gate, parts of

           glus   gras
          lusgal lusgar
            +<     +>
[formula [sample context]]
    -          +
   hep        lus

from [209]

todo: add stuff to cheat sheet from old sequence, esp. http://web.archive.org/web/20131014210126/http://www.urbit.org/2013/08/22/Chapter-6-hoons.html :

todo: sort the punctuation characters in the Hoon->English table.

todo: notify the Hoon guys about the tutorial omissions noticed in the Hoon->English table.

todo: weed tile constructor?