Note: much of this content overlaps with at https://urbit.org/docs/glossary/
Urbit and Hoon terms:
a unique number which is assigned by a “sub-noun” of a cell, by virtue of its location within the cell.
the input value. It is a type of payload.
Arms are limbs of the subject that are used for carrying out substantive computations. They are the battery of the core. Arms are also what you might typically call “functions” many other (imperative) languages. It is useful to remember in Hoon that everything is a binary tree, and a generator is also a larger binary tree. Therefore, arms are also accurately thought of as arms of the tree that contain functional code.
unsigned integers (integers, where it is not specified as to whether they are positive or negative)
A means of displaying an atom in another format, such as a string of text, or binary, or hexadecimal. There are a number of standard auras, and custom auras can be created.
Battery is code, a “battery of Nock formulas”. It is the operation to be performed. Payload is the data on which the battery acts.
a tree of nested pairs — the structure used for all data within Hoon( and nock) —
to assign data or code to a face (recalling that a face is somewhat like a variable name, but can also have code elements assigned to it).
the default value for a type; for atoms, the bunt value is 0
to activate an arm to execute the code that they contain or to access the values that they store
a pair of a mark and some data
representing an atom in a particular format, such as text, or unsigned integers, or binary formats.
an ordered pair of nouns. Cells are always pairs
one of the two default urbit applications with terminal interfaces, manages relates to the chat room and publication functions and commands.
arguments of a rune of function
the lowest level of the address space, there are 2^128 comet addresses available. Comet identities are free, and can be ‘mined’ at any time.Functionally, comets are full urbit ships, except that they can not reset their network keys so are fundamentally not permanent like planets are.
Part of the ‘Subject’ – something like the background of information in which your program is being run, which is available to the current running generator. Much like literature is written in time, and therefore has a historical context, to which it might be responsive, our programs operate in a context with which they can interact. Stated differently, the context is part of the available data to your program that is not explicitly provided (the explicitly provided data, by contrast, is the ‘Sample’).
Strings that are encoded as atoms. Cords are always of the aura @t. Cords can be very large numbers when cast as natural numbers @u
a cell consisting of a battery and a payload. [battery payload]
one of two areas of the Urbit terminal where input is taken in from the user. In its resting state with no app taking over computing power it appears as dojo> . Of the two areas that receive input, the dojo is the functional area and can accept commands and direct lines of code, though not all code in Hoon will directly translate to Dojo commands. The other area where information can be inputted through the terminal is called the “chat client”
a multi-armed core that has a sample.
A dry gate is a gate that has a specified type. It does not allow multiple types and simply pass them through – it requires that a certain type be specified and that type is preserved through the gate.
a combination of characters that the language interprets and evaluates as producing a value. Complex expressions are made up of smaller expressions which are called subexpressions.
somewhat similar to a variable name in other languages, but can contain data or more Hoon code. Stated again differently, it can mean a static value or more code to run. This is different from other languages in which variables can only store data
Top-level networking node. Only 256 galaxies in existence, each routing for 256 stars.
like a function in other languages, it takes an input, performs a specified computation, and then produces an output. Without each of these three features, a gate is not complete. Stated in a Hoon way, a gate consists of a battery and a payload. A gate is a core with two distinctive properties: (1) the battery of a gate contains exactly one arm, which has the special name $. The $ arm contains the instructions for the function in question. And (2), the payload of a gate consists of a cell of [sample context]. The sample is the part of the payload that stores the ‘argument’ (i.e., input value) of the function call. The context contains all other data that is needed for computing the $ arm of the gate correctly.
A unit of code, saved as a file in the /home/gen directory of a ship. Is run by entering + before the name of the generator, plus any user input entered after the name of the generator in the proper format
Generator type: naked
This is the only generator type covered in beginning Hoon. A naked generator is a raw dry gate (a core with one arm and a sample) with no specified mark. This lack of a mark is what makes it “naked.” The marks used in the other types of generators listed here form the head of a cell with a tail of a gate. So naked generators have no mark, just their output. Naked generators do not have access to some information that other generators do (such as random numbers/entropy, the time, or the ship’s name) automatically. Naked generators, in terms of incoming data, have access to their sample only.
Generator type: say
A %say generator is a cell of a mark of %say and a gate that produces a cask (a duple cell of a mark and some output). %say generators don’t require an argument (input from the user or from another portion of code feeding into the generator), which differentiates them from naked generators. Further, a %say generator may use arguments, both required and optional ones, and can even access information out of Arvo (effectively information about the environment in which the generator is run).
Generator type: ask
An %ask generator is a cell of a mark of %ask and a gate that produces a cask (a duple cell of a mark and some output). %ask generators operate fairly similarly to %say generators and have many of the same capacities. %ask generators differ from %say generators in that they incorporate types from /sur/sole.hoon and library files from /lib/generators.hoon. These incorporated types and library files allow for interactivity – pausing the program and requesting additional information from the user
Generator type: get
Get generators are a complex form of generator that require an intermediate Hoon understanding to fully process. The very basic idea is that a %get generator can access information from an HTTP request to a website. A %get generator is a cell of a mark of %get and a gate that produces a cask (a duple – two part – cell of a mark and some output). %get generators differ from %say generators, as with %ask generators, in that they incorporate types from /sur/sole.hoon and library files from /lib/generators.hoon A %get generator’s ultimate goal is to take some URL and parse the return data (the entirety of the http response).
the left-most part of the cell – the first element on the left. The head has the face called i. The rest of the cell (everything to the right of the head) is called the tail.
the programming language of Urbit.
some chunk of Hoon code which can be evaluted
the piece of software that takes Nock code (compiled hoon) and performs the intended operation. A component of the urbit binary running on your system.
see “wing notation”
A leaf generally refers to a data only (i.e. no Hoon code) branch in the binary tree. However it can also refer to an %ask used type from sole.
Legs are limbs that store data. Any limb that isn’t an arm is a leg. It is useful to remember in Hoon that everything is a binary tree. Therefore, limbs of the tree that contain data are more easily remembered to be called “legs”
non-null lists. Lists that have contents other than [~].
a type of cell. It’s an ordered collection of items that usually share a type. (there are actually some lists that do not share a type but they are uncommon, so keeping it simple, think of lists as an ordered collection of items that do share a type). Note that all lists are null-terminated, and the “null” is the symbol “sig” which is ~. It can be before the list (outside the brackets to the left) or inside the rightmost bracket. A list can be a null-list if they only contain [~].
literal is a notation for representing a fixed value in source code. A value that may change is a variable, or in Hoon a face. A value that does not change is a literal.
mark is a file-type in the Clay filesystem. A mark is a file that defines the filesystem(?). %say generators use mark to make it clear, to other Arvo computations, exactly what kind of data their output is. This includes information such as type, merge routines, diff routines, and patch algorithms.
a map is a series of “values” and “keys” – I think of this as a vertical list of two columns. on the left, perhaps, you have the value, on the right, you have the key. a map will let us, from that, say “what is the value to key x” or “what is the key to value y”
A mold is a function that coerces a noun to a type or crashes. Mold is a very good name for it. It says I have some data, I want it in this shape – stuff it in there and if it fits, leave it, and if it doesn’t give up.
A moon is like a local address within a planet. Each planet can spawn 2^32 moons, which could be used for different devices, different users(e.g., children) or just different access locations.
Occurring as a cell with another cell.
Noun – either an atom or a cell
0 / no value represented by ~, “sig”
A list consisting only of sig [~]
the data on which an operation is performed.
The file folder where the ship’s files are stored, usually located in the same director as the Urbit executable file.
A network address intended for use by a human being. There are 2^32 planet addresses available. Planets have the ability to reset their own network keys, as well as to issue/reset network keys for their spawned moons.
Pretty-printing is the reproduction of input or output content in its “most concise” form. For instance, you may know that lists are a series of nested cells that are null terminated – like this: [1 [2 [3 [4 ~]]]]. That aforementioned list is pretty-printed (based on a variety of rules which you will learn) as ~[1 2 3 4]. Pretty-printing is intended to make output more human legible and also more aesthetically pleasing.
ascii digraphs (two ascii characters that are put together to form one symbol), which define a particular function in the Hoon language. Each character, that is to say each ½ of a rune, is a pronounceable character. It’s a good idea to learn how to pronounce each character, so that you can read and communicate hoon code out loud.
The part of the payload that stores the ‘argument’ (i.e., input value) of the function call
A general term for all of the types of entities that can run as an independently networked entity with Urbit. Within this class are: Galaxy, Star, Planet, Moon and Comet
A casual term meaning the location on one’s system where multiple piers are stored.
Sinking a ship can refer to either crashing your ship temporarily or, more drastically, breaching your ship’s continuity. If you see that a peer of yours “has sunk” according to the dojo, this indicates the latter, though some people mean the former in common parlance.
Source Code is instructive code for a computer written out in “long form.” That is to say, no compiler has done any work to perhaps optimize the code for execution in the actual operating environment. This differentiation from code that you write, at first, will not be extremely important. What you should know now is that the dojo is actively parsed as you enter in code. This prevents you from entering code that is syntactically invalid (you can still make logical mistakes, or type mistakes).
Second-tier (mid-level) networking node. There are 65,536 stars in existence (256 per galaxy), each routing for up to 65,536. 65,536 is the total number of planets that a star may spawn.
The subject and the operating environment are two terms that are close to analogous, but differentiated to some degree, as well. Effectively, we can think of the Environment as the absolute boundaries of the Subject. The Environment is the entirety of the data available to your Urbit – it is, you might imagine, the entire interior body of your Urbit up to and inclusive of its skin. In contrast, the Subject is the immediately focused-on and discussed portion of that corpus for the purpose of executing some code. Various levels of programs can be exposed to various delimited amounts of the operating Environment, as is necessary for their faithful execution.
As referenced in the definition of “subject/environment”, the Subject is something like a delimited portion of the operating environment, fenced off for the evaluation of some hoon. I like to think of this as a “how far you zoom in the camera on the environment.” You can zoom out, and include vast swaths of the Environment, or zoom very far in and have your program really only consider itself in evaluation (and hoon.hoon almost always). Working w/ finding the right amount of Subject to include in a Hoon program is a skill you will develop over time as we start incorporating libraries and other extraneous elements into our programs.
The dojo subject has some preset values in it. It includes faces like our (our ship’s name) now (the current datetime) and eny (many bits of entropy for use in random number generation). It also has hoon.hoon implicitly tacked to it, so your standard library functions are always available. Furthermore, you can pin values to the dojo using this notation: =face <value>. Please note that if you pin a face to the dojo, it will always be available in the dojo until it is unset using just =face. It is wise to keep your dojo clean of these pinned values if you’re just testing. Anything you do in dojo after pinning a face will implicitly have that value available to it as well; that is to say if I set =a 1, then I write some gate b, that gate b will have a=1 implicit in it’s subject, even if I unpin a from the dojo at some later point. This isn’t incredibly critical, but you should be aware of it.
Wikipedia: syntactic sugar is syntax within a programming language that is designed to make things easier to read or to express. It makes the language “sweeter” for human use.
A tape is one way of handling UTF-8 (https://en.wikipedia.org/wiki/UTF-8). Tapes produced by putting double quotes around some UTF-8 string, “like this here.” Importantly, tapes are actually lists of individual UTF-8 elements (cords) – being able to handle UTF-8 characters as both atoms (cords) and lists (null terminated cell) of text, we are given the liberty to perform a wide array of Standard Library functions against our text. For instance, by using a list, we can address individual sub-items “of a string like this”, or build a string, head first – something we could not do with just the atomic structure.
everything in the cell that is not the head (the right non-head portion of the cell). The tail has a face called t
Terms are constant values that are used to tag data using the type system, and are always of the aura @tas. These are strings preceded with a % and made up of lower-case letters, numbers, and hyphens, i.e., ‘kebab case’. The first character after the % must be a letter. For example, %a, %hello, %this-is-kebab-case123. You can think of these as tags (metadata), like hashtags, or flags, or symbols, to indicate meaning to some part of the code.
a recursion loop
“A type is usually understood to be a set of values. Hoon values are all nouns, so a Hoon type is a set of nouns.”
One of the Urbit modules that performs essential system operations. The modules are ames, behn, clay, dill, eyre, ford, gall, iris and jael.
Pronounced “Vair”, Vere is the Nock runtime environment and Urbit virtual machine.
As in “wet core” – this means that the core does not have specified types. it allows the types of the arguments to pass through, in effect meaning that one doesn’t need a put for each type of possible map (@ud to @tas, etc). “By” (which is the door in hoon.hoon map logic) is an example of a wet core. When you pass arguments to a wet gate, their types are preserved and type analysis is done at the definition site of the gate.
A wing is the global term for an arm or leg (or a path of arms and legs), the quadrilateral to our trapezoid and rhombus. A wing some portion of / path down the binary tree down which your Urbit can follow or search. By referencing a wing, you can identify where Hoon should look for some specific face, value, or function.
Wing notation, or lark notation is a means of accessing a specific wing of a larger structure (possibly a core). Wing notation uses – and < to indicate the head, and + and > to indicate the tail of the binary structure, starting at the top of the indicated larger structure. So, if we had a large structure called “struct”, we could reference “the head of the tail” by typing +<.struct.
One of the essential components or “vanes” of the Urbit OS. Ames is the peer-to-peer networking vane, and is also the overall name of the Urbit network.
One of the essential components or “vanes” of the Urbit OS. Behn is the timer vane.
One of the essential components or “vanes” of the Urbit OS. Clay is the filesystem and revision-control vane.
One of the essential components or “vanes” of the Urbit OS. Dill is the terminal-driver vane.
One of the essential components or “vanes” of the Urbit OS. Eyre is the HTTP vane.
One of the essential components or “vanes” of the Urbit OS. Ford is the build-system vane.
One of the essential components or “vanes” of the Urbit OS. Gall is the application vane.
One of the essential components or “vanes” of the Urbit OS. Iris is the server HTTP vane.
One of the essential components or “vanes” of the Urbit OS. Jael is the security vane.