on master help sign in
Urbytes etc.
commitf98ccdc909888fb909d959c22f23e2767c174d54 authorC. Guy Yarvin <cgyarvin@gmail.com> dateMon 18 Jul 2016, 16:28 (10 years ago) parent750d967
10 files changed+1375−14
docs.md+2−1 docs/about/objections.md+266 docs/arvo.md+4−4 docs/byte.md+11 docs/byte/0.md+273 docs/byte/1.md+349 docs/byte/2.md+464 docs/hoon.md+4−5 docs/nock.md+1−1 docs/using.md+1−3
docs.md+2−1
@@ -24,7 +24,8 @@ in Arvo will teach you to build high-level programs and interact with the networ
2424Dig into the mechanics of Urbit with [Core Hoon](hoon). Refer back
2525there for pure-code exercises and functions in the [standard library](hoon/library).
2626
27−Registered academics are required to start with the [Nock definition](nock/definition) and work upward from there.
27+Anyone obsessed with math, theory, fundamentals of computation,
28+etc, should start with the [Nock definition](nock/definition) and work upward from there.
2829
2930</div>
3031
docs/about/objections.mdnew file+266
@@ -0,0 +1,266 @@
1+
2+# Common objections to Urbit
3+
4+"We choose to go to the moon, not because it is easy, but because it is hard." -- John F. Kennedy
5+
6+We're strong believers in crowdsourced criticism. We've heard a lot of great objections from all kinds of directions. Surely there's more out there -- if you think of a reason Urbit can't work, and it's not listed here, please add it in a comment at the bottom, post it somewhere and send us a link, etc, etc.
7+
8+## Urbit is a total scamcoin. It's 100% premined.
9+
10+TLDR: yeah. But at least it's not the DAO.
11+
12+Like a cryptocurrency, Urbit is a digital title. But Urbit is digital land, not digital money. If you assess it as a currency, it's a lousy currency. If you assess a cat as a dog, it's a lousy dog.
13+
14+In real-world economics, the crucial distinction between land and money is that land (a) has intrinsic utility and (b) is non-fungible.
15+
16+Because of (b) alone, frictionless transactions in land are impossible. A blockchain is only needed to ensure zero-cost high-frequency transactions. So digital land doesn't need a blockchain. Which means it doesn't need mining.
17+
18+Of course, just because a digital title system doesn't need mining, doesn't mean it can't distribute an initial allocation by proof-of-work -- or by any other arbitrary method which is careful not to benefit the system's own developers. Could we give away the Urbit address space randomly? Sure. But why?
19+
20+Probably the purest design is the "proof-of-burn" initial allocation used by some coins. By any standard, proof-of-burn is technically beautiful and results in an extraordinary level of ethical independence. We can't help but admire it.
21+
22+But any altcoin or metacoin is just way less work than Urbit. An altcoin can afford to burn even its creation energy, capturing no value at all from its seigniorage. Your altcoin doesn't have a clean-slate OS to fund, and no one started building it in 2002.
23+
24+Ethically, what makes "premining" feel wrong is that the creators of the currency are rewarded disproportionately for their effort. The scamcoin is a get-rich-quick scheme, vaguely pyramid-shaped. Nothing about Urbit matches this pattern at all.
25+
26+To put it bluntly, Galen drives a 2004 Saab and Curtis drives a moldy '99 Cougar covered with raven shit. And we both love cars. We also have kids. And our spouses are more skeptical of Urbit than anyone else could ever be. (Our next startup definitely *will* be a get-rich-quick scheme, though.)
27+
28+Curtis created Urbit. So by the [homesteading principle], he started out owning all of it. But by now, Urbit's 8-bit galaxies have already been distributed among [57 separate individuals](). Curtis owns 4 -- or 24, counting his whole family. (Some of whom he still owes money.)
29+
30+Tlon, the corporation which still runs Urbit development, has 95. (Without Tlon, there is basically no Arvo.) 50 are reserved for a hypothetical Urbit Foundation. Tlon employees have another 16.
31+
32+The rest of the galaxies belong to donors, investors, contributors, contest winners, and just random people who were in the right place at the right time. One is a Silicon Valley tycoon. Another is an Orthodox nun in a monastery in Greece. A couple are ex-Tlon employees who might totally hate us. There is nothing they all have in common, which is sort of the point.
33+
34+This property distribution looks a lot like land ownership in the real world -- complex and asymmetrical. That's no accident. If you have a problem living in New York because New York's real estate is not distributed equally among its residents, you may have a similar problem with Urbit. The reality is that Urbit, like New York, wasn't born yesterday and comes with a complex ownership history which we couldn't possibly change, even if we wanted to.
35+
36+Also, even in Manhattan you can just sleep in your van, and in Urbit you can always make your own comet. But people can't be prevented from thinking this means you're a weirdo.
37+
38+## Urbit isn't even really decentralized! It has a government!
39+
40+TLDR: yeah. But at least it's not the DAO.
41+
42+Real TLDR: it's technically impossible for Urbit to be decentralized at this stage of its life. Urbit is designed to achieve decentralization, not be born with it.
43+
44+A young network can't afford to be decentralized. It has to act as a unit. Because it has no network effect, it needs every scrap of efficiency it can get. Right now, Urbit needs a central government about ten times over.
45+
46+As we found out with the DAO, if a network isn't ready to be decentralized, its developers shouldn't even try. If Ethereum is hard-forked to roll back the DAO (which looks like the most probable result), it acknowledges that it both has a central government, and needs a central government. Decentralization is good. Pretend decentralization -- "decentralization theater" -- is harmful, and not a effective path to actual decentralization.
47+
48+Urbit did not have to get hacked to realize that a decentralized network can only be bootstrapped by a central government. It's part of Urbit's basic design. For example, by default your urbit upgrades its OS automatically (like an "evergreen" browser) with signed network updates. Whoever signs these updates is a central government by definition.
49+
50+But the test of a free software project is whether it can fork. So long as the unity of the PKI and the protocol is maintained, Urbit development can fork easily without disrupting the network. Any stress will fragment this central government, and as it fragments it grows more limited and stable.
51+
52+Urbit is designed to govern itself collectively by address space ownership -- effectively, "proof of stake." Any arbitrary power, will tend to fracture along these property lines. For instance, our hot updates are sent through the galaxy hierarchy; in a development fork, active galaxies would pick sides. This would actually be awesome for Urbit.
53+
54+By fragmenting the galaxy space into 57 separate partitions, 've created a global property map which is much more likely to splinter further, than reunite.
55+
56+In the long run, every galaxy should have a separate owner, who is a human being rather than a corporation. Combining galaxy holdings is regarded as creepy, and damages the value of both galaxies. Splitting up any remaining clumps is meritorious.
57+
58+The technical goal of Urbit is to create a network which, *if it actually takes over the world*, inevitably becomes decentralized. Even if Urbit takes over the world, nobody takes over the world. World domination must be technically implausible.
59+
60+This is the goal of all the new "web3" decentralized systems. If IPFS, Sandstorm or Ethereum takes over the world, nobody takes over the world. (The same is almost true of the Internet -- though it wouldn't be that surprising if a time traveler from 2116 revealed that ICANN had become a planetary government.)
61+
62+Urbit, by starting out as a centralized network, just reduces the technical problem to match the actual goal. Only long-term decentralization matters.
63+
64+It's very important that Urbit in 2116 be fully decentralized. For Urbit in 2016, pretending to be decentralized would be a joke at best, and a hoax at worst. And of course, no one can DAO us -- since the property system is still just a central registry.
65+
66+## {Sandstorm, IPFS, Ethereum, ...} is way ahead of Urbit.
67+
68+In general, web3 (next distributed web) solutions don't compete with each other. They support each other. Concretely, they are all part of each others' network effect.
69+
70+IPFS, Sandstorm, Ethereum, ZeroTier, and Urbit can all take over the world at the same time. None of them competes with the others. They enable each other. For instance, IPFS is not a computer; Urbit will be a great computer to use IPFS from; IPFS is a great CDN for Urbit. Moar IPFS now!
71+
72+The closest thing to a competitor that Urbit has is Sandstorm. Sandstorm, which by the way rocks, is also a personal server.
73+
74+But Sandstorm and Urbit compete in the way that, on the PC, the OS and the browser compete. In theory, the OS could solve the problems that the browser solves; or the browser could be the OS. In practice, Windows is a great OS to run a browser on.
75+
76+Similarly, a world in which Sandstorm takes off is an awesome world for Urbit, because everyone who has a Sandstorm instance has a great platform for running Urbit on. (Although Sandstorm could still work on its UDP capabilities.)
77+
78+Urbit on Sandstorm will be a sort of "double-hulled" personal server, even safer and more friendly than either system alone. And Sandstorm is not its own P2P network, like Urbit.
79+
80+## Urbit doesn't have enough planets for every human being.
81+
82+A planet is a tool, not a toy. Like a car, it's a device for a responsible and civilized adult. There aren't 4 billion cars in the world, nor 4 billion responsible adults.
83+
84+And limiting the supply of anything doesn't create a shortage. It sets a price. Ideally, in the long run, we think a planet should cost about $10. This could be off by an order of magnitude either way, and it wouldn't be the end of the world.
85+
86+If a planet costs $10, that means you paid $10 to get a planet. A planet with no reputation has a positive reputation, because someone paid $10 for it and hasn't yet done anything wrong. Positive default reputation is the single quality that makes a social network social.
87+
88+There is always a tradeoff between free speech and free beer. Urbit will always choose free speech.
89+
90+## Cloud computing is inherently non-private.
91+
92+TLDR: a general-purpose cloud computer is much, much more private than a special-purpose cloud computer. In general, a VM is secure against corporations but not governments.
93+
94+One reason we want the decentralized Internet is that we're tired of giant corporations spying on us. Think about it this way: Amazon is Netflix's main competitor. And yet, Netflix runs its whole operation on AWS. Why is Netflix sure that Amazon won't spy on it?
95+
96+A general-purpose virtual machine is special from a privacy standpoint, just because it's commercially realistic to design terms of service that prevent the host from peeking and poking at the customer's machine. Crossing this moat is technically nontrivial and can't possibly happen by any reasonable accident. No hosting contract could contemplate it.
97+
98+Whereas when your cloud computer is a special-purpose machine -- just a database row on some corporation's mainframe -- there is no way these services can promise not to handle your data. Handling your data is *what they do*. On a special-purpose server, the concept of privacy is not even defined.
99+
100+Where even a general-purpose server falls down is where the user has a sovereign adversary, which can secretly violate explicit or implicit hosting contracts. Users with a sovereign adversary must rely only on their own physical security. However, most users don't have a sovereign adversary. And those who do maximize their "herd immunity" if they can use the same protocols as those who don't.
101+
102+Also, the portability of a cloud server image is critical. Of course, since Urbit is formally specified, it's trivially portable. In fact, one strategy against sovereign adversaries may be continuous rotation between hosts, like an MX missile.
103+
104+## "Jets" are, like, a total hoax.
105+
106+TLDR: like, all of computing is a hoax. You can't compare a hoax to nothing. You can only compare it to all the other hoaxes.
107+
108+A "jet" is a sort of software device driver in Urbit. Urbit is precisely defined in terms of an interpreter that fits on a T-shirt, Nock. But a naive implementation of Nock is nowhere near practical, because Nock has only one integer operation: increment. For example, to decrement a number in Nock, you increment a counter up to the number under it.
109+
110+The only way an efficient Nock interpreter can work is to recognize algorithms like decrement, and implement them non-naively. By far the easiest way to do this is not to analyze arbitrary code as it's being executed, but to register and match well-known implementations in the standard library. No one should be writing their own decrement.
111+
112+But the semantics of the interpreter, *so long as the jet and the jet harness are defined correctly*, are exactly those of Nock. We are not extending or changing Nock in any way. We are just taking a shortcut in certain cases we understand perfectly.
113+
114+It's not at all unprecedented to have implementations much more complex than the corresponding specification. The x86 instruction set is relatively simple; the complexity of its decoding and execution path in a modern CPU is enormous. This path may well have "peephole optimizations" that replace matched algorithms, and if it doesn't the modern C compiler does.
115+
116+So jets are *morally* defensible. The fact remains, however, that a Nock interpreter without jets is completely useless. And there is not even an informal document that tells you what jets you need for a reasonably efficient Urbit. (This last, we can agree, should be corrected.)
117+
118+The correct way to think about jets is not to compare them to a perfect interpreter implemented by unicorns. Jets are a combined replacement for two other techniques in language implementation: intrinsics and a foreign-function interface.
119+
120+Compared to both intrinsics and an FFI, your jets have one key disadvantage: they need to be specified in pure code. You may not have this executable specification, which means you need to write it. Is this really so bad for your development process? An executable specification? Which can be trivially tested against the efficient implementation?
121+
122+Compared to intrinsics, jets give you true separation between mechanism and policy; only the interpreter, not the programmer and not the compiler, needs to know what's accelerated.
123+
124+Compared to an FFI, jets preclude I/O, so can be trivially sandboxed. Except that the programmer needs to mark routines which may benefit from optimization with a hint, here too we separate mechanism (efficient implementation) from policy.
125+
126+Yes, formal verification of jet equivalence is desirable. However, in the real world, many specifications, including quite complex ones, are tested into equivalence by brute force.
127+
128+Urbit has some jet abuses. The equivalence between our markdown parser in Hoon and the CommonMark C library is super dubious. It should be taken out and shot.
129+
130+However, the miscomputation resulting from a minor jet discrepancy is not a security hole or even fatal. It effectively means the event history does not match the current state. The way to resolve this conflict is for the current state to win, and the event history to be discarded -- not abnormal anyway. See the next question.
131+
132+## Urbit needs an infinitely extending packet/event log.
133+
134+TLDR: no, it doesn't.
135+
136+We can prune the event log because the Urbit transition function doesn't have any access to the event history -- just the current state and the current event.
137+
138+Urbit defines the semantics of a complete event log. It doesn't and can't require an implementation to maintain the whole log. It can maintain a checkpoint and the log since that checkpoint. The current implementation of Urbit maintains
139+
140+However, any practical urbit maintains a periodically updated checkpoint. Our present implementation doesn't provide a way to prune the event log, but that's just a missing feature.
141+
142+## Urbit will never be able to call any existing code.
143+
144+TLDR: neither will Javascript. And dear Unix, the browser does not miss interacting with your `$LD_LIBRARY_PATH` at all.
145+
146+You can't talk to the OS or use system libraries from Javascript. Therefore, there is no point in having any kind of gateway, compatibility bridge, native methods, or other interface between Javascript and C.
147+
148+When in doubt, remember that Urbit is "the browser for the server side." It plays by the same general rules. Isolation means isolation.
149+
150+## There's no way Urbit will ever be adopted. It's too weird.
151+
152+TLDR: Urbit adoption is designed to be driven by ordinary end users. Urbit isn't ready for ordinary end users yet. We're working on it -- come help.
153+
154+Right now, Urbit is a developer tool. Or rather, a developer toy -- since the only thing it's useful for is developing Urbit. It also could be a much better toy. We're working on that too.
155+
156+But it's absolutely wrong to think of Urbit being adopted as a developer tool in the conventional sense. If you think this is almost impossible, you're right.
157+
158+If we look at the way most successful platforms are adopted, they're not adopted for their own virtues. They're adopted because they're part of a larger solution. It's very hard to displace a native component of an existing platform. Urbit is not trying to do this.
159+
160+C is a better language than Pascal, but it didn't beat Pascal because it's a better language. C beat Pascal because C was the native language of Unix, and people wanted to program in Unix. People don't use Javascript because Javascript is a great language, but because it's the native language of the browser. Replacing the native language of a platform may be doable -- but it's incredibly hard.
161+
162+Hoon is not competing with C, or even Haskell, as a Unix programming language. The only reason to program in Hoon is that it's the native language of Urbit. Urbit is not competing with node.js or Rails as a Web backend. The only reason to run Urbit is to
163+
164+Nock is cool, but it only gets adopted if Hoon gets adopted. Hoon is cool, but it only gets adopted if Urbit gets adopted. Urbit only gets adopted if it's useful as a personal server for human beings -- most of whom won't be Hoon programmers, or programmers at all.
165+
166+## Hoon is too weird. No one will be able to program in it.
167+
168+TLDR: Hoon is ridiculously simple. Our documentation and tooling are just immature.
169+
170+It's pretty fair to assume that (a) functional programming is hard and weird, (b) Hoon is weird even for a functional language, so (c) Hoon must be hard-squared.
171+
172+Actually, Hoon is weird even for a functional language because it's an attempt to remove the hardest things about functional programming: category theory, lazy evaluation, and gratuitous abstraction. To know a language is to know what the compiler is doing; all the semantics of the Hoon compiler fit in 2000 lines of code.
173+
174+It's too easy for us to wind up living in Isaac Asimov's Trantor, a world in which everything got invented thousands of years ago and the idea of new technology is just weird and scary. History isn't over yet, and nor is technical history.
175+
176+New things are harder to learn than old things. We ask smart high-school students to learn calculus. Think about how much harder it was for Newton and Leibniz to invent calculus, or for their first students to pick it up.
177+
178+Most of the difference is just the collective certainty that our society conveys to a high-school student that calculus is learnable. When you're learning Urbit, you don't have this collective knowledge; so you don't have the confidence that the problem is solvable. Confidence makes a huge difference. Moreover, any bug or glitch in the developer experience destroys this confidence and takes a long time to heal.
179+
180+Yes, we know: Hoon remains quite hard to learn. Again, we have no reason to think this problem isn't solvable. Public enlightenment remains our main priority.
181+
182+## Urbit programmers are stuck with Hoon.
183+
184+TLDR: patience, grasshopper.
185+
186+There's quite a straightforward way to implement any perfectly specified language with a reliable interpreter in Hoon. First, write an interpreter for that language in Hoon. Second, jet that intepreter function with the existing implementation.
187+
188+It is not clear that Javascript is *quite* well-defined enough for this treatment. But Lua probably is.
189+
190+## Ordinary users will never be able to manage an Urbit server.
191+
192+TLDR: Urbit's technical simplicity has always been designed to drive human usability. But the polish is the last thing that goes on. So we can't evaluate this claim right now.
193+
194+Right now, Urbit is only for geeks. You already need to be able to wrangle a Unix machine to run it. What's the point?
195+
196+This Urbit isn't the real Urbit. It's an early milestone on the way to the real Urbit.
197+
198+The real Urbit -- for normal human beings -- is a hosted service. Getting a planet is as easy as signing up for Facebook. Probably many users will think of it as another web account. They might not even know it can run more apps than the ones they use.
199+
200+A deterministic, persistent cloud computer is something different from a traditional server. Normally when we think of a server in the cloud, we think of it like a live animal -- a creature that needs to be cared for, fed, and herded. A file in the cloud is more like a rock -- you can forget about it for ten years.
201+
202+An urbit is a general-purpose computer, but it doesn't even have the concept of a reboot. It upgrades itself. If you don't feed it any packets for ten years, then turn it back on, it will spend a day or two upgrading itself, then be back to normal. Maybe it's something in between a rock and an animal -- a cactus?
203+
204+Another huge difference versus an Internet server is that we're confident that Urbit's limited supply of identities will make it easy to keep abusers off the network. So far, so good -- but of course, no one abuses a young network.
205+
206+The bottom line is that managing your urbit has to be as easy as managing your iPhone. Normally, it consists of deciding what apps you want to be running, and how much you trust them. Resources can't be free, so sometimes you have to play memory police. Humans have shown that they can handle these tasks.
207+
208+Our '70s OSes and networks, which were great designs in their day and have matured into excellent industrial tools, give us a totally misleading impression of how hard it should be to manage a general-purpose computer. Computing isn't scary or dangerous. Unix and the Internet are scary and dangerous. That's fine for an industrial tool, but not a personal tool.
209+
210+## Urbit has no killer app.
211+
212+TLDR: the killer app is personal API aggregation.
213+
214+It's a truism that any new platform has to be fundamentally much better at solving some problem than the mature platform it seeks to replace.
215+
216+We can look at Urbit's killer app from two perspectives: as a developer, and as a user.
217+
218+From the developer's perspective, Urbit's advantage is that it's a network stack which provides exactly-once delivery of typed, validated, transactional, encrypted and authenticated messages. The difference between an Urbit API and a REST API is like the difference between a paved road and a dirt road. On the other hand, you do need to learn a new functional language.
219+
220+From the user's perspective, there's one task that any personal server can perform, that can't be performed by any Web service: unrestricted API aggregation.
221+
222+Well before Urbit is ready to *replace* any conventional web services, it should be ready to *command* them in place by API. (Or if needed, by scraping.) If all you care about is being in control of your own data, it's fine to leave it in the hands of these services, as you have the API secrets to get it out.
223+
224+Managing a set of security connections to your existing services is one of the first important tasks of a modern personal server. This is a stateful task that typically requires both a durable API key and a temporary OAuth token. APIs change all the time, so connection maintenance also requires evergreen updates.
225+
226+The origin of this API key will vary, but usually the best way to set it is BYOK: the user registers their own urbit as an "app." And the neat thing about having your own API keys, for multiple services, on a single general-purpose computer, is that none of these services really has any practical way to control what you do with your own data.
227+
228+Terms of service which constrain the use of data (as opposed to the abuse of the service) simply aren't realistic and will no longer apply. This enables a variety of novel user experiences which aren't implementable as traditional web services, and also aren't available via conventional third-party API aggregators.
229+
230+Also, since Urbit is after all quite immature, it doesn't make much sense to restrict this security state to code within Urbit. The Urbit interpreter `vere` runs as a Unix daemon that implements the FUSE user-level filesystem protocol, and maps the data on your services into the Unix filesystem. For example, one of our demos lets you `ls` your Github issues.
231+
232+So it's straightforward to build, for instance, a Python app that uses Urbit as a gateway to mash up a bunch of web services. As a Unix programmer, you might even just regard Urbit as a generic Web API gateway daemon, without worrying about its internals.
233+
234+We have other ideas for initial killer apps. But this, we feel, is the best one. API libraries for `npm` et al abound. Stateful, self-updating, generic API aggregators with FUSE integration, also integrated with a reactive web server, are more rare. So perhaps there's a small niche here.
235+
236+## Urbit is sneered at by brilliant talking horses.
237+
238+It's difficult to categorize this [brilliant essay of Fare's] in a single bullet point. So I've saved it for last.
239+
240+We've already addressed the point most commonly made by others: that jets are a sham. It's not always trivial to decode this critique, which is quite abstract. But Fare' makes a few other points.
241+
242+### Event-sourcing and/or caching is a pattern, not a layer
243+
244+Fare' is perfectly right that "one size does not fit all" in persistence. Generally, Urbit uses event-sourced persistence.
245+
246+But it has multiple layers of event-sourcing: in the definition of Urbit itself; in the application sandbox vane (Gall), and in the application itself. Urbit also has a completely orthogonal revision control system (Clay).
247+
248+And there is not a single cache across the whole system, though arguably there should be; for instance, the functional build system (Ford, which Fare' the master of build systems might appreciate) has its own internal cache.
249+
250+It is a common mistake to confuse a design pattern with a layer or feature, and equally fatal whichever direction you fail.
251+
252+### Let's be clear about why DSLs suck
253+
254+DSLs suck not because they are difficult to newbies in the base language. DSLs suck because every time a programmer, even one *experienced* in the base language, comes into a new codebase or project, she has to learn a new custom language.
255+
256+You need enormous wins to justify this cost. It's the goal of the base language designer to preempt these wins, creating a language which is almost never so tiresome and full of boilerplate that it requires a DSL or template layer.
257+
258+Hoon is almost entirely made of macros -- but they are internal, fixed, built-in macros (with no gensyms). This fixed set of macros is essentially enough. Occasionally we want to add one or two. But we never, ever pine for context-dependent macros.
259+
260+### Determinism is not consensus, and is not constraining
261+
262+Fare' is totally right that an urbit's data is meant for itself alone. In fact, an urbit has the right to compute incorrectly if it wants. We go to considerable lengths to ensure that you can't gain any particular advantage by incorrect computing.
263+
264+The whole point of Nock is that it's so low-level that there is no conceivable advantage in upgrading it. Divergence is just pointless. This is not a question of network integrity, just of practical standardization.
265+
266+This consistency stops at Nock. Without anyone violating the correctness of their lifecycle functions, anyone or everyone in Urbit could replace Hoon with Javascript. Determinism does not cramp Urbit's semantic style in any way, shape or form.
docs/arvo.md+4−4
@@ -1,12 +1,12 @@
11---
22navhome: /docs
3−sort: 3
3+sort: 4
44---
55
6−# Arvo programming
6+# Quickstart
77
8−This example-based sequence of tutorials shows you how to build simple programs in hoon and use the basic features of Arvo.
8+Fast, pragmatic tutorials which show you how to build simple programs in Hoon and Arvo.
99
10−If you like to learn by example, start here.
10+If you learn by getting things done, not by exploring fundamentals, start here.
1111
1212<list/>
docs/byte.mdnew file+11
@@ -0,0 +1,11 @@
1+---
2+navhome: /docs
3+sort: 3
4+---
5+
6+# Urbytes
7+
8+Learn Hoon in short, self-contained, bottom-up tutorials.
9+A work in progress. Still ideal for the complete newbie.
10+
11+<list/>
docs/byte/0.mdnew file+273
@@ -0,0 +1,273 @@
1+---
2+navhome: /docs
3+sort: 1
4+next: true
5+title: Setup and nouns
6+---
7+
8+# Urbyte 0: setup and nouns
9+
10+This is the first post in our new Urbyte series.
11+
12+The Urbyte concept is that you, an ordinary programmer, not a
13+kernel hacker or a Haskell magician (not that there's anything
14+wrong with kernel hackers or Haskell magicians) can learn Hoon,
15+Urbit's programming language.
16+
17+We're going to test this daring idea by teaching you Hoon, in
18+easily digestible, byte-size chunks. Each post in the "Urbytes"
19+series is designed to take about 15 minutes to consume. (Maybe
20+10, if you're a kernel hacker or a Haskell magician.)
21+
22+We'll assume no knowledge of Urbit except for previous lessons.
23+Ideally you have some basic familiarity with programming and can
24+operate the Unix command line.
25+
26+We strongly encourage you to type in all the examples in each
27+Urbyte. Urbytes are short, but not meant to be skimmed.
28+
29+## Install
30+
31+First, [install Urbit](http://urbit.org/docs/using/install/) on any
32+Mac or Unix machine. On Windows, make a virtual Linux machine
33+using VirtualBox or a similar tool.
34+
35+While you're downloading, read about Urbit ships:
36+
37+## Ships
38+
39+In the Urbyte exercises you'll be running what we call a "fake
40+`~zod`." A string starting with `~`, like `~zod`, is what Urbit
41+calls a *ship*.
42+
43+A ship is one number which means four things: a network address, a
44+cryptographic identity, a memorable name, and a single virtual computer.
45+We write this number in a base-256 format, where each digit is a
46+syllable. Imagine if your phone number was a pronounceable
47+string which sounded like a name in a foreign language.
48+
49+`~zod` is ship zero, making it a very important ship indeed.
50+Your "fakezod" thinks it's `~zod`, but no one can talk to it.
51+(An ordinary user-level ship is a 32-bit number which becomes
52+a four-syllable string, like `~talsur-todres`.)
53+
54+A fakezod is not the true Urbit experience, of course. But it's
55+ideal if all you want to do is play around with Hoon. If you
56+have a real urbit ship, of course you can use that instead.
57+
58+## Create and restart
59+
60+To create your fakezod, run:
61+
62+```
63+$ urbit -FI ~zod -c myship
64+```
65+
66+This will take about 30 seconds and spin out a bunch of boot
67+messages. At the end, you'll see:
68+
69+```
70+ames: on localhost, UDP 31337.
71+http: live (insecure, public) on 8080
72+http: live ("secure", public) on 8443
73+http: live (insecure, loopback) on 12321
74+~zod:dojo>
75+```
76+
77+To make sure everything is working, type `(add 2 2)` at the
78+prompt, then hit return. Your screen now shows:
79+
80+```
81+ames: on localhost, UDP 31337.
82+http: live (insecure, public) on 8080
83+http: live ("secure", public) on 8443
84+http: live (insecure, loopback) on 12321
85+> (add 2 2)
86+4
87+~zod:dojo>
88+```
89+
90+That's super awesome! You made your first noun! We'll make a
91+few more in a second. First, quit Urbit with `^D`:
92+
93+```
94+> (add 2 2)
95+4
96+~zod:dojo>
97+$
98+```
99+
100+You now have an Urbit image, or *pier*, in the `myship` directory.
101+Right now the only thing in your pier is Urbit's system files:
102+
103+```
104+$ ls -a myship
105+./ ../ .urb/
106+```
107+
108+Restarting uses almost the same command, but without `-c` (which
109+means "create"). There are also fewer startup messages:
110+
111+```
112+$ urbit -FI ~zod myship
113+[...]
114+ames: on localhost, UDP 31337.
115+http: live (insecure, public) on 8080
116+http: live ("secure", public) on 8443
117+http: live (insecure, loopback) on 12321
118+~zod:dojo>
119+```
120+
121+Note also that Urbit is an ACID database. You can stop it
122+politely with `^D`, abruptly with `^Z`, even violently with `kill
123+-9`. None of these should cause Urbit to lose data. If you do
124+manage to corrupt a pier, it's a bug; please let us know.
125+
126+## Let's make a noun
127+
128+We already made a noun. Let's make another. (We won't show the
129+`~zod:dojo> ` prompt in future, just the echoed command.)
130+
131+```
132+~zod:dojo> 42
133+```
134+
135+You'll see:
136+
137+```
138+> 42
139+42
140+~zod:dojo>
141+```
142+
143+## Understanding nouns
144+
145+A value in Urbit is called a *noun*. A noun is either an *atom*
146+(an unsigned integer of any size) or a *cell* (an ordered pair of
147+any two nouns).
148+
149+In a sentence, a noun is a binary tree whose leaves are numbers.
150+If you know Lisp, a noun is a minimalist S-expression. A noun
151+can't have cycles (pointer loops). An implementation can use
152+dags (shared subtrees), but the programmer can't detect them
153+(there's no pointer equality test).
154+
155+The absence of graph cycles makes nouns much easier to save in
156+persistent storage, send over the network, manage memory for
157+(Urbit has no tracing garbage collector), etc.
158+
159+## Let's make some atoms
160+
161+So one kind of atom is a number. And the syntax (or at least one
162+syntax) for a number is a decimal, like `42`. Seems legit.
163+
164+But just to be sure we understand this decimal thing, let's make
165+some atoms:
166+
167+```
168+> 4
169+4
170+```
171+
172+Seems pretty straightforward.
173+
174+```
175+> 42
176+42
177+```
178+
179+Why not try it again to make sure?
180+
181+```
182+> 420
183+420
184+```
185+
186+Can we add another zero?
187+
188+```
189+~zod:dojo> 420
190+```
191+
192+Wat? When you tried to type that next zero and turn `420` into
193+`4200`, Urbit actually *deleted the `0` and beeped at you.*
194+
195+But isn't an atom an unsigned integer of any size? It is.
196+But the syntax is actually `4.200`:
197+
198+```
199+> 4.200
200+4.200
201+> (mul 42 100)
202+4.200
203+```
204+
205+Just think of it as "4,200", written the German way with a dot.
206+
207+Why? Long decimals are unreadable. Human beings know this, so
208+we group them in threes. For some historical reason, programming
209+languages never copied this marvelous usability innovation.
210+
211+English notation for decimals is more common than German
212+notation. Unfortunately, dot is URL-safe and comma isn't, and
213+it's nice to have a regular syntax for atoms that's URL-safe.
214+
215+As for why Urbit deleted your zero: it parses your command line
216+as you type, and rejects any characters after the parser stops.
217+
218+## Let's make some cells
219+
220+There's not much mystery about cells. A cell has a head and a
221+tail, and puts brackets around them:
222+
223+```
224+> [42 420]
225+[42 420]
226+```
227+
228+`42` is the *head* and `420` is the *tail* of the cell. Cell
229+syntax nests to the right:
230+
231+```
232+> [4 [42 420]]
233+[4 42 420]
234+
235+> [4 42 420]
236+[4 42 420]
237+
238+> [[4 42] 420]
239+[[4 42] 420]
240+```
241+
242+If you look at these nouns as binary trees, you see
243+
244+```
245+ [4 [42 420]] [[4 42] 420]
246+ . .
247+ / \ / \
248+ 4 . . 420
249+ / \ / \
250+ 42 420 4 42
251+```
252+
253+Each number is an atom; each dot is a cell.
254+
255+## And we're done
256+
257+And we're done! Press `^D` to exit:
258+
259+```
260+~zod:dojo> ^D
261+$
262+```
263+
264+## Questions and/or exercises
265+
266+And we're done with our very first Urbyte! Here's a question to
267+think about. These exercises are never mandatory, but they may
268+be fun and/or interesting. Skip them if they're obvious.
269+
270+The question today is: what is the right way to represent common
271+data structures as nouns? A linked list? A string? A *signed*
272+integer? A table or associative array? Just try to picture
273+these structures in your head, or draw them on a piece of paper.
docs/byte/1.mdnew file+349
@@ -0,0 +1,349 @@
1+---
2+navhome: /docs
3+sort: 2
4+next: true
5+title: Atoms, auras, types
6+---
7+
8+# Urbyte 1: atoms, auras, types
9+
10+Thanks for reading Urbyte 0! In Urbyte 1, we'll look a little
11+more deeply at atoms and other simple noun types.
12+
13+Let's restart our engines:
14+
15+```
16+$ urbit -FI ~zod myship
17+[...]
18+ames: on localhost, UDP 31337.
19+http: live (insecure, public) on 8080
20+http: live ("secure", public) on 8443
21+http: live (insecure, loopback) on 12321
22+~zod:dojo>
23+```
24+
25+## The atom question
26+
27+It seems limiting to have only one kind of atom, the unsigned
28+decimal. How are signed integers represented? Symbols?
29+Floating-point values? Dates? IP addresses? Even just hex?
30+
31+The Lisp S-expression, with cons cells and atoms, is very similar
32+to Hoon's nouns. But languages in the Lisp family mark each atom
33+with a dynamic tag that defines the atom's meaning. These tags
34+are effectively dynamic types.
35+
36+Hoon also tracks the meaning of atoms. But Hoon is statically
37+typed, so an atom description is obviously a type. An atomic type
38+in Hoon is called an *aura*. The aura syntax is just an ASCII
39+string starting with `@`, like `@ud` for unsigned decimal.
40+
41+## Examples
42+
43+With the dojo command `? expression`, you tell the dojo to print
44+both the product of the expression, and the product's type.
45+
46+Let's type in some aura examples:
47+
48+### Unsigned integers
49+
50+```
51+> 42
52+42
53+
54+> ? 42
55+ @ud
56+42
57+
58+> ? 0x42
59+ @ux
60+0x42
61+
62+> ? (add 0x42 42)
63+ @
64+108
65+
66+> ? `@ud`0x42
67+ @ud
68+66
69+
70+```
71+
72+So decimal is aura `@ud`, hexadecimal is `@ux`. Note the cast
73+syntax, which lets us change the type of an atom, converting hex
74+`0x42` to a decimal `66`.
75+
76+An aura is soft type. The programmer can always insist on how
77+to interpret an atom. Hoon doesn't have "dependent types"; it
78+can't enforce any constraints the aura puts on the atom's value.
79+
80+### Signed integers
81+
82+```
83+> -7
84+-7
85+
86+> ? -7
87+ @sd
88+
89+> --7
90+--7
91+
92+> ? --7
93+ @sd
94+--7
95+
96+> ? (sum:si -7 --7)
97+ @s
98+--0
99+
100+> `@ud`-7
101+13
102+
103+> `@ud`--7
104+14
105+```
106+
107+`--7` means "positive 7." `+7` might have been better, but `+`
108+is not URL-safe, and every regular atom syntax fits in a URL.
109+
110+Hoon needs `--` to distinguish positive signed numbers because
111+Hoon's type system doesn't feed back into its parser. The
112+expression itself needs to control whether it's `@sd` or `@ud`.
113+
114+With unlimited atom width, traditional sign extension makes no
115+sense. The sign bit is the low bit. Even atoms are positive,
116+odd atoms are negative.
117+
118+And Hoon has no overloading or type detection; we need to use a
119+different function to add signed integers. We'll always choose
120+slightly clunkier syntax in exchange for much simpler semantics.
121+
122+### Symbols
123+
124+```
125+> ? 'Ürbit'
126+ @t
127+'Ürbit'
128+
129+> ? `@ux`'Ürbit'
130+ @ux
131+0x7469.6272.9cc3
132+
133+> ? `@ux`'foo'
134+ @ux
135+0x6f.6f66
136+```
137+
138+The `@t` aura is UTF-8 text, with the first byte low. Again,
139+Hoon doesn't actually have the power to check statically that
140+your UTF-8 is valid. Auras don't tell you what an atom is, just
141+what you think it is.
142+
143+### Dates, floats, IP addresses...
144+
145+```
146+> ? now
147+ @da
148+~2016.7.11..01.32.04..2c0d
149+
150+> ? @~h6
151+ @dr
152+~h6
153+
154+> `@ux`~h6
155+ @ux
156+0x5460.0000.0000.0000.0000
157+
158+> ? (add ~h6 now)
159+ @
160+170.141.184.502.236.089.414.812.327.632.537.911.296
161+
162+> `@da`(add ~h6 now)
163+~2016.7.11..07.32.28..842f
164+
165+> ? .3.14
166+ @rs
167+.3.14
168+
169+> ? .127.0.0.1
170+ @if
171+.127.0.0.1
172+```
173+
174+`@da` is a 128-bit absolute date (64 bits for fractions of a
175+second, 64 bits for seconds); `@dr` is a relative date; `@rs` is
176+a single-precision IEEE real; `@if` is an IPv4 address. This is
177+not all Hoon's aura syntax, but it's a good range of examples.
178+
179+`(add ~h6 now)` is a good example of the use and limits of
180+the aura system. Unlike the signed-integer sum, offsetting a
181+date can use plain atomic addition. But the product of `add` is
182+a flavorless atom with no aura, so we have to cast it back to an
183+absolute date `@da`.
184+
185+## Auras explained
186+
187+Does an aura represent the units of the atom, its syntax, its
188+semantics, its constraints?
189+
190+It can mean any or all of these. Programmers can even use their
191+own aura strings which nothing in Hoon recognizes. The set of
192+syntaxes that Hoon knows how to parse and print is fixed. But
193+there are plenty of reasons to introduce user-defined auras.
194+
195+If your program uses both fortnights and furlongs, the aura
196+system will not parse a fortnight syntax or print furlongs in the
197+dojo. It will keep you from accidentally confusing the two,
198+which is probably most of what you want.
199+
200+Hoon does interpret the string in one way: auras specialize to
201+the right. For example, `@u` is any unsigned integer; `@ux` is
202+an unsigned integer that likes to be printed as hex.
203+
204+Hoon's typechecker lets you go up or down the specialization
205+ladder, but complains if you try to go across. For example,
206+`@u` can silently convert into `@ux` or `@ux` into `@u`, but
207+turning `@ud` into `@ux`, `@ux` into `@da`, etc, requires an
208+explicit cast.
209+
210+## Constants, symbols, loobeans and null
211+
212+An atom type isn't just an aura. There's another choice: the
213+type can be *general* and contain all atoms (like the types we've
214+seen above), or *constant* and contain just one atom.
215+
216+A type describes a set of values. While auras may informally
217+describe a format for which not all atoms are valid, any atom can
218+be cast into the aura whether valid or invalid. But in a
219+constant, the type contains just one atom.
220+
221+The regular syntax for an atomic constant is just to put `%` on
222+front of the constant. Like:
223+
224+```
225+> ? 42
226+ @ud
227+42
228+
229+> ? %42
230+ $42
231+42
232+
233+> ? %~h6
234+ $~h6
235+~h6
236+```
237+
238+The `$` on the type indicates the constant. Note that constants
239+still have auras; `~h6` (6 hours) is still a `@dr`.
240+
241+## Common irregulars
242+
243+There are a few special forms worth learning early: symbols,
244+null, loobeans, and of course ships:
245+
246+```
247+> ? %foo
248+ $foo
249+%foo
250+
251+> `@ux`%foo
252+0x6f.6f66
253+
254+> .n
255+.n
256+
257+> |
258+.n
259+
260+> .y
261+.y
262+
263+> &
264+.y
265+
266+> `@ud`&
267+0
268+
269+> ~
270+~
271+
272+> `@ud`~
273+0
274+
275+> ? ~zod
276+ ~zod
277+@p
278+
279+> `@ux`~forseg-bolbyn
280+0x885e.8af9
281+```
282+
283+`%symbol` is a constant with aura `@tas` (text, ASCII, symbol).
284+The symbol rules, which are enforced by the Hoon parser but not
285+(as we've discussed) the type system: a symbol is lowercase with
286+infix hyphens ("kebab-case").
287+
288+Loobeans are not true and false, but yes (`.y` or `&`) and no
289+(`.n` or `|`). This is because *yes is zero and no is one*.
290+This makes sense at a certain mathematical level, though it
291+was probably a mistake.
292+
293+`~` is Hoon's nil: constant `0`, aura `@n`.
294+
295+And of course, `@p` is the phonemic base used for ship names.
296+(It's useful for any kind of memorable number.)
297+
298+## Cells and types
299+
300+Naturally, all these atoms fit neatly into cells, and retain
301+their types within the cells.
302+
303+```
304+> ? [~h6 [.3.14 %foo] 0xdead.beef]
305+ {@dr {@rs $foo} @ux}
306+[~h6 [.3.14 %foo] 0xdead.beef]
307+
308+> `*`[~h6 [.3.14 %foo] 0xdead.beef]
309+[398.449.671.992.126.314.905.600 [1.078.523.331 7.303.014] 3.735.928.559]
310+```
311+
312+Another fun trick is to cast any noun to the `*` type, ie,
313+generic noun. We then know nothing about the noun, so we print
314+all its atoms as decimals.
315+
316+## And we're done
317+
318+And we're done! Press `^D` to exit:
319+
320+```
321+~zod:dojo> ^D
322+$
323+```
324+
325+## Questions and/or exercises
326+
327+As always, these questions are optional and only for fun.
328+
329+We didn't include anywhere near all auras or syntaxes in this
330+lesson. It's just a set of examples.
331+
332+Try using the dojo's magic error erasure to stumble around the
333+rest of Hoon's atom syntax. Any string that can't be extended
334+into a valid expression will be trimmed back, with a beep, until
335+it can. Return will beep if the expression is not complete.
336+This feedback is harmless and does not use an electric shock,
337+but it enables stochastic reinforcement learning of Hoon syntax.
338+
339+If `~h6` is six hours, how do you write forty-five minutes? Two
340+days, six hours and forty-five minutes?
341+
342+What would you expect the syntax for double-precision float to
343+be? What about base64?
344+
345+Does an absolute date have to include every zillisecond, or can
346+it be pruned to a day or a year?
347+
348+If there's an IP syntax, what about bitcoin addresses? What
349+other auras do you think should be supported?
docs/byte/2.mdnew file+464
@@ -0,0 +1,464 @@
1+---
2+navhome: /docs
3+sort: 3
4+next: false
5+title: Subject-oriented programming
6+---
7+
8+# Urbyte 2: subject-oriented programming
9+
10+Thanks for reading Urbytes 0 and 1! In Urbyte 2, we'll take
11+nouns for granted and have some real fun with them.
12+
13+Let's restart our engines:
14+
15+```
16+$ urbit -FI ~zod myship
17+[...]
18+ames: on localhost, UDP 31337.
19+http: live (insecure, public) on 8080
20+http: live ("secure", public) on 8443
21+http: live (insecure, loopback) on 12321
22+~zod:dojo>
23+```
24+
25+## Welcome to the dojo
26+
27+Wait, where are we?
28+
29+We're playing in the Urbit `:dojo`. The dojo is sort of like a
30+cross between a Lisp REPL and the Unix shell. (If you know the
31+Unix shell, the Urbit command line has the same history model and
32+Emacs editing commands.)
33+
34+The dojo has its own command language, which is a superset of
35+Hoon. Any Hoon expression is a command. But not all commands
36+are expressions.
37+
38+(The dojo is not the only command-line app on your Urbit. By
39+default there is one other, `:talk`. Since you're on a fakezod,
40+you can only talk to yourself. If you accidentally press `^X`,
41+it will put you into `:talk`; press `^X` again to switch back.)
42+
43+### Dojo variables
44+
45+Like the Unix shell, the dojo has command variables. Type
46+
47+```
48+> =a 42
49+```
50+
51+You've set the dojo variable `a` to the value `42`. The dojo
52+puts this binding in the Hoon subject for expressions to use.
53+So you can write:
54+
55+```
56+> a
57+42
58+
59+> [4 a]
60+[4 42]
61+
62+> ? [4 a]
63+ {@ud @ud}
64+[4 42]
65+```
66+
67+To unbind `a`, just omit the value:
68+
69+```
70+> =a
71+```
72+
73+You removed `a` from the subject. (We can bind it again later, or
74+bind over it without removing it.)
75+
76+```
77+> [4 a]
78+-find.a
79+```
80+
81+Now trying to use `a` is an error.
82+
83+## Subject-oriented programming
84+
85+What is this *subject* thing, anyway? We put `a` in what?
86+
87+Most programming languages have something called a *scope* or an
88+*environment* or a *context*. This is a data structure that
89+contains the variables and functions an expression can use.
90+
91+In a normal language, the environment is not a first-class value.
92+You cannot save an environment in a variable, compute an
93+expression against the environment in the variable, etc, etc.
94+
95+In Hoon or any "subject-oriented" language, an expression is
96+executed against one normal value, the *subject*. In Hoon, of
97+course, the subject is a noun.
98+
99+## First experiments
100+
101+Up to now, we've only built constants. By definition, a constant
102+doesn't use the subject.
103+
104+It would be nice to start with the subject every dojo expression
105+gets. But that subject is pretty complex. Instead, let's make a
106+simple noun from the kinds of atoms we've already learned about:
107+
108+```
109+> =a [42 [%foo .6.28 ~m45] 0xdead.beef]
110+
111+> ? a
112+ {@ud {$foo @rs @dr} @ux}
113+[42 [%foo .3.14 ~m45] 0xdead.beef]
114+
115+> 420:a
116+420
117+```
118+
119+The syntax `expression:expression` uses the product of the second
120+expression as the subject of the first. So we're using `a` as
121+the subject of the expression `420`.
122+
123+Of course, `420` is a constant expression. It doesn't care what
124+the subject is. But:
125+
126+```
127+> (add 2 2):a
128+-find.add
129+```
130+
131+We can't use `a` as the subject of even a simple addition. How
132+could we? There's no `add` function in our `a`. It sometimes
133+takes new Hoon programmers a little while before they realize
134+that there really isn't a scope or environment in Hoon.
135+
136+## Tree geometry
137+
138+So what can we do with this subject? How can we get data out of
139+it? Let's keep working with our little test subject `a`.
140+
141+The most basic way to access the subject is *tree geometry*.
142+Every noun is a binary tree; every noun in the tree has a number
143+which is its address. The root of the tree is `1`; if the
144+address of a cell is `n`, its head is `2n` and its tail is
145+`2n+1`.
146+
147+A picture might help::
148+```
149+ 1
150+ / \
151+ 2 3
152+ / \ / \
153+ 4 5 6 7
154+ / \
155+ 14 15
156+```
157+
158+The syntax for a fragment of the subject at a tree address, or
159+*axis*, is just `+axis`. So:
160+
161+```
162+> +3:a
163+[[%foo .3.14 ~m45] 0xdead.beef]
164+
165+> ? +7:a
166+ @ux
167+0xdead.beef
168+
169+> ? +13:a
170+ {@rs @dr}
171+[.3.14 ~m45]
172+```
173+
174+Of course, the fragment retains the type it had when we built it.
175+
176+## Labeled surfaces
177+
178+We can obviously get anything we want out of the subject by tree
179+geometry. But it's not really how we'd like to program. We'd
180+much rather *label* subtrees with convenient, memorable symbols.
181+
182+For example, suppose our tree looked like:
183+
184+```
185+ 1
186+ / \
187+ x=2 3
188+ / \
189+ y=6 z=7
190+ / \
191+ p=14 15
192+ / \
193+ q=30 r=31
194+```
195+
196+Then instead of writing `+2`, we could write `x`, and so on.
197+
198+Let's replace our test subject `a` with a new noun built around
199+this tree of *labeled surfaces*.
200+
201+```
202+> =a [x=42 y=[p=%foo q=.6.28 r=~m45] z=0xdead.beef]
203+
204+> ? x:a
205+ @ud
206+42
207+
208+> ? y:a
209+ {p/$foo q/@rs r/@dr}
210+[p=%foo q=.6.28 r=~m45]
211+
212+> ? q.y:a
213+ @rs
214+.6.28
215+```
216+
217+Surfaces might remind you of attributes in an object. But again,
218+attributes in an object are a symbol table. There is no symbol
219+table here -- just a tree search.
220+
221+An expression like the label `x` or the axis `+2`, which
222+designates a fragment or feature of the subject, is called a
223+*limb*. Limbs can be connected with a `.`, making a *wing*.
224+
225+To remind you that you're not in Kansas anymore, the syntax for a
226+wing, like `q.y` above, means means "q inside y." In a classic
227+object-oriented system, of course, this would be written `y.q`,
228+that is, attribute `q` within object `y`. In Hoon, `q.y` means
229+"find limb `q`, then find limb `y` inside that."
230+
231+## Surfaces versus fragments
232+
233+Once again, Hoon has no symbol tables. When we put a surface
234+on a noun, the surface label is part of that noun's type. It's
235+not part of the cell or other structure that contains the noun.
236+For example:
237+
238+```
239+> ? x:a
240+ @ud
241+42
242+
243+> ? +2:a
244+ x/@ud
245+x=42
246+
247+? x.+2:a
248+ @ud
249+42
250+```
251+
252+When we take fragment 2 of the labeled subject the *surface
253+comes with it *. `+2` is not `42` but rather `x=42`. We can
254+take the surface off with `x.+2`.
255+
256+## The search algorithm
257+
258+In resolving a label to a fragment axis, we search the subject
259+type in a depth-first traverse.
260+
261+If we find a surface that matches the limb, we succeed. If we
262+find a surface that doesn't match the limb, we fail. If we find
263+a cell, we search first head, then tail.
264+
265+## Skipping
266+
267+What if the same label appears twice in one noun? Let's modify
268+our subject slightly as a test case:
269+
270+```
271+> ? +7:a
272+ z/@ux
273+z=0xdead.beef
274+
275+> =a a(+7 x=z:a)
276+
277+> ? a
278+ {x/@ud y/{p/$foo q/@rs r/@dr} x/@ux}
279+[x=42 y=[p=%foo q=.6.28 r=~m45] x=0xdead.beef]
280+
281+> ? x:a
282+ @ud
283+42
284+
285+> ? ^x:a
286+ @ux
287+0xdead.beef
288+```
289+
290+We don't want to hide any part of the noun from an expression.
291+So the modified limb `^x` *skips* the first match with a surface
292+`x`, getting us to our `0xdead.beef`. This is a unary notation:
293+`^^x` would skip the first two matches.
294+
295+## Editing
296+
297+Above, we mutated our first noun with the flashy `a(+7 x=z:a)`.
298+
299+Of course we are not really "modifying" a noun. Hoon is a pure
300+language. We are making an edited copy. `a(+7 x=z:a)` means "a
301+copy of `a`, with limb `+7` replaced by the product of `x=z:a`."
302+
303+We can edit multiple (disjoint) wings in one expression:
304+
305+```
306+> ? a(+7 [%hello %world], q.y .3.14)
307+ {x/@ud y/{p/$foo q/@rs r/@dr} $hello $world}
308+[x=42 y=[p=%foo q=.3.14 r=~m45] %hello %world]
309+```
310+
311+Notice that nothing stopped us from changing `+7` from
312+`x=0xdead.beef` to `[%hello %world]`. Since the mutated
313+copy is a different noun, it has a different type.
314+
315+(And remember that since `[x y z]` means `[x [y z]]`,
316+`[x y [%hello %world]]` means `[x y %hello %world]`.)
317+
318+## Cores and arms
319+
320+It should be reasonably clear how Hoon's system of fragments and
321+surfaces parallels variables, records or structures in a
322+classical language. But where is Hoon's equivalent of objects:
323+values which bind code to data?
324+
325+The Hoon equivalent of an object is a *core*. As usual in Hoon,
326+the resemblance isn't exact. A core has a set of computed
327+attributes, or *arms*. Each arm is an expression whose subject
328+is the core. There is no argument, so an arm is not a method.
329+
330+Physically, a core is always a cell `[battery payload]`, where
331+the *payload* is any noun, and the *battery* is a tree of
332+formulas in Nock (Hoon's functional assembly language) that
333+implements the arms.
334+
335+As you'd expect with a computed attribute, an expression which
336+uses a label can't know whether the subject will resolve it to a
337+surface fragment (a *leg*) or to an arm.
338+
339+If we're searching a core and the label matches one of the core's
340+arms, we compute the arm against the core. If the label is not
341+found, we search into the payload of the core.
342+
343+## Some core examples
344+
345+When you type these examples, make sure you get the number of
346+spaces exactly right. Hoon syntax is not whitespace-sensitive
347+in general, except that "one space" is always a different token
348+from "two or more spaces."
349+
350+```
351+> ? x:a
352+ @ud
353+42
354+
355+> ? :per a x
356+ @ud
357+42
358+
359+> =b :per a :core ++ foo x ++ bar [q.y foo] --
360+
361+> b
362+<2.spy {x/@ud y/{p/$foo q/@rs r/@dr} x/@ux}>
363+
364+> ? foo:b
365+ @ud
366+42
367+
368+> ? bar:b
369+ {@rs @ud}
370+[.6.28 42]
371+
372+? x:b
373+ @ud
374+42
375+
376+> ? +2:b
377+ *
378+[[0 6] [0 58] 9 4 0 1]
379+```
380+
381+We're seeing some Hoon regular forms for the first time. `x:a`
382+turns out to be an irregular relative of the regular `:per` form.
383+
384+(We'll get more into syntax in a later Urbyte. If some of these
385+examples seem syntactically a little funky, this isn't usually
386+way we'd do them in "real life." We don't normally write cores
387+on one line in the dojo, for instance.)
388+
389+And when we print `b`, or any core, we see that typed noun
390+printing can't be an invertible function in Hoon.
391+
392+We actually can read the battery (with `+2:b` above), but it's
393+just Nock code, not typed data. We don't even print the payload
394+data, though we print the payload type. The `<2.spy>` just shows
395+a core with two arms, for which `spy` is a hash code.
396+
397+## The dojo subject
398+
399+Now that we've made a test subject which is a core, we can look
400+directly at the real dojo subject:
401+
402+```
403+> +1
404+[ [ [ a=[x=42 y=[p=%foo q=.6.28 r=~m45] x=0xdead.beef]
405+ b=<2.spy {x/@ud y/{p/$foo q/@rs r/@dr} x/@ux}>
406+ ]
407+ our=~zod
408+ now=~2016.7.18..08.05.15..0b5c
409+ eny=0vl.hsfrh.tg642.g5o21.1n80b.0h141.0vuan.pm8o4.77ovg.96rk0.n26nn
410+ ]
411+ ~
412+ <283.xzp 42.ajz 407.xtr 110.xht 1.ztu $151>
413+]
414+```
415+
416+We see a bunch of surfaces: our custom `a` and `b`; standard
417+surfaces for identity, date, and entropy; and a ginormous core
418+stack with almost a thousand total arms.
419+
420+To be exact, the syntax `<283.xzp 42.ajz 407.xtr 110.xht 1.ztu
421+$151>` denotes a system of six cores, each of whose payload is
422+another core, until the innermost payload `%151` (the Hoon
423+version). This stack is our standard library, from which comes
424+`add` and other fine functions. (We don't know how to define a
425+Hoon function yet, but we're getting close.)
426+
427+Let's clean up our subject, just to be hygienic:
428+
429+```
430+> =a
431+> =b
432+
433+> +1
434+[ [ our=~zod
435+ now=~2016.7.18..08.10.42..36a0
436+ eny=0vf.8j71j.hlqim.k340u.q0ual.v2cd8.cfa65.vkbte.e733g.ehihg.e8aog
437+ ]
438+ ~
439+ <283.xzp 42.ajz 407.xtr 110.xht 1.ztu $151>
440+]
441+```
442+
443+Again, remember that `=a` is not Hoon syntax, but `:dojo` syntax.
444+How the dojo assembles this subject remains a mystery. But it's
445+not a particularly interesting mystery.
446+
447+## And we're done
448+
449+And we're done! Press `^D` to exit:
450+
451+```
452+~zod:dojo> ^D
453+$
454+```
455+
456+## Questions and/or exercises
457+
458+As always, these questions are optional and only for fun.
459+
460+What's the best way to construct a core which acts as a function?
461+How do you call the function?
462+
463+Why don't any other languages use subject-oriented programming?
464+Which languages are most similar to it?
docs/hoon.md+4−5
@@ -1,12 +1,11 @@
11---
22navhome: /docs
3−sort: 4
3+sort: 5
44---
55
6−# Hoon reference
6+# Hoon
77
8−This in-depth reference covers all the features of Hoon.
9−
10−If you prefer to learn from the bottom up, feel free to start here.
8+An in-depth technical reference for Hoon. Best for readers with
9+an interest or background in programming languages.
1110
1211<list/>
docs/nock.md+1−1
@@ -1,6 +1,6 @@
11---
22navhome: /docs
3−sort: 5
3+sort: 6
44title: Nock
55---
66
docs/using.md+1−3
@@ -5,8 +5,6 @@ sort: 2
55
66# Using
77
8−These short guides will get you installed, setup, and walk you through the basic features of Urbit. Each section has a quickstart at the top that covers the basics.
9−
10−The sections do build on eachother, so it's a good idea to at least skim them in order.
8+These short guides will get you installed, setup, and walk you through the basic features of Urbit.
119
1210<list/>