git.iko.soy/urbit.org
on 021ce99 help sign in
urbit.org/docs/byte/0.md
275 lines 6.8 kB history raw
1---
2navhome: /docs
3sort: 1
4next: true
5title: Setup and nouns
6---
8# Urbyte 0: setup and nouns
10This is the first post in our new Urbyte series.
12The Urbyte concept is that you, an ordinary programmer, not a
13kernel hacker or a Haskell magician (not that there's anything
14wrong with kernel hackers or Haskell magicians) can learn Hoon,
15Urbit's programming language.
17We're going to test this daring idea by teaching you Hoon, in
18easily digestible, byte-size chunks. Each post in the "Urbytes"
19series is designed to take about 15 minutes to consume. (Maybe
2010, if you're a kernel hacker or a Haskell magician.)
22We'll assume no knowledge of Urbit except for previous lessons.
23Ideally you have some basic familiarity with programming and can
24operate the Unix command line.
26We strongly encourage you to type in all the examples in each
27Urbyte. Urbytes are short, but not meant to be skimmed.
29## Install
31First, [install Urbit](http://urbit.org/docs/using/install/) on any
32Mac or Unix machine. On Windows, make a virtual Linux machine
33using VirtualBox or a similar tool.
35While you're downloading, read about Urbit ships:
37## Ships
39In the Urbyte exercises you'll be running what we call a "fake
40`~zod`." A string starting with `~`, like `~zod`, is what Urbit
41calls a *ship*.
43A *ship* is one number which means four things: a network address,
44a cryptographic identity, a memorable name, and a single virtual
45computer.
47We write this number in a base-256 format, where each digit is a
48syllable. Imagine if your phone number was a pronounceable
49string which sounded like a name in a foreign language.
51`~zod` is ship zero, making it a very important ship indeed.
52Your "fakezod" thinks it's `~zod`, but no one can talk to it.
53(An ordinary user-level ship is a 32-bit number which becomes
54a four-syllable string, like `~talsur-todres`.)
56A fakezod is not the true Urbit experience, of course. But it's
57ideal if all you want to do is play around with Hoon. If you
58have a real urbit ship, of course you can use that instead.
60## Create and restart
62To create your fakezod, run:
64```
65$ urbit -FI ~zod -c myship
66```
68This will take about 30 seconds and spin out a bunch of boot
69messages. At the end, you'll see:
71```
72ames: on localhost, UDP 31337.
73http: live (insecure, public) on 8080
74http: live ("secure", public) on 8443
75http: live (insecure, loopback) on 12321
76~zod:dojo>
77```
79To make sure everything is working, type `(add 2 2)` at the
80prompt, then hit return. Your screen now shows:
82```
83ames: on localhost, UDP 31337.
84http: live (insecure, public) on 8080
85http: live ("secure", public) on 8443
86http: live (insecure, loopback) on 12321
87> (add 2 2)
89~zod:dojo>
90```
92That's super awesome! You made your first noun! We'll make a
93few more in a second. First, quit Urbit with `^D`:
95```
96> (add 2 2)
98~zod:dojo>
100```
102You now have an Urbit image, or *pier*, in the `myship` directory.
103Right now the only thing in your pier is Urbit's system files:
105```
106$ ls -a myship
107./ ../ .urb/
108```
110Restarting uses almost the same command, but without `-c` (which
111means "create"). There are also fewer startup messages:
113```
114$ urbit -FI ~zod myship
115[...]
116ames: on localhost, UDP 31337.
117http: live (insecure, public) on 8080
118http: live ("secure", public) on 8443
119http: live (insecure, loopback) on 12321
120~zod:dojo>
121```
123Note also that Urbit is an ACID database. You can stop it
124politely with `^D`, abruptly with `^Z`, even violently with `kill
125-9`. None of these should cause Urbit to lose data. If you do
126manage to corrupt a pier, it's a bug; please let us know.
128## Let's make a noun
130We already made a noun. Let's make another. (We won't show the
131`~zod:dojo> ` prompt in future, just the echoed command.)
133```
134~zod:dojo> 42
135```
137You'll see:
139```
140> 42
14142
142~zod:dojo>
143```
145## Understanding nouns
147A value in Urbit is called a *noun*. A noun is either an *atom*
148(an unsigned integer of any size) or a *cell* (an ordered pair of
149any two nouns).
151In a sentence, a noun is a binary tree whose leaves are numbers.
152If you know Lisp, a noun is a minimalist S-expression. A noun
153can't have cycles (pointer loops). An implementation can use
154dags (shared subtrees), but the programmer can't detect them
155(there's no pointer equality test).
157The absence of graph cycles makes nouns much easier to save in
158persistent storage, send over the network, manage memory for
159(Urbit has no tracing garbage collector), etc.
161## Let's make some atoms
163So one kind of atom is a number. And the syntax (or at least one
164syntax) for a number is a decimal, like `42`. Seems legit.
166But just to be sure we understand this decimal thing, let's make
167some atoms:
169```
170> 4
172```
174Seems pretty straightforward.
176```
177> 42
17842
179```
181Why not try it again to make sure?
183```
184> 420
185420
186```
188Can we add another zero?
190```
191~zod:dojo> 420
192```
194Wat? When you tried to type that next zero and turn `420` into
195`4200`, Urbit actually *deleted the `0` and beeped at you.*
197But isn't an atom an unsigned integer of any size? It is.
198But the syntax is actually `4.200`:
200```
201> 4.200
2024.200
203> (mul 42 100)
2044.200
205```
207Just think of it as "4,200", written the German way with a dot.
209Why? Long decimals are unreadable. Human beings know this, so
210we group them in threes. For some historical reason, programming
211languages never copied this marvelous usability innovation.
213English notation for decimals is more common than German
214notation. Unfortunately, dot is URL-safe and comma isn't, and
215it's nice to have a regular syntax for atoms that's URL-safe.
217As for why Urbit deleted your zero: it parses your command line
218as you type, and rejects any characters after the parser stops.
220## Let's make some cells
222There's not much mystery about cells. A cell has a head and a
223tail, and puts brackets around them:
225```
226> [42 420]
227[42 420]
228```
230`42` is the *head* and `420` is the *tail* of the cell. Cell
231syntax nests to the right:
233```
234> [4 [42 420]]
235[4 42 420]
237> [4 42 420]
238[4 42 420]
240> [[4 42] 420]
241[[4 42] 420]
242```
244If you look at these nouns as binary trees, you see
246```
247 [4 [42 420]] [[4 42] 420]
248 . .
249 / \ / \
250 4 . . 420
251 / \ / \
252 42 420 4 42
253```
255Each number is an atom; each dot is a cell.
257## And we're done
259And we're done! Press `^D` to exit:
261```
262~zod:dojo> ^D
264```
266## Questions and/or exercises
268And we're done with our very first Urbyte! Here's a question to
269think about. These exercises are never mandatory, but they may
270be fun and/or interesting. Skip them if they're obvious.
272The question today is: what is the right way to represent common
273data structures as nouns? A linked list? A string? A *signed*
274integer? A table or associative array? Just try to picture
275these structures in your head, or draw them on a piece of paper.