git.iko.soy/urbit.org
on 6d45ede help sign in
urbit.org/docs/byte/0.md
277 lines 6.9 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$ git clone https://github.com/urbit/arvo/
66$ urbit -FI ~zod -A arvo -c myship
67```
69This will take about 30 seconds and spin out a bunch of boot
70messages. At the end, you'll see:
72```
73ames: on localhost, UDP 31337.
74http: live (insecure, public) on 8080
75http: live ("secure", public) on 8443
76http: live (insecure, loopback) on 12321
77~zod:dojo>
78```
80To make sure everything is working, type `(add 2 2)` at the
81prompt, then hit return. Your screen now shows:
83```
84ames: on localhost, UDP 31337.
85http: live (insecure, public) on 8080
86http: live ("secure", public) on 8443
87http: live (insecure, loopback) on 12321
88> (add 2 2)
90~zod:dojo>
91```
93That's super awesome! You made your first noun! We'll make a
94few more in a second. First, quit Urbit with `ctrl-d`:
96```
97> (add 2 2)
99~zod:dojo>
101```
103You now have an Urbit image, or *pier*, in the `myship` directory.
104Right now the only thing in your pier is Urbit's system files:
106```
107$ ls -a myship
108./ ../ .urb/
109```
111Restarting uses almost the same command, but without `-c` (which
112means "create"). There are also fewer startup messages:
114```
115$ urbit -FI ~zod myship
116[...]
117ames: on localhost, UDP 31337.
118http: live (insecure, public) on 8080
119http: live ("secure", public) on 8443
120http: live (insecure, loopback) on 12321
121~zod:dojo>
122```
124Note also that Urbit is an ACID database. You can stop it
125politely with `ctrl-d`, abruptly with `ctrl-z`, even violently with `kill
126-9`. None of these should cause Urbit to lose data. If you do
127manage to corrupt a pier, it's a bug; please let us know.
129## Let's make a noun
131We already made a noun. Let's make another. (We won't show the
132`~zod:dojo> ` prompt in future, just the echoed command.)
134```
135~zod:dojo> 42
136```
138You'll see:
140```
141> 42
14242
143~zod:dojo>
144```
146## Understanding nouns
148A value in Urbit is called a *noun*. A noun is either an *atom*
149(an unsigned integer of any size) or a *cell* (an ordered pair of
150any two nouns).
152In a sentence, a noun is a binary tree whose leaves are numbers.
153If you know Lisp, a noun is a minimalist S-expression. A noun
154can't have cycles (pointer loops). An implementation can use
155dags (shared subtrees), but the programmer can't detect them
156(there's no pointer equality test).
158The absence of graph cycles makes nouns much easier to save in
159persistent storage, send over the network, manage memory for
160(Urbit has no tracing garbage collector), etc.
162## Let's make some atoms
164So one kind of atom is a number. And the syntax (or at least one
165syntax) for a number is a decimal, like `42`. Seems legit.
167But just to be sure we understand this decimal thing, let's make
168some atoms:
170```
171> 4
173```
175Seems pretty straightforward.
177```
178> 42
17942
180```
182Why not try it again to make sure?
184```
185> 420
186420
187```
189Can we add another zero?
191```
192~zod:dojo> 420
193```
195Wat? When you tried to type that next zero and turn `420` into
196`4200`, Urbit actually *deleted the `0` and beeped at you.*
198But isn't an atom an unsigned integer of any size? It is.
199But the syntax is actually `4.200`:
201```
202> 4.200
2034.200
204> (mul 42 100)
2054.200
206```
208Just think of it as "4,200", written the German way with a dot.
210Why? Long decimals are unreadable. Human beings know this, so
211we group them in threes. For some historical reason, programming
212languages never copied this marvelous usability innovation.
214English notation for decimals is more common than German
215notation. Unfortunately, dot is URL-safe and comma isn't, and
216it's nice to have a regular syntax for atoms that's URL-safe.
218As for why Urbit deleted your zero: it parses your command line
219as you type, and rejects any characters after the parser stops.
221## Let's make some cells
223There's not much mystery about cells. A cell has a head and a
224tail, and puts brackets around them:
226```
227> [42 420]
228[42 420]
229```
231`42` is the *head* and `420` is the *tail* of the cell. Cell
232syntax nests to the right:
234```
235> [4 [42 420]]
236[4 42 420]
238> [4 42 420]
239[4 42 420]
241> [[4 42] 420]
242[[4 42] 420]
243```
245If you look at these nouns as binary trees, you see
247```
248 [4 [42 420]] [[4 42] 420]
249 . .
250 / \ / \
251 4 . . 420
252 / \ / \
253 42 420 4 42
254```
256Each number is an atom; each dot is a cell.
258## And we're done
260And we're done! Type `|exit` to exit:
262```
263~zod:dojo> |exit
264%drum-exit
266```
268## Questions and/or exercises
270And we're done with our very first Urbyte! Here's a question to
271think about. These exercises are never mandatory, but they may
272be fun and/or interesting. Skip them if they're obvious.
274The question today is: what is the right way to represent common
275data structures as nouns? A linked list? A string? A *signed*
276integer? A table or associative array? Just try to picture
277these structures in your head, or draw them on a piece of paper.