git.iko.soy/urbit.org
on 63b60ca help sign in
urbit.org/docs/urbyte/0.md
284 lines 7.0 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](../../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 "comet". A string starting with `~`, like `~zod`, is what Urbit
40calls a *ship*.
42A *ship* is one number which means four things: a network address,
43a cryptographic identity, a memorable name, and a single virtual
44computer.
46We write this number in a base-256 format, where each digit is a
47syllable. Imagine if your phone number was a pronounceable
48string which sounded like a name in a foreign language. `~zod`
49is ship zero (making it a very important ship indeed!). An ordinary
50user-level ship is a "planet", a 32-bit number which becomes
51a four-syllable string, like `~talsur-todres`.
53*Comets*, at 128-bits or 16 syllables, are
54disposable identities that anyone can make for free to
55join the live network. Thus, comets make the ideal ship for
56playing around with Hoon, asking for help from other Urbit devs in [Talk](../../using/messaging/) if you
57need it, and showing off Urbit to your hacker friends.
59## Create and restart
61To create your comet, run:
63```
64$ cd ~
65$ mkdir urbit
66$ cd urbit
67$ urbit -c mycomet
68```
70This will take a few minutes and will spin out a bunch of boot
71messages. At the end, you'll see something like:
73```
74ames: on localhost, UDP 31337.
75http: live (insecure, public) on 8080
76http: live ("secure", public) on 8443
77http: live (insecure, loopback) on 12321
78~palnul_nocser:dojo>
79```
81To make sure everything is working, type `(add 2 2)` at the
82prompt, then hit return. Your screen now shows:
84```
85ames: on localhost, UDP 31337.
86http: live (insecure, public) on 8080
87http: live ("secure", public) on 8443
88http: live (insecure, loopback) on 12321
89> (add 2 2)
91~palnul_nocser:dojo>
92```
94That's super awesome! You made your first noun! We'll make a
95few more in a second. First, quit Urbit with `ctrl-d`:
97```
98> (add 2 2)
100~palnul_nocser:dojo>
102```
104You now have an Urbit image, or *pier*, in the `mycomet` directory.
105Right now the only thing in your pier is Urbit's system files:
107```
108$ ls -a /path/to/mycomet
109./ ../ .urb/
110```
112Restarting uses almost the same command, but without `-c` (which
113means "create"). There are also fewer startup messages:
115```
116$ urbit mycomet
117[...]
118ames: on localhost, UDP 31337.
119http: live (insecure, public) on 8080
120http: live ("secure", public) on 8443
121http: live (insecure, loopback) on 12321
122~palnul_nocser:dojo>
123```
125Note also that Urbit is an ACID database. You can stop it
126politely with `ctrl-d`, abruptly with `ctrl-z`, even violently with `kill
127-9`. None of these should cause Urbit to lose data. If you do
128manage to corrupt a pier, it's a bug; please let us know.
130## Let's make a noun
132You've already made a noun. Let's make another!
134*We won't show the `~palnul_nocser:dojo> ` prompt from here on out.
135We'll just show the echoed command.*
138```
139~palnul_nocser:dojo> 42
14042
141```
143You'll see:
145```
146> 42
14742
148```
150## Understanding nouns
152A value in Urbit is called a *noun*. A noun is either an *atom*
153(an unsigned integer of any size) or a *cell* (an ordered pair of
154any two nouns).
156In a sentence, a noun is a binary tree whose leaves are numbers.
157If you know Lisp, a noun is a minimalist S-expression. A noun
158can't have cycles (pointer loops). An implementation can use
159dags (shared subtrees), but the programmer can't detect them
160(there's no pointer equality test).
162The absence of graph cycles makes nouns much easier to save in
163persistent storage, send over the network, manage memory for
164(Urbit has no tracing garbage collector), etc.
166## Let's make some atoms
168So one kind of atom is a number. And the syntax (or at least one
169syntax) for a number is a decimal, like `42`. Seems legit.
171But just to be sure we understand this decimal thing, let's make
172some atoms:
174```
175> 4
177```
179Seems pretty straightforward.
181```
182> 42
18342
184```
186Why not try it again to make sure?
188```
189> 420
190420
191```
193Can we add another zero?
195```
196> 420
197```
199Wat? When you tried to type that next zero and turn `420` into
200`4200`, Urbit actually *deleted the `0` and beeped at you.*
202But isn't an atom an unsigned integer of any size? It is.
203But the syntax is actually `4.200`:
205```
206> 4.200
2074.200
208> (mul 42 100)
2094.200
210```
212Just think of it as "4,200", written the German way with a dot.
214Why? Long decimals are unreadable. Human beings know this, so
215we group them in threes. For some historical reason, programming
216languages never copied this marvelous usability innovation.
218English notation for decimals is more common than German
219notation. Unfortunately, dot is URL-safe and comma isn't, and
220it's nice to have a regular syntax for atoms that's URL-safe.
222As for why Urbit deleted your zero: it parses your command line
223as you type, and rejects any characters after the parser stops.
225## Let's make some cells
227There's not much mystery about cells. A cell has a head and a
228tail, and puts brackets around them:
230```
231> [42 420]
232[42 420]
233```
235`42` is the *head* and `420` is the *tail* of the cell. Cell
236syntax nests to the right:
238```
239> [4 [42 420]]
240[4 42 420]
242> [4 42 420]
243[4 42 420]
245> [[4 42] 420]
246[[4 42] 420]
247```
249If you look at these nouns as binary trees, you see
251```
252 [4 [42 420]] [[4 42] 420]
253 . .
254 / \ / \
255 4 . . 420
256 / \ / \
257 42 420 4 42
258```
260Each number is an atom; each dot is a cell.
262## And we're done
264And we're done! Type `|exit` to exit:
266```
267~palnul_nocser:dojo> |exit
268%drum-exit
270```
272## Questions and/or exercises
274And we're done with our very first Urbyte! Here are some questions to
275think about. These exercises are never mandatory, but they may
276be fun and/or interesting. Skip them if they're obvious.
278* What is the right way to represent common
279data structures as nouns?
280* A linked list?
281* A string? A *signed* integer?
282* A table or associative array?
284Just try to picture these structures in your head, or draw them on a piece of paper.