1.5.1 What are Urbit, Nock and Hoon? (the basics)

There are enough new concepts to be covered that we will describe a few components in “broad brushstrokes” here first, and then will go into greater detail a bit further down in the introduction.

We presume that you understand what Urbit is overall, in terms of a system of networked computers running a new operating system, which has a hierarchical address / routing system (i.e. there are galaxies, stars, planets, moons and so on), and which allows for people to build communities with a peer-to-peer type system of computer networking.

We cannot jump into the Hoon language without mentioning Nock at least briefly, and beware, this is going to get a bit jargon-y. Urbit was built from scratch, on top of a set of logic rules whose specifications are short enough that the whole thing can fit on a t-shirt. These sets of rules make up a “low-level function”, “Nock.” Nock therefore is a pure mathematical function, and inherent to the functioning of Nock is that it operates on binary trees of integers (meaning things are always structured as pairs of integer numbers) and when it runs on / interprets something, it produces a new binary tree of integers. Worry you not, about understanding all of that! But know that someday you’ll come back to this paragraph and think to yourself “oh yeah, of course it does!”

The programming language “Hoon” is built on top of Nock and contains many more operators (runes and a standard library) that use those logic rules, but they also go way beyond those basic rules in their complexity, and this makes higher level programming possible. Ultimately, all Hoon code is compiled down to (i.e. converted to) Nock and is ultimately run by a Nock interpreter. Someday perhaps someone will make an actual computer chip using these Nock logic rules, and then, zoom zoom, everything Urbit will be super fast.

While it is not strictly necessary to study Nock, and in fact might be overwhelming to the newcomer, the adventuresome and curious among you might enjoy reading more: https://urbit.org/docs/tutorials/nock/example/ is a great place to see the Urbit take on Nock, while a recent three part tutorial is wonderfully approachable and has been created by community member ~timluc-miptev and can be found here: https://blog.timlucmiptev.space/. With these tools, and having already learned the binary cell system from the Urbit documentation first, one can garner a full understanding of Nock without too much effort.

1.6 Hoon Programs and Hoon’s weaknesses

Hoon is no different from the person making our PB&J, or the computer interpreting our BASIC program – Hoon is very naive when it comes to reading your instructions. So, in order to write our programs effectively, it’s important that we discuss some of the ways in which our Hoon interpreter will be naive.

1.6.1 Types of Naivety in Hoon:

n order to avoid confusion later, there are a number of things in Hoon that one should recognize as being particularly naive and therefore in need of special attention on the part of the programmer. Let’s begin with those concepts.

1.6.2 Aura/Type

If you haven’t seen it already in the website tutorial intro, know this: Hoon understands everything as natural numbers (a positive integer or zero). Fortunately, we can store many different types of data as single positive integers(Atoms) using Hoon’s aura system(and indeed we can store any sort of data as a tree of positive integers using Hoon’s type system.)

Since many different sorts of data can be stored as Atoms(single integers), it is critical to tell the interpreter HOW you mean for it to understand a given value. A human reader has no idea how to interpret an extremely-large number like:
156.434.381.737.501.786.786.292.313.902.471.469.107.061.393.755.
230.168.566.658.352.304.823.233.578.944.566.754.040.486.687.720.
494.504.165.807.741.020.743.911.520.672.975.909.287.079.241.267.
942.638.443.580.249.825.242.849.353

However, if we tell our Hoon interpreter to treat this value as Aura @t, we can see it says:

'I am intended to be read as a cord! (i.e. a string of ASCII characters)'

Consider this image with real world things that have a base reality (their material form) and then can be interpreted various ways with their names. If you did not know what language they were in, you would think that the word “pain” means something uncomfortable, pane means glass, and pan is a saucepan, and if the base reality was “bread” then you would be wrong. Similar to the many ways numbers can be represented in Hoon, even if it looks familiar to us, we must state exactly how it is expected to be represented or is represented, or we will either get errors, or simply be unable to continue. So don’t forget, you’ve got to keep those Auras in mind.

While you don’t have to memorize all auras up front, if you want to have a study aid, a flashcards deck (used with the ANKI program) can be found here. General study materials can all be found in the Urbit “Hooniverse” group links pages.

1.7 Naivety: Stopping / finishing a program

At times, elements of your programming need to be ‘closed out’ for Hoon to know that it is done. Therefore you must occasionally tell Hoon when to stop doing a particular thing. Nearly every program you write will need to have a ‘condition’ to know when to stop applying rules (bread peanut butter jelly bread peanut butter jelly bread — OH STOP! I forgot STOP as a command), so that it does not keep going on to infinite loops.

1.7.1 Naivety: The ‘work product’ must be declared

Hoon is built for you to state what is going to be delivered early in the program and the program will only complete its work when that actual, specific work product has been delivered as originally specified. You must tell Hoon a version of “we are going to make this, specifically” and then you go make it. In a way, this is another version of the naivety of needing to tell Hoon when to stop, because the program stops automatically when the work is done. Of course this is only workable if you have declared first what needs to be done.

This is very important for the new coder: so, when you piece apart some code, or when you learn terms, you should be mentally understanding whether the tool you are learning is 1) establishing rules, 2) doing some decision-making, or 3) performing some computation and then stopping when done. If you pay lots of attention to these categories of code components, then you will quickly learn to tell these areas apart and be better able to make your way around understanding a piece of code.