on master help sign in
Merge remote-tracking branch 'galenwp/urbyte'
b69985bRaymond Pasco
docs.md+2−1
@@ -24,7 +24,8 @@ in Arvo will teach you to build high-level programs and interact with the networ
24Dig into the mechanics of Urbit with [Core Hoon](hoon). Refer back
24Dig into the mechanics of Urbit with [Core Hoon](hoon). Refer back
25there for pure-code exercises and functions in the [standard library](hoon/library).
25there for pure-code exercises and functions in the [standard library](hoon/library).
26
26
27+Anyone obsessed with math, theory, fundamentals of computation,
27−Registered academics are required to start with the [Nock definition](nock/definition) and work upward from there.
28+etc, should start with the [Nock definition](nock/definition) and work upward from there.
28
29
29</div>
30</div>
30
31
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 @@
1---
1---
2navhome: /docs
2navhome: /docs
3−sort: 3
3+sort: 4
4---
4---
5
5
6−# Arvo programming
6+# Quickstart
7
7
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.
9
9
10−If you like to learn by example, start here.
10+If you learn by getting things done, not by exploring fundamentals, start here.
11
11
12<list/>
12<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+275
@@ -0,0 +1,275 @@
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,
44+a cryptographic identity, a memorable name, and a single virtual
45+computer.
46+
47+We write this number in a base-256 format, where each digit is a
48+syllable. Imagine if your phone number was a pronounceable
49+string which sounded like a name in a foreign language.
50+
51+`~zod` is ship zero, making it a very important ship indeed.
52+Your "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
54+a four-syllable string, like `~talsur-todres`.)
55+
56+A fakezod is not the true Urbit experience, of course. But it's
57+ideal if all you want to do is play around with Hoon. If you
58+have a real urbit ship, of course you can use that instead.
59+
60+## Create and restart
61+
62+To create your fakezod, run:
63+
64+```
65+$ urbit -FI ~zod -c myship
66+```
67+
68+This will take about 30 seconds and spin out a bunch of boot
69+messages. At the end, you'll see:
70+
71+```
72+ames: on localhost, UDP 31337.
73+http: live (insecure, public) on 8080
74+http: live ("secure", public) on 8443
75+http: live (insecure, loopback) on 12321
76+~zod:dojo>
77+```
78+
79+To make sure everything is working, type `(add 2 2)` at the
80+prompt, then hit return. Your screen now shows:
81+
82+```
83+ames: on localhost, UDP 31337.
84+http: live (insecure, public) on 8080
85+http: live ("secure", public) on 8443
86+http: live (insecure, loopback) on 12321
87+> (add 2 2)
88+4
89+~zod:dojo>
90+```
91+
92+That's super awesome! You made your first noun! We'll make a
93+few more in a second. First, quit Urbit with `^D`:
94+
95+```
96+> (add 2 2)
97+4
98+~zod:dojo>
99+$
100+```
101+
102+You now have an Urbit image, or *pier*, in the `myship` directory.
103+Right now the only thing in your pier is Urbit's system files:
104+
105+```
106+$ ls -a myship
107+./ ../ .urb/
108+```
109+
110+Restarting uses almost the same command, but without `-c` (which
111+means "create"). There are also fewer startup messages:
112+
113+```
114+$ urbit -FI ~zod myship
115+[...]
116+ames: on localhost, UDP 31337.
117+http: live (insecure, public) on 8080
118+http: live ("secure", public) on 8443
119+http: live (insecure, loopback) on 12321
120+~zod:dojo>
121+```
122+
123+Note also that Urbit is an ACID database. You can stop it
124+politely with `^D`, abruptly with `^Z`, even violently with `kill
125+-9`. None of these should cause Urbit to lose data. If you do
126+manage to corrupt a pier, it's a bug; please let us know.
127+
128+## Let's make a noun
129+
130+We already made a noun. Let's make another. (We won't show the
131+`~zod:dojo> ` prompt in future, just the echoed command.)
132+
133+```
134+~zod:dojo> 42
135+```
136+
137+You'll see:
138+
139+```
140+> 42
141+42
142+~zod:dojo>
143+```
144+
145+## Understanding nouns
146+
147+A 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
149+any two nouns).
150+
151+In a sentence, a noun is a binary tree whose leaves are numbers.
152+If you know Lisp, a noun is a minimalist S-expression. A noun
153+can't have cycles (pointer loops). An implementation can use
154+dags (shared subtrees), but the programmer can't detect them
155+(there's no pointer equality test).
156+
157+The absence of graph cycles makes nouns much easier to save in
158+persistent storage, send over the network, manage memory for
159+(Urbit has no tracing garbage collector), etc.
160+
161+## Let's make some atoms
162+
163+So one kind of atom is a number. And the syntax (or at least one
164+syntax) for a number is a decimal, like `42`. Seems legit.
165+
166+But just to be sure we understand this decimal thing, let's make
167+some atoms:
168+
169+```
170+> 4
171+4
172+```
173+
174+Seems pretty straightforward.
175+
176+```
177+> 42
178+42
179+```
180+
181+Why not try it again to make sure?
182+
183+```
184+> 420
185+420
186+```
187+
188+Can we add another zero?
189+
190+```
191+~zod:dojo> 420
192+```
193+
194+Wat? When you tried to type that next zero and turn `420` into
195+`4200`, Urbit actually *deleted the `0` and beeped at you.*
196+
197+But isn't an atom an unsigned integer of any size? It is.
198+But the syntax is actually `4.200`:
199+
200+```
201+> 4.200
202+4.200
203+> (mul 42 100)
204+4.200
205+```
206+
207+Just think of it as "4,200", written the German way with a dot.
208+
209+Why? Long decimals are unreadable. Human beings know this, so
210+we group them in threes. For some historical reason, programming
211+languages never copied this marvelous usability innovation.
212+
213+English notation for decimals is more common than German
214+notation. Unfortunately, dot is URL-safe and comma isn't, and
215+it's nice to have a regular syntax for atoms that's URL-safe.
216+
217+As for why Urbit deleted your zero: it parses your command line
218+as you type, and rejects any characters after the parser stops.
219+
220+## Let's make some cells
221+
222+There's not much mystery about cells. A cell has a head and a
223+tail, and puts brackets around them:
224+
225+```
226+> [42 420]
227+[42 420]
228+```
229+
230+`42` is the *head* and `420` is the *tail* of the cell. Cell
231+syntax nests to the right:
232+
233+```
234+> [4 [42 420]]
235+[4 42 420]
236+
237+> [4 42 420]
238+[4 42 420]
239+
240+> [[4 42] 420]
241+[[4 42] 420]
242+```
243+
244+If you look at these nouns as binary trees, you see
245+
246+```
247+ [4 [42 420]] [[4 42] 420]
248+ . .
249+ / \ / \
250+ 4 . . 420
251+ / \ / \
252+ 42 420 4 42
253+```
254+
255+Each number is an atom; each dot is a cell.
256+
257+## And we're done
258+
259+And we're done! Press `^D` to exit:
260+
261+```
262+~zod:dojo> ^D
263+$
264+```
265+
266+## Questions and/or exercises
267+
268+And we're done with our very first Urbyte! Here's a question to
269+think about. These exercises are never mandatory, but they may
270+be fun and/or interesting. Skip them if they're obvious.
271+
272+The question today is: what is the right way to represent common
273+data structures as nouns? A linked list? A string? A *signed*
274+integer? A table or associative array? Just try to picture
275+these structures in your head, or draw them on a piece of paper.
docs/byte/1.mdnew file+368
@@ -0,0 +1,368 @@
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+## What's in an atom?
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+Lisp's S-expression, with its own cells and atoms, is very
32+similar to Hoon's nouns. But languages in the Lisp family mark
33+each atom with a dynamic tag that defines the atom's meaning.
34+These tags 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+Hoon has a wide (but not extensible) variety of atom syntaxes.
42+Each syntax for an atom produces an appropriate predefined aura.
43+And Hoon's printer can invertibly print any aura Hoon can parse.
44+Because atoms make great path nodes and paths make great URLs,
45+all regular atom syntaxes use only URL-safe characters.
46+
47+## Examples
48+
49+With the dojo command `? expression`, you tell the dojo to print
50+both the product of the expression, and the product's type.
51+
52+Let's type in some aura examples:
53+
54+### Unsigned integers
55+
56+```
57+> 42
58+42
59+
60+> ? 42
61+ @ud
62+42
63+
64+> ? 0x42
65+ @ux
66+0x42
67+
68+> ? (add 0x42 42)
69+ @
70+108
71+
72+> ? `@ud`0x42
73+ @ud
74+66
75+
76+```
77+
78+So decimal is aura `@ud`, hexadecimal is `@ux`. Note the cast
79+syntax, which lets us change the type of an atom, converting hex
80+`0x42` to a decimal `66`.
81+
82+An aura is soft type. The programmer can always insist on how
83+to interpret an atom. Hoon doesn't have "dependent types"; it
84+can't enforce any constraints the aura puts on the atom's value.
85+
86+### Signed integers
87+
88+```
89+> -7
90+-7
91+
92+> ? -7
93+ @sd
94+
95+> --7
96+--7
97+
98+> ? --7
99+ @sd
100+--7
101+
102+> ? (sum:si -7 --7)
103+ @s
104+--0
105+
106+> `@ud`-7
107+13
108+
109+> `@ud`--7
110+14
111+```
112+
113+`--7` means "positive 7." `+7` might have been better, but `+`
114+is not URL-safe.
115+
116+Hoon needs `--` to distinguish positive signed numbers because
117+Hoon's type system doesn't feed back into its parser. The
118+expression itself needs to control whether it's `@sd` or `@ud`.
119+
120+With unlimited atom width, traditional sign extension makes no
121+sense. The sign bit is the low bit. Even atoms are positive,
122+odd atoms are negative.
123+
124+And Hoon has no overloading or type detection; we need to use a
125+different function to add signed integers. We'll always choose
126+slightly clunkier syntax in exchange for much simpler semantics.
127+
128+### Symbols
129+
130+```
131+> ? 'Ürbit'
132+ @t
133+'Ürbit'
134+
135+> ? `@ux`'Ürbit'
136+ @ux
137+0x7469.6272.9cc3
138+
139+> ? ~~Ürbit
140+ @t
141+'Ürbit'
142+
143+? >~.urbit
144+ @ta
145+~.urbit
146+
147+> ? `@ux`'foo'
148+ @ux
149+0x6f.6f66
150+```
151+
152+The `@t` aura is UTF-8 text, with the first byte low. Again,
153+Hoon doesn't actually have the power to check statically that
154+your UTF-8 is valid. Auras don't tell you what an atom is, just
155+what you think it is.
156+
157+The familiar single-quote syntax for `@t` is an irregular form of
158+the more unusual `~~` prefix. The `~.` prefix, aura `@ta`, is
159+restricted to lowercase ASCII (a great common denominator). Of
160+course, `~` is URL-safe and `'` is not.
161+
162+### Dates, floats, IP addresses...
163+
164+```
165+> ? now
166+ @da
167+~2016.7.11..01.32.04..2c0d
168+
169+> ? @~h6
170+ @dr
171+~h6
172+
173+> `@ux`~h6
174+ @ux
175+0x5460.0000.0000.0000.0000
176+
177+> ? (add ~h6 now)
178+ @
179+170.141.184.502.236.089.414.812.327.632.537.911.296
180+
181+> `@da`(add ~h6 now)
182+~2016.7.11..07.32.28..842f
183+
184+> ? .3.14
185+ @rs
186+.3.14
187+
188+> ? .127.0.0.1
189+ @if
190+.127.0.0.1
191+```
192+
193+`@da` is a 128-bit absolute date (64 bits for fractions of a
194+second, 64 bits for seconds); `@dr` is a relative date; `@rs` is
195+a single-precision IEEE real; `@if` is an IPv4 address. This is
196+not all Hoon's aura syntax, just a good range of examples.
197+
198+`(add ~h6 now)` is a good example of the use and limits of
199+the aura system. Unlike the signed-integer sum, offsetting a
200+date can use plain atomic addition. But the product of `add` is
201+a flavorless atom with no aura, `@`. So we have to cast it back
202+to an absolute date `@da`.
203+
204+## Auras explained
205+
206+Does an aura represent the units of the atom, its syntax, its
207+semantics, its constraints?
208+
209+Any or all of the above. Programmers can even use their own aura
210+strings, which nothing in Hoon recognizes. The set of syntaxes
211+that Hoon knows how to parse and/or print is fixed. But there
212+are plenty of good reasons to use your own user-defined auras.
213+
214+If your program uses both fortnights and furlongs, Hoon will not
215+parse a user-defined fortnight syntax. It will not print furlongs
216+in the dojo. But the type system will keep you from accidentally
217+passing a furlong to a function that expects a fortnight.
218+
219+Hoon does interpret the aura string in one way: auras specialize
220+to the right. For example, `@u` is any unsigned integer; `@ux`
221+is an unsigned integer that likes to be printed as hex.
222+
223+Hoon's typechecker lets you go up or down the specialization
224+ladder. It complains if you try to move across. For example,
225+`@u` can silently convert into `@ux` or `@ux` into `@u`, but
226+turning `@ud` into `@ux`, `@ux` into `@da`, etc, requires an
227+explicit cast.
228+
229+## Constants, symbols, loobeans and null
230+
231+An atom type isn't just an aura. There's another choice: the
232+type can be *general* and contain all atoms (like the types we've
233+seen above), or *constant* and contain just one atom.
234+
235+A type describes a set of values. While auras may informally
236+describe a format for which not all atoms are valid, any atom can
237+be cast into the aura whether valid or invalid. But in a
238+constant, the type contains just one atom.
239+
240+The regular syntax for an atomic constant is just to put `%` on
241+front of the constant. Like:
242+
243+```
244+> ? 42
245+ @ud
246+42
247+
248+> ? %42
249+ $42
250+42
251+
252+> ? %~h6
253+ $~h6
254+~h6
255+```
256+
257+The `$` on the type indicates the constant. Note that constants
258+still have auras; `~h6` (6 hours) is still a `@dr`.
259+
260+## Common irregulars
261+
262+There are a few special forms worth learning early: symbols,
263+null, loobeans, and of course ships:
264+
265+```
266+> ? %foo
267+ $foo
268+%foo
269+
270+> `@ux`%foo
271+0x6f.6f66
272+
273+> .n
274+.n
275+
276+> |
277+.n
278+
279+> .y
280+.y
281+
282+> &
283+.y
284+
285+> `@ud`&
286+0
287+
288+> ~
289+~
290+
291+> `@ud`~
292+0
293+
294+> ? ~zod
295+ ~zod
296+@p
297+
298+> `@ux`~forseg-bolbyn
299+0x885e.8af9
300+```
301+
302+`%symbol` is a constant with aura `@tas` (text, ASCII, symbol).
303+The symbol rules, which are enforced by the Hoon parser but not
304+(as we've discussed) the type system: a symbol is lowercase with
305+infix hyphens ("kebab-case").
306+
307+Loobeans are not true and false, but yes (`.y` or `&`) and no
308+(`.n` or `|`). This is because *yes is zero and no is one*.
309+This makes sense at a certain mathematical level, though it
310+was probably a mistake from a practical perspective.
311+
312+`~` is Hoon's nil: constant `0`, aura `@n`.
313+
314+And of course, `@p` is the phonemic base used for ship names.
315+(It's useful for any kind of memorable number.)
316+
317+## Cells and types
318+
319+Naturally, all these atoms fit neatly into cells, and retain
320+their types within the cells.
321+
322+```
323+> ? [~h6 [.3.14 %foo] 0xdead.beef]
324+ {@dr {@rs $foo} @ux}
325+[~h6 [.3.14 %foo] 0xdead.beef]
326+
327+> `*`[~h6 [.3.14 %foo] 0xdead.beef]
328+[398.449.671.992.126.314.905.600 [1.078.523.331 7.303.014] 3.735.928.559]
329+```
330+
331+Another fun trick is to cast any noun to the `*` type, ie,
332+generic noun. We then know nothing about the noun, so we print
333+all its atoms as decimals.
334+
335+## And we're done
336+
337+And we're done! Press `^D` to exit:
338+
339+```
340+~zod:dojo> ^D
341+$
342+```
343+
344+## Questions and/or exercises
345+
346+As always, these questions are optional and only for fun.
347+
348+We didn't include anywhere near all Hoon's auras or syntaxes in
349+this lesson. It's just a set of examples.
350+
351+Try using the dojo's magic error erasure to stumble around the
352+rest of Hoon's atom syntax. Any string that can't be extended
353+into a valid expression will be trimmed back, with a beep, until
354+it can. Return will beep if the expression is not complete.
355+This feedback is harmless and does not use an electric shock.
356+It enables stochastic reinforcement learning of Hoon syntax.
357+
358+If `~h6` is six hours, how do you write forty-five minutes? Two
359+days, six hours and forty-five minutes?
360+
361+What would you expect the syntax for double-precision float to
362+be? What about base64?
363+
364+Does an absolute date have to include every zillisecond, or can
365+it be pruned to a day or a year?
366+
367+If there's an IP syntax, what about bitcoin addresses? What
368+other auras do you think should be supported?
docs/byte/2.mdnew file+494
@@ -0,0 +1,494 @@
1+---
2+navhome: /docs
3+sort: 3
4+title: Subject-oriented programming
5+---
6+
7+# Urbyte 2: subject-oriented programming
8+
9+Thanks for reading Urbytes 0 and 1! In Urbyte 2, we'll take
10+nouns for granted and have some real fun with them.
11+
12+Let's restart our engines:
13+
14+```
15+$ urbit -FI ~zod myship
16+[...]
17+ames: on localhost, UDP 31337.
18+http: live (insecure, public) on 8080
19+http: live ("secure", public) on 8443
20+http: live (insecure, loopback) on 12321
21+~zod:dojo>
22+```
23+
24+## Welcome to the dojo
25+
26+Wait, where are we?
27+
28+We're playing in the Urbit `:dojo`. The dojo is sort of like a
29+cross between a Lisp REPL and the Unix shell. (If you know the
30+Unix shell, the Urbit command line has the same history model and
31+Emacs editing commands.)
32+
33+The dojo has its own command language, which is a superset of
34+Hoon. Any Hoon expression is a command. But not all commands
35+are expressions.
36+
37+(The dojo is not the only command-line app on your Urbit. By
38+default there is one other, `:talk`. Since you're on a fakezod,
39+you can only talk to yourself. If you accidentally press `^X`,
40+it will put you into `:talk`; press `^X` again to switch back.)
41+
42+### Dojo variables
43+
44+Like the Unix shell, the dojo has command variables. Type
45+
46+```
47+> =a 42
48+```
49+
50+You've set the dojo variable `a` to the value `42`. The dojo
51+puts this binding in the Hoon subject for expressions to use.
52+So you can write:
53+
54+```
55+> a
56+42
57+
58+> [4 a]
59+[4 42]
60+
61+> ? [4 a]
62+ {@ud @ud}
63+[4 42]
64+```
65+
66+To unbind `a`, just omit the value:
67+
68+```
69+> =a
70+```
71+
72+You removed `a` from the subject. (We can bind it again later, or
73+bind over it without removing it.)
74+
75+```
76+> [4 a]
77+-find.a
78+```
79+
80+Now trying to use `a` is an error.
81+
82+## Subject-oriented programming
83+
84+What is this *subject* thing, anyway? We put `a` in what?
85+
86+Most programming languages have something called a *scope* or an
87+*environment* or a *context*. This is a data structure that
88+contains the variables and functions an expression can use.
89+
90+In a normal language, the environment is not a first-class value.
91+You cannot save an environment in a variable, compute an
92+expression against the environment in the variable, etc, etc.
93+
94+In Hoon or any "subject-oriented" language, an expression is
95+executed against one normal value, the *subject*. In Hoon, of
96+course, the subject is a noun.
97+
98+## First experiments
99+
100+Up to now, we've only built constants. By definition, a constant
101+doesn't use the subject.
102+
103+It would be nice to start with the subject every dojo expression
104+gets. But that subject is pretty complex. Instead, let's make a
105+simple noun from the kinds of atoms we've already learned about:
106+
107+```
108+> =a [42 [%foo .6.28 ~m45] 0xdead.beef]
109+
110+> ? a
111+ {@ud {$foo @rs @dr} @ux}
112+[42 [%foo .3.14 ~m45] 0xdead.beef]
113+
114+> 420:a
115+420
116+```
117+
118+The syntax `expression:expression` uses the product of the second
119+expression as the subject of the first. So we're using `a` as
120+the subject of the expression `420`.
121+
122+Of course, `420` is a constant expression. It doesn't care what
123+the subject is. But:
124+
125+```
126+> (add 2 2):a
127+-find.add
128+```
129+
130+We can't use `a` as the subject of even a simple addition. How
131+could we? There's no `add` function in our `a`. It sometimes
132+takes new Hoon programmers a little while before they realize
133+that there really isn't a scope or environment in Hoon.
134+
135+## Tree geometry
136+
137+So what can we do with this subject? How can we get data out of
138+it? Let's keep working with our little test subject `a`.
139+
140+The most basic way to access the subject is *tree geometry*.
141+Every noun is a binary tree; every noun in the tree has a number
142+which is its address. The root of the tree is `1`; if the
143+address of a cell is `n`, its head is `2n` and its tail is
144+`2n+1`.
145+
146+A picture might help::
147+```
148+ 1
149+ / \
150+ 2 3
151+ / \ / \
152+ 4 5 6 7
153+ / \
154+ 14 15
155+```
156+
157+The syntax for a fragment of the subject at a tree address, or
158+*axis*, is just `+axis`. So:
159+
160+```
161+> +3:a
162+[[%foo .3.14 ~m45] 0xdead.beef]
163+
164+> ? +7:a
165+ @ux
166+0xdead.beef
167+
168+> ? +13:a
169+ {@rs @dr}
170+[.3.14 ~m45]
171+```
172+
173+Of course, the fragment retains the type it had when we built it.
174+
175+## Labeled surfaces
176+
177+We can obviously get anything we want out of the subject by tree
178+geometry. But that's not really how we'd like to program. We'd
179+much rather *label* subtrees with convenient, memorable symbols.
180+
181+For example, suppose our tree looked like:
182+
183+```
184+ 1
185+ / \
186+ x=2 3
187+ / \
188+ y=6 z=7
189+ / \
190+ p=14 15
191+ / \
192+ q=30 r=31
193+```
194+
195+Then instead of writing `+2`, we could write `x`, and so on.
196+
197+Let's replace our test subject `a` with a new noun built around
198+this tree of *labeled surfaces*.
199+
200+```
201+> =a [x=42 y=[p=%foo q=.6.28 r=~m45] z=0xdead.beef]
202+
203+> ? x:a
204+ @ud
205+42
206+
207+> ? y:a
208+ {p/$foo q/@rs r/@dr}
209+[p=%foo q=.6.28 r=~m45]
210+
211+> ? q.y:a
212+ @rs
213+.6.28
214+```
215+
216+Surfaces might remind you of attributes in an object. But again,
217+attributes in an object are a symbol table. There is no symbol
218+table here -- just a tree search.
219+
220+An expression like the label `x` or the axis `+2`, which
221+designates a fragment or feature of the subject, is called a
222+*limb*. A list of limbs connected with `.`, is a *wing*.
223+
224+To remind you that you're not in Kansas anymore, the syntax for a
225+wing, like `q.y` above, means means "q inside y." In a classic
226+object-oriented system, of course, this would be written `y.q`,
227+that is, attribute `q` within object `y`. In Hoon, `q.y` means
228+"find limb `q`, then find limb `y` inside that."
229+
230+## Surfaces versus fragments
231+
232+Once again, Hoon has no symbol tables. When we put a surface
233+on a noun, the surface label is part of that noun's type. It's
234+not part of the cell or other structure that contains the noun.
235+This will take a little getting used to:
236+
237+```
238+> ? x:a
239+ @ud
240+42
241+
242+> ? +2:a
243+ x/@ud
244+x=42
245+
246+? x.+2:a
247+ @ud
248+42
249+```
250+
251+When we take fragment 2 of the labeled subject, the *surface
252+comes with it*. `+2` is not `42` but rather `x=42`. We can
253+take the surface off with `x.+2`.
254+
255+## The search algorithm
256+
257+In resolving a label to a fragment axis, we search the subject
258+type in a depth-first traverse.
259+
260+If we find a surface that matches the limb, we succeed. If we
261+find a surface that doesn't match the limb, we fail. If we find
262+a cell, we search first head, then tail.
263+
264+## Skipping
265+
266+What if the same label appears twice in one noun? Let's modify
267+our subject slightly as a test case:
268+
269+```
270+> ? +7:a
271+ z/@ux
272+z=0xdead.beef
273+
274+> =a a(+7 x=z:a)
275+
276+> ? a
277+ {x/@ud y/{p/$foo q/@rs r/@dr} x/@ux}
278+[x=42 y=[p=%foo q=.6.28 r=~m45] x=0xdead.beef]
279+
280+> ? x:a
281+ @ud
282+42
283+
284+> ? ^x:a
285+ @ux
286+0xdead.beef
287+```
288+
289+We don't want to hide any part of the noun from an expression.
290+So the modified limb `^x` *skips* the first match with a surface
291+`x`, getting us to our `0xdead.beef`. This is a unary notation:
292+`^^x` would skip the first two matches.
293+
294+## Editing
295+
296+Above, we mutated our first noun with the flashy `a(+7 x=z:a)`.
297+
298+Of course we are not really "modifying" a noun. Hoon is a pure
299+language. We are making an edited copy. `a(+7 x=z:a)` means "a
300+copy of `a`, with limb `+7` replaced by the product of `x=z:a`."
301+
302+We can edit multiple (disjoint) wings in one expression:
303+
304+```
305+> ? a(+7 [%hello %world], q.y .3.14)
306+ {x/@ud y/{p/$foo q/@rs r/@dr} $hello $world}
307+[x=42 y=[p=%foo q=.3.14 r=~m45] %hello %world]
308+```
309+
310+Notice that nothing stopped us from changing `+7` from
311+`x=0xdead.beef` to `[%hello %world]`. Since the mutated
312+copy is a different noun, it has a different type.
313+
314+(And remember that since `[x y z]` means `[x [y z]]`,
315+`[x y [%hello %world]]` means `[x y %hello %world]`.)
316+
317+## Cores and arms
318+
319+It should be reasonably clear how Hoon's system of fragments and
320+surfaces parallels variables, records or structures in a
321+classical language. But where is Hoon's equivalent of objects:
322+values which bind code to data?
323+
324+The Hoon equivalent of an object is a *core*. As usual in Hoon,
325+the resemblance is inexact. A core has a set of computed
326+attributes, or *arms*. Each arm is an expression whose subject
327+is the core. There is no argument, so an arm is not a method.
328+
329+Physically, a core is always a cell `[battery payload]`, where
330+the *payload* is any noun, and the *battery* is a tree of
331+formulas in Nock (Hoon's functional assembly language) that
332+implements the arms. (A battery is like a C++ vtable, sort of.)
333+
334+## The search algorithm
335+
336+As you'd expect with a computed attribute, there is only one
337+namespace and one search algorithm. We just extend the algorithm
338+described above. And an expression which uses a label can't know
339+whether the subject will resolve it to a surface fragment (a
340+*leg*) or to an arm.
341+
342+If we're searching a core and the label matches one of the core's
343+arms, we compute the arm against the core. If the label is not
344+found, we search into the payload of the core.
345+
346+## Some core examples
347+
348+When you type these examples, make sure you get the number of
349+spaces exactly right. Hoon syntax is not whitespace-sensitive
350+in general, except that "one space" is always a different token
351+from "two or more spaces."
352+
353+```
354+> ? x:a
355+ @ud
356+42
357+
358+> ? :per a x
359+ @ud
360+42
361+
362+> =b :per a :core ++ foo x ++ bar [q.y foo] --
363+```
364+
365+We're seeing some Hoon regular forms for the first time. `x:a`
366+turns out to be an irregular relative of the regular `:per` form.
367+
368+We'll get more into syntax in a later Urbyte. If some of these
369+examples seem syntactically a little funky, this isn't usually
370+way we'd do them in "real life." We don't normally write cores
371+on a single command line. In a file this would be:
372+
373+```
374+ :per a
375+ :core
376+ ++ foo x
377+ ++ bar [q.y foo]
378+ --
379+```
380+
381+which is much more readable, at least once you get used to it.
382+Let's look at the core itself:
383+
384+```
385+> b
386+<2.spy {x/@ud y/{p/$foo q/@rs r/@dr} x/@ux}>
387+
388+> ? +2:b
389+ *
390+[[0 6] [0 58] 9 4 0 1]
391+
392+> ? +3:b
393+ {x/@ud y/{p/$foo q/@rs r/@dr} x/@ux}
394+[x=42 y=[p=%foo q=.6.28 r=~m45] x=0xdead.beef]
395+```
396+
397+When we print `b`, or any core, we see that typed noun printing
398+can't be an invertible function in Hoon.
399+
400+We actually can read the battery (with `+2:b` above), but it's
401+just Nock code, not typed data. `<2.spy>` tells us the battery
402+has two arms and hashes to the three-letter code `spy`.
403+
404+When printing a full core, we don't even print the payload data,
405+just its type. But our `+3:b` confirms the `[battery payload]`
406+structure of the core. Remember, `+2` is the head and `+3` is
407+the tail.
408+
409+Finally, let's use this thing:
410+
411+```
412+> ? foo:b
413+ @ud
414+42
415+
416+> ? bar:b
417+ {@rs @ud}
418+[.6.28 42]
419+
420+? x:b
421+ @ud
422+42
423+```
424+
425+Seems legit.
426+
427+## The dojo subject
428+
429+Now that we've made a test subject which is a core, we can look
430+directly at the real dojo subject:
431+
432+```
433+> +1
434+[ [ [ a=[x=42 y=[p=%foo q=.6.28 r=~m45] x=0xdead.beef]
435+ b=<2.spy {x/@ud y/{p/$foo q/@rs r/@dr} x/@ux}>
436+ ]
437+ our=~zod
438+ now=~2016.7.18..08.05.15..0b5c
439+ eny=0vl.hsfrh.tg642.g5o21.1n80b.0h141.0vuan.pm8o4.77ovg.96rk0.n26nn
440+ ]
441+ ~
442+ <283.xzp 42.ajz 407.xtr 110.xht 1.ztu $151>
443+]
444+```
445+
446+We see a bunch of surfaces: our custom `a` and `b`; standard
447+surfaces for identity, date, and entropy; and a ginormous core
448+stack with *over eight hundred* total arms.
449+
450+To be exact, the syntax `<283.xzp 42.ajz 407.xtr 110.xht 1.ztu
451+$151>` denotes a stack of six cores, each of whose payload is
452+another core, until the innermost payload `%151` (the Hoon
453+version number). This stack is our standard library, from which
454+comes `add` and other fine functions. (We don't know how to
455+write a Hoon function yet, but we're getting way closer.)
456+
457+Let's clean up our subject, just to be hygienic:
458+
459+```
460+> =a
461+> =b
462+
463+> +1
464+[ [ our=~zod
465+ now=~2016.7.18..08.10.42..36a0
466+ eny=0vf.8j71j.hlqim.k340u.q0ual.v2cd8.cfa65.vkbte.e733g.ehihg.e8aog
467+ ]
468+ ~
469+ <283.xzp 42.ajz 407.xtr 110.xht 1.ztu $151>
470+]
471+```
472+
473+Again, remember that `=a` is not Hoon syntax, but `:dojo` syntax.
474+How the dojo assembles this subject remains a mystery. But it's
475+not a particularly interesting mystery.
476+
477+## And we're done
478+
479+And we're done! Press `^D` to exit:
480+
481+```
482+~zod:dojo> ^D
483+$
484+```
485+
486+## Questions and/or exercises
487+
488+As always, these questions are optional and only for fun.
489+
490+What's the best way to construct a core which acts as a function?
491+What do you do to call the function?
492+
493+Why don't any other languages use subject-oriented programming?
494+Which languages are most similar to it?
docs/hoon.md+4−5
@@ -1,12 +1,11 @@
1---
1---
2navhome: /docs
2navhome: /docs
3−sort: 4
3+sort: 5
4---
4---
5
5
6−# Hoon reference
6+# Hoon
7
7
8−This in-depth reference covers all the features of Hoon.
8+An in-depth technical reference for Hoon. Best for readers with
9−
9+an interest or background in programming languages.
10−If you prefer to learn from the bottom up, feel free to start here.
11
10
12<list/>
11<list/>
docs/nock.md+1−1
@@ -1,6 +1,6 @@
1---
1---
2navhome: /docs
2navhome: /docs
3−sort: 5
3+sort: 6
4title: Nock
4title: Nock
5---
5---
6
6
docs/using.md+1−3
@@ -5,8 +5,6 @@ sort: 2
5
5
6# Using
6# Using
7
7
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.
8+These short guides will get you installed, setup, and walk you through the basic features of Urbit.
9−
10−The sections do build on eachother, so it's a good idea to at least skim them in order.
11
9
12<list/>
10<list/>