--- navhome: /docs/ sort: 1 next: true title: Setup and nouns --- # Urbyte 0: Setup and nouns This is the first post in our new Urbyte series. The Urbyte concept is that you, an ordinary programmer, not a kernel hacker or a Haskell magician (not that there's anything wrong with kernel hackers or Haskell magicians) can learn Hoon, Urbit's programming language. We're going to test this daring idea by teaching you Hoon, in easily digestible, byte-size chunks. Each post in the "Urbytes" series is designed to take about 15 minutes to consume. (Maybe 10, if you're a kernel hacker or a Haskell magician.) We'll assume no knowledge of Urbit except for previous lessons. Ideally you have some basic familiarity with programming and can operate the Unix command line. We strongly encourage you to type in all the examples in each Urbyte. Urbytes are short, but not meant to be skimmed. ## Install First, [install Urbit](http://urbit.org/docs/using/install/) on any Mac or Unix machine. On Windows, make a virtual Linux machine using VirtualBox or a similar tool. While you're downloading, read about Urbit ships: ## Ships In the Urbyte exercises you'll be running what we call a "comet". A string starting with `~`, like `~zod`, is what Urbit calls a *ship*. A *ship* is one number which means four things: a network address, a cryptographic identity, a memorable name, and a single virtual computer. We write this number in a base-256 format, where each digit is a syllable. Imagine if your phone number was a pronounceable string which sounded like a name in a foreign language. `~zod` is ship zero (making it a very important ship indeed!). An ordinary user-level ship is a "planet", a 32-bit number which becomes a four-syllable string, like `~talsur-todres`. *Comets*, at 128-bits or 16 syllables, are disposable identities that anyone can make for free to join the live network. Thus, comets make the ideal ship for playing around with Hoon, asking for help from other Urbit devs in [`:talk`](http://urbit.org/docs/using/messaging/) if you need it, and showing off Urbit to your hacker friends. ## Create and restart To create your comet, run: ``` $ cd ~ $ mkdir urbit $ cd urbit $ urbit -c mycomet ``` This will take a few minutes and will spin out a bunch of boot messages. At the end, you'll see something like: ``` ames: on localhost, UDP 31337. http: live (insecure, public) on 8080 http: live ("secure", public) on 8443 http: live (insecure, loopback) on 12321 ~palnul_nocser:dojo> ``` To make sure everything is working, type `(add 2 2)` at the prompt, then hit return. Your screen now shows: ``` ames: on localhost, UDP 31337. http: live (insecure, public) on 8080 http: live ("secure", public) on 8443 http: live (insecure, loopback) on 12321 > (add 2 2) 4 ``` ~palnul_nocser:dojo> That's super awesome! You made your first noun! We'll make a few more in a second. First, quit Urbit with `ctrl-d`: ``` > (add 2 2) 4 ~palnul_nocser:dojo> $ ``` You now have an Urbit image, or *pier*, in the `mycomet` directory. Right now the only thing in your pier is Urbit's system files: ``` $ ls -a /path/to/mycomet ./ ../ .urb/ ``` Restarting uses almost the same command, but without `-c` (which means "create"). There are also fewer startup messages: ``` $ urbit mycomet [...] ames: on localhost, UDP 31337. http: live (insecure, public) on 8080 http: live ("secure", public) on 8443 http: live (insecure, loopback) on 12321 ~palnul_nocser:dojo> ``` Note also that Urbit is an ACID database. You can stop it politely with `ctrl-d`, abruptly with `ctrl-z`, even violently with `kill -9`. None of these should cause Urbit to lose data. If you do manage to corrupt a pier, it's a bug; please let us know. ## Let's make a noun You've already made a noun. Let's make another! *We won't show the `~palnul_nocser:dojo> ` prompt from here on out. We'll just show the echoed command.* ``` ~palnul_nocser:dojo> 42 42 ``` You'll see: ``` > 42 42 ``` ## Understanding nouns A value in Urbit is called a *noun*. A noun is either an *atom* (an unsigned integer of any size) or a *cell* (an ordered pair of any two nouns). In a sentence, a noun is a binary tree whose leaves are numbers. If you know Lisp, a noun is a minimalist S-expression. A noun can't have cycles (pointer loops). An implementation can use dags (shared subtrees), but the programmer can't detect them (there's no pointer equality test). The absence of graph cycles makes nouns much easier to save in persistent storage, send over the network, manage memory for (Urbit has no tracing garbage collector), etc. ## Let's make some atoms So one kind of atom is a number. And the syntax (or at least one syntax) for a number is a decimal, like `42`. Seems legit. But just to be sure we understand this decimal thing, let's make some atoms: ``` > 4 4 ``` Seems pretty straightforward. ``` > 42 42 ``` Why not try it again to make sure? ``` > 420 420 ``` Can we add another zero? ``` > 420 ``` Wat? When you tried to type that next zero and turn `420` into `4200`, Urbit actually *deleted the `0` and beeped at you.* But isn't an atom an unsigned integer of any size? It is. But the syntax is actually `4.200`: ``` > 4.200 4.200 > (mul 42 100) 4.200 ``` Just think of it as "4,200", written the German way with a dot. Why? Long decimals are unreadable. Human beings know this, so we group them in threes. For some historical reason, programming languages never copied this marvelous usability innovation. English notation for decimals is more common than German notation. Unfortunately, dot is URL-safe and comma isn't, and it's nice to have a regular syntax for atoms that's URL-safe. As for why Urbit deleted your zero: it parses your command line as you type, and rejects any characters after the parser stops. ## Let's make some cells There's not much mystery about cells. A cell has a head and a tail, and puts brackets around them: ``` > [42 420] [42 420] ``` `42` is the *head* and `420` is the *tail* of the cell. Cell syntax nests to the right: ``` > [4 [42 420]] [4 42 420] > [4 42 420] [4 42 420] > [[4 42] 420] [[4 42] 420] ``` If you look at these nouns as binary trees, you see ``` [4 [42 420]] [[4 42] 420] . . / \ / \ 4 . . 420 / \ / \ 42 420 4 42 ``` Each number is an atom; each dot is a cell. ## And we're done And we're done! Type `|exit` to exit: ``` ~palnul_nocser:dojo> |exit %drum-exit $ ``` ## Questions and/or exercises And we're done with our very first Urbyte! Here are some questions to think about. These exercises are never mandatory, but they may be fun and/or interesting. Skip them if they're obvious. * What is the right way to represent common data structures as nouns? * A linked list? * A string? A *signed* integer? * A table or associative array? Just try to picture these structures in your head, or draw them on a piece of paper.