urbit/shrub
1
1
Fork 0
mirror of https://github.com/urbit/shrub.git synced 2024-12-15 04:22:48 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'test' of github.com:galenwp/urbit into test

Browse Source
This commit is contained in:
Galen Wolfe-Pauly 2015-09-29 17:22:15 -07:00
commit 505fd03489
34 changed files with 2643 additions and 137 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
gen/hood/begin.hoon
View File

@ -21,7 +21,7 @@
?~ +.arg -
(fun.q.q tic.arg)
%+ sole-lo
[%& %helm-begin "your ship: ~"]
[%& %helm-begin "your urbit: ~"]
%+ sole-go fed:ag
|= his=@p
%+ sole-lo

10
pub/doc.md
View File

@ -1,7 +1,7 @@
urbit
=====
Urbit Manual
============
is a general-purpose computing stack designed to live in the cloud.
Urbit is a general-purpose computing stack designed to live in the cloud.
<list dataPreview="true"></list>
@ -11,6 +11,4 @@ is a general-purpose computing stack designed to live in the cloud.
------------------------------------------------------------------------
If you're new to the system, take a look at some of the
[guides](doc/guide) to get oriented. Come join us on `:talk` in the
`/urbit-meta` channel to ask questions and get help.
Come join us on `:talk` in the `/urbit-meta` channel to ask questions and get help.

4
pub/doc/arvo.md → pub/doc/arvo.mdy
View File

@ -1,3 +1,7 @@
---
sort: 2
---
arvo
====

8
pub/doc/arvo/ives.md
View File

@ -1,8 +0,0 @@
<div class="short">
`%ives`
=======
Isn't finished yet.
</div>

5
pub/doc/arvo/ives/ives.md
View File

@ -1,5 +0,0 @@
Ives: Reference
===============
Ives: Commentary
================

8
pub/doc/arvo/jael.md
View File

@ -1,8 +0,0 @@
<div class="short">
`%jael`
=======
Isn't finished yet.
</div>

5
pub/doc/arvo/jael/jael.md
View File

@ -1,5 +0,0 @@
Jael: Reference
===============
Jael: Commentary
================

8
pub/doc/arvo/kahn.md
View File

@ -1,8 +0,0 @@
<div class="short">
`%kahn`
=======
Isn't finished yet.
</div>

5
pub/doc/arvo/kahn/kahn.md
View File

@ -1,5 +0,0 @@
Kahn: Reference
===============
Kahn: Commentary
================

8
pub/doc/arvo/lunt.md
View File

@ -1,8 +0,0 @@
<div class="short">
`%lunt`
=======
Isn't finished yet.
</div>

5
pub/doc/arvo/lunt/lunt.md
View File

@ -1,5 +0,0 @@
Lunt: Reference
===============
Lunt: Commentary
================

4
pub/doc/hoon.md → pub/doc/hoon.mdy
View File

@ -1,3 +1,7 @@
---
sort: 1
---
<div class="short">
hoon

68
pub/doc/hoon/reference/pronunciation.md Normal file
View File

@ -0,0 +1,68 @@
Pronunciation
=============
Overview
--------
Hoon is a reserved-word-free
language - any text in the program is part of the program.
We use so many of these ASCII glyphs that we like to be able
to read them out loud. A language is meant to be _said_. The
squiggles have conventional names, sort of, some of them easy to
say, others not so much. So we've renamed them:
ace space
bar |
bas \
buc $
cab _
cen %
col :
com ,
doq "
dot .
fas /
gal <
gar >
hax #
hep -
kel {
ker }
ket ^
lus +
pam &
pat @
pel (
per )
sel [
sem ;
ser ]
sig ~
soq '
tar *
tec `
tis =
wut ?
zap !
Memorizing these names seems like a burden, but it actually makes
communicating about hoon code a lot faster and easier. `bartis`
sounds a lot better than 'bar equals'.
To pronounce a rune, concatenate the glyph names, stressing the
first syllable and softening the second vowel into a "schwa."
Hence, to say `~.`, say "sigdot." To say `|=`, say "bartis."
Which has an inevitable tendency to turn into "barts" - a sin
to be encouraged.
There are a few runes with irregular special pronunciations:
-- hephep phep
+- lushep slep
++ luslus slus
== tistis stet
+< lusgal glus
+> lusgar gras
-< hepgal gelp
-> hepgar garp

4
pub/doc/hoon/tutorial.md Normal file
View File

@ -0,0 +1,4 @@
Tutorials
=========
<list dataPreview="true" titlesOnly="true"></list>

232
pub/doc/hoon/tutorial/0-nouns.md Normal file
View File

@ -0,0 +1,232 @@
# Hoon 0: introduction
Hoon is a strict, higher-order typed pure-functional language.
Why Hoon? On the one hand, typed functional languages are known
for a particularly pleasant phenomenon: once your code compiles,
it's quite likely to work. On the other hand, most typed
functional languages are influenced by advanced mathematics.
As Barbie once put it, math class is hard.
Hoon is a typed FP language for the common street programmer.
Well-written Hoon is as concrete and data-oriented as possible.
The less functional magic you use, the better. One Haskell
hacker described Hoon as "imperative programming in a functional
language." He didn't mean this as a compliment, but we choose to
take it as one.
Moreover, one task of a type system in network computing is
marshalling typed data on the sender, and validating untrusted
data on the receiver. Hoon is very good at this task, which in
most typed languages is an afterthought at best.
The main disadvantage of Hoon is that its syntax and semantics
are unfamiliar. The syntax will remind too many of Perl, but
like most human languages (and unlike Perl) it combines a regular
core structure with irregular variations. Its semantic
complexity is bounded by the fact that the compiler is only 2000
lines of Hoon (admittedly an expressive language). Most peoples'
experience is that Hoon is much easier to learn than it looks.
## Nouns: data made boring
A noun is an atom or a cell. An atom is any unsigned integer. A
cell is an ordered pair of nouns.
The noun is an intentionally boring data model. Nouns (at least,
nouns in Urbit) don't have cycles (although a noun implementation
should take advantage of acyclic graph structure). Noun
comparison is always by value (there is no way for the programmer
to test pointer equality). Nouns are strict; there is no such
thing as an infinite noun. And, of course, nouns are immutable.
So there's basically no way to have any real fun with nouns.
For language historians, nouns are Lisp's S-expressions, minus a
lot of hacks, tricks, and features that made sense 50 years ago.
In particular, because atoms are not tagged (an atom can encode a
string, for instance), nouns work best with a static type system.
How do you print an atom if you don't know whether it's a string
or a number? You can guess, but...
## A type system for nouns
So learning nouns in practice involves learning them with a type
system that makes them usable. Fortunately, we have that.
One obstacle to learning Hoon is that it has two quite distinct
concepts that might equally be called a "type." Worse, most
other typed functional languages are mathy and share a basically
mathematical concept of "type." We can't avoid using the T-word
occasionally, but it has no precise meaning in Hoon and can be
extremely confusing.
Hoon's two kinds of "type" are `span` and `mold`. A span is both
a constructively defined set of nouns, and a semantic convention
for users in that set. A `mold` is a function whose range is
some useful span. A mold is always idempotent (for any noun x,
`f(x)` equals `f(f(x))`), and its domain is any noun.
(One way to explain this is that while a span is what most
languages call a "type," Hoon has no way for the programmer to
express a span directly. Instead, we use inference to define it
as the range of a function. This same function, the mold, can
also be used to validate or normalize untrusted, untyped data --
a common problem in modern programming.)
(Hoon's inference algorithm is somewhat dumber than the
unification algorithms (Hindley-Milner) used in most typed
functional languages. Hoon reasons only forward, not backward.
It needs more manual annotations, which you usually want anyway.
Otherwise, it gets more or less the same job done.)
## Let's make some nouns
This stuff isn't even slightly hard. Let's make a noun:
```
~tasfyn-partyv:dojo> 42
```
You'll see the expression you entered, then the resulting value:
```
> 42
42
```
Let's try a different value:
```
~tasfyn-partyv:dojo> 0x2a
```
You'll see:
```
> 0x2a
0x2a
```
`42` and `0x2a` are actually *the same noun*, because they're the
same number. But we don't just have the noun to print - we have
a `[span noun]` cell (sometimes called a `vase`).
As you recall, a span defines a set of nouns and a semantic
interpretation. As sets, both spans here are "any number". But
semantically, `42` has a decimal span and `0x2a` hexadecimal, so
they print differently.
(It's important to note that Hoon is a statically typed language.
We don't work with vases unless we're dynamically compiling code,
which is of course what we're doing here in the shell. Dynamic
type is static type compiled at runtime.)
Finally, let's make some cells. Try these on your own ship:
```
~tasfyn-partyv:dojo> [42 0x2a]
~tasfyn-partyv:dojo> [42 [0x2a 420]]
~tasfyn-partyv:dojo> [42 0x2a 420]
```
We observe that cells associate right: `[a b c]` is just another
way of writing `[a [b c]]`.
Also, Lisp veterans beware: Hoon `[a b]` is Lisp `(a . b)`, Lisp
`(a b)` is Hoon `[a b ~]`(`~` represents nil, with a value of atom `0`). Lisp and Hoon are both pair-oriented
languages down below, but Lisp has a layer of sugar that makes it
look list-oriented. Hoon loves its "improper lists," ie, tuples.
## Looking at spans
What are these mysterious spans? We can see them with the `?`
prefix, which prints the span along with the result. Moving to
a more compact example format:
```
~tasfyn-partyv:dojo> ? 42
@ud
42
~tasfyn-partyv:dojo> ? 0x2a
@ux
0x2a
```
`@ud` and `@ux` stand for "unsigned decimal" and "unsigned hex,"
obviously. But what is this syntax?
We only derive spans through inference. So there's no language
syntax for a span. We have to be able to print spans, though, if
only for debugging and diagnostics. `@ud` is an print-only
syntax. (In this case it happens to be the same as the `mold`
syntax, but that's just a coincidence.)
## Looking at spans, part 2
A good way to teach yourself to think in nouns is to look not at
the prettyprinted span, but at the actual noun it's made of.
Since everything in Hoon is a noun, a span is a noun too. When
we use `??` rather than `?` as a prefix, we see the noun:
```
~tasfyn-partyv:dojo> ?? 42
[%atom %ud]
42
~tasfyn-partyv:dojo> ?? [42 0x2a]
[%cell [%atom %ud] [%atom %ux]]
[42 0x2a]
```
What is this `%atom` notation? Is it a real noun? Can anyone
make one?
```
~tasfyn-partyv:dojo> %atom
%atom
~tasfyn-partyv:dojo> %foo
%foo
~tasfyn-partyv:dojo> [%foo %bar]
[%foo %bar]
```
What if we look at the span?
```
~tasfyn-partyv:dojo> ? %foo
%foo
%foo
~tasfyn-partyv:dojo> ?? %foo
[%cube 7.303.014 %atom %tas]
%foo
```
This takes a little bit of explaining. First of all, `7.303.014`
is just the German (and Urbit) way of writing `7,303,014`, or the
hexadecimal number `0x6f.6f66`, or the string "foo" as an
unsigned integer. (It's much easier to work with large integers
when the digits are grouped.) Second, remembering that cells
nest right, `[%cube 7.303.014 %atom %tas]` is really `[%cube
7.303.014 [%atom %tas]]`.
A `%cube` span is a constant -- a set of one noun, the atom
`7.303.014`. But we still need to know how to print that noun.
In this case, it's an `[%atom %tas]`, ie, a text symbol.
Cubes don't have to be symbols -- in fact, we can take the
numbers we've just been using, and make them constants:
```
~tasfyn-partyv:dojo> %42
%42
~tasfyn-partyv:dojo> ? %42
%42
%42
~tasfyn-partyv:dojo> ?? %42
[%cube 42 %atom %ud]
%42
```
## Our first mold
After seeing a few span examples, are we ready to describe the
set of all spans with a Hoon mold? Well, no, but let's try it
anyway. Ignore the syntax (which we'll explain later; this is a
tutorial, not a reference manual), and you'll get the idea:
```
++ span
$% [%atom @tas]
[%cell span span]
[%cube * span]
==
```
This mold is not the entire definition of `span`, just the cases
we've seen so far. In English, a valid span is either:
- a cell with head `%atom`, and tail some symbol.
- a cell with head `%cell`, and tail some pair of spans.
- a cell with head `%cube`, and tail a noun-span pair.
The head of a span is essentially the tag in a variant record,
a pattern every programming language has. To use the noun, we
look at the head and then decide what to do with the tail.

229
pub/doc/hoon/tutorial/1-twigs.md Normal file
View File

@ -0,0 +1,229 @@
# Hoon 1: twigs and legs
In the last chapter we learned how to make nouns. In this
chapter we'll start programming a little.
## Nock for Hoon programmers
Hoon compiles itself to a pico-interpreter called Nock. This
isn't the place to explain Nock (which is to Hoon much as
assembly language is to C), but Nock is just a way to express a
function as a noun.
Specifically, you can think of Nock as a (Turing-complete)
interpreter shaped like (pseudocode):
```
Nock(subject formula) => product
```
Your function is the noun `formula`. The input to the function
is the noun `subject`. The output is `product`. If something
about this seems complicated or even interesting, you may be
misunderstanding it.
## From Hoon to Nock
The Hoon parser turns an source expression (even one as simple as
`42` from the last chapter) into a noun called a `twig`. If you
know what an AST is, a twig is an AST. (If you don't know what
an AST is, it's not worth the student loans.)
To simplify slightly, the Hoon compiler is shaped like:
```
Hoon(subject-span function-twig) => [product-span formula-nock]
```
Hoon, like Nock, is a *subject-oriented* language - your twig is
always executed against one input noun, the subject. For any
subject noun in `subject-span`, the compiler produces a Nock
formula that computes `function-twig` on that subject, and a
`product-span` that is the span of the product.
(Pretty much no other language works this way. In a normal
language, your code is executed against a scope, stack, or other
variable context, which may not even be a regular user-level
value. This change is one of the hardest things to understand
about Hoon, mostly because it's hard to stay convinced that
subject-oriented programming is as straightforward as it is.)
## From constants to twigs
In the last chapter we were entering degenerate twigs like `42`.
Obviously this doesn't use the subject at all.
Let's use the dojo variable facility (this is *not* Hoon syntax,
just a dojo command) to make a test subject:
```
~tasfyn-partyv:dojo> =test [[[8 9] 5] [6 7]]
```
We can evaluate twigs against this subject with the Hoon `:`
syntax (`a:b` uses the product of `b` as the subject of `a`).
```
~tasfyn-partyv:dojo> 42:test
42
```
## Tree addressing
The simplest twigs produce a subtree, or "leg", of the subject.
A cell, of course, is a binary tree. The very simplest twig is
`.`, which produces the root of the tree - the whole subject:
```
~tasfyn-partyv:dojo> .:test
[[[8 9] 5] 6 7]
```
(If you're wondering why `[6 7]` got printed as `6 7`, remember
that `[]` associates to the right.)
Hoon has a simple tree addressing scheme (inherited from Nock):
the root is `1`, the head of `n` is `2n`, the tail is `2n+1`.
The twig syntax is `+n`. Hence:
```
~tasfyn-partyv:dojo> +1:test
[[[8 9] 5] 6 7]
```
Our example is a sort of Hoon joke, not very funny:
```
~tasfyn-partyv:dojo> +2:test
[[8 9] 5]
~tasfyn-partyv:dojo> +3:test
[6 7]
~tasfyn-partyv:dojo> +4:test
[8 9]
~tasfyn-partyv:dojo> +5:test
5
~tasfyn-partyv:dojo> +6:test
6
~tasfyn-partyv:dojo> +7:test
7
```
And so on. An instinct for binary tree geometry develops over
time as you use the system, rather the way most programmers
learn to do binary math.
## Femur syntax
A "femur" is an alternative syntax for a tree address. The femur
syntax creates a recognizable geometric shape by alternating
between two head/tail pairs, read left to right: `-` and `+`,
`<` and `>`.
Thus `-` is `+2`, `+` is `+3`, `+<` is `+6`, `->` is `+5`, `-<+`
is `+9`, etc. The decimal numbers are distracting, whereas the
glyph string binds directly to the tree geometry as you learn it.
We actually almost never use the decimal tree geometry syntax.
## Simple faces
But it would be pretty tough to program in Hoon if explicit
geometry was the only way of getting data out of a subject.
Let's introduce some new syntax:
```
~tasfyn-partyv:dojo> foo=42
foo=42
~tasfyn-partyv:dojo> ? foo=42
foo=@ud
foo=42
~tasfyn-partyv:dojo> ?? foo=42
[%face %foo %atom %ud]
foo=42
```
To extend our `++span` mold:
```
++ span
$% [%atom @tas]
[%cell span span]
[%cube * span]
[%face @tas span]
==
```
The `%face` span wraps a label around a noun. Then we can
get a leg by name. Let's make a new dojo variable:
```
~tasfyn-partyv:dojo> =test [[[8 9] 5] foo=[6 7]]
```
The syntax is what you might expect:
```
~tasfyn-partyv:dojo> foo:test
[6 7]
```
Does this do what you expect it to do?
```
~tasfyn-partyv:dojo> +3:test
foo=[6 7]
~tasfyn-partyv:dojo> ? +3:test
foo=[@ud @ud]
foo=[6 7]
~tasfyn-partyv:dojo> ?? +3:test
[%face %foo %cell [%atom %ud] %atom %ud]
foo=[6 7]
```
## Interesting faces; wings
Again, you're probably used to name resolution in variable scopes
and flat records, but not in trees. (Partly this is because the
tradition in language design is to eschew semantics that make it
hard to build simple symbol tables, because linear search of a
big tree is a bad idea on '80s hardware.)
Let's look at a few more interesting face cases. First, suppose
we have two cases of `foo`?
```
~tasfyn-partyv:dojo> =test [[foo=[8 9] 5] foo=[6 7]]
~tasfyn-partyv:dojo> foo:test
[8 9]
```
In the tree search, the head wins. We can overcome this with a
`^` prefix, which tells the search to skip its first hit:
```
~tasfyn-partyv:dojo> =test [[foo=[8 9] 5] foo=[6 7]]
~tasfyn-partyv:dojo> ^foo:test
[6 7]
```
`^^foo` will skip two foos, `^^^foo` three, up to `n`.
But what about nested labels?
```
~tasfyn-partyv:dojo> =test [[[8 9] 5] foo=[6 bar=7]]
~tasfyn-partyv:dojo> bar:test
/~tasfyn-partyv/home/~2015.9.16..21.40.21..1aec:<[1 1].[1 9]>
-find-limb.bar
find-none
```
It didn't seem to like that. We'll need a nested search:
```
~tasfyn-partyv:dojo> bar.foo:test
7
```
`bar.foo` here is a `wing`, a search path in a noun. Note that
the wing runs from left to right, ie, the opposite of most
languages: `bar.foo` means "bar inside foo."
Each step in a wing is a `limb`. A limb can be a tree address,
like `+3` or `.`, or a label like `foo`. We can combine them in
one wing:
```
~tasfyn-partyv:dojo> bar.foo.+3:test
7
```
## Mutation
Well, not really. We can't modify nouns; the concept doesn't
even make sense in Hoon. Rather, we build new nouns which are
(logical -- the pointers are actually shared) copies of old ones,
with changes.
Let's build a "mutated" copy of our test noun:
```
~tasfyn-partyv:dojo> test
[[[8 9] 5] foo=[6 bar=7]]
~tasfyn-partyv:dojo> test(foo 42)
[[[8 9] 5] foo=42]
~tasfyn-partyv:dojo> test(+8 %eight, bar.foo [%hello %world])
[[[%eight 9] 5] foo=[6 [%hello %world]]]
```
As we see, there's no obvious need for the mutant noun to be
shaped anything like the old noun. They're different nouns.
At this point, you have a simplified but basically sound idea of
how Hoon builds and manages nouns. Next, it's time to do some
programming.

392
pub/doc/hoon/tutorial/2-syntax.md Normal file
View File

@ -0,0 +1,392 @@
# Hoon 2: serious syntax
We've done a bunch of fun stuff on the command line. We know our
nouns. It's time to actually write some serious code -- in a
real source file.
## Building a simple generator
In Urbit there's a variety of source file roles, distinguished by
the magic paths they're loaded from: `/gen` for generators,
`/ape` for appliances, `/fab` for renderers, etc.
We'll start with a generator, the simplest kind of Urbit program.
### Create a sandbox desk
A desk is the Urbit equivalent of a `git` branch. We're just
playing around here and don't intend to soil our `%home` desk with
test files, so let's make a sandbox:
```
|merge %sandbox our %home
```
### Mount the sandbox
Your Urbit pier is in `~/tasfyn-partyv`, or at least mine is.
So we can get our code into Urbit, run the command
```
~tasfyn-partyv:dojo> |mount /=sandbox=/gen %gen
```
mounts the `/gen` folder from the `%sandbox` desk in your Unix
directory `~/tasfyn-partyv/gen`. The mount is a two-way sync,
like your Dropbox. When you edit a Unix file and save, your edit
is automatically committed as a change to `%sandbox`.
### Execute from the sandbox
The `%sandbox` desk obviously is merged from `%home`, so it
contains find all the default facilities you'd expect there.
Bear in mind, we didn't set it to auto-update when `%home`
is updated (that would be `|sync` instead of `|merge`).
So we're not roughing it when we set the dojo to load from
`%sandbox`:
```
[switch to %home]
```
### Write your builder
Let's build the simplest possible kind of generator, a builder.
With your favorite Unix text editor (there are Hoon modes for vim
and emacs), create the file `~/tasfyn-partyv/gen/test.hoon`.
Edit it into this:
```
:- %say |= * :- %noun
[%hello %world]
```
Get the spaces exactly right, please. Hoon is not in general a
whitespace-sensitive language, but the difference between one
space and two-or-more matters. And for the moment, think of
```
:- %say |= * :- %noun
```
as gibberish boilerplate at the start of a file, like `#include
"stdio.h"` at the start of a C program. Any of our old Hoon
constants would work in place of `[%hello %world`].
Now, run your builder:
```
~tasfyn-partyv:dojo/sandbox> +test
[%hello %world]
```
Obviously this is your first Hoon *program* per se.
## Hoon syntax 101
But what's up with this syntax?
### A syntactic apology
The relationship between ASCII and human programming languages
is like the relationship between the electric guitar and
rock-and-roll. If it doesn't have a guitar, it's not rock.
Some great rockers play three chords, like Johnny Ramone; some
shred it up, like Jimmy Page.
The two major families of ASCII-shredding languages are Perl and
the even more spectacular APL. (Using non-ASCII characters is
just a fail, but APL successors like J fixed this.) No one
has any right to rag on Larry Wall or Ken Iverson, but Hoon,
though it shreds, shreds very differently.
The philosophical case for a "metalhead" language is threefold.
One, human beings are much better at associating meaning with
symbols than they think they are. Two, a programming language is
a professional tool and not a plastic shovel for three-year-olds.
And three, the alternative to heavy metal is keywords. When you
use a keyword language, not only are you forcing the programmer
to tiptoe around a ridiculous maze of restricted words used and
reserved, you're expressing your program through two translation
steps: symbol->English and English->computation. When you shred,
you are going direct: symbol->computation. Especially in a pure
language, this creates a sense of "seeing the function" which no
keyword language can quite duplicate.
But any metalhead language you don't yet know is line noise.
Let's get you up to speed as fast as possible.
### A glyphic bestiary
A programming language needs to be not just read but said. But
no one wants to say "ampersand." Therefore, we've taken the
liberty of assigning three-letter names to all ASCII glyphs.
Some of these bindings are obvious and some aren't. You'll be
genuinely surprised at how easy they are to remember:
```
ace [1 space] dot . pan ]
bar | fas / pel )
bis \ gap [>1 space, nl] pid }
buc $ hax # ran >
cab _ ket ^ rep '
cen % lep ( sac ;
col : lit < tar *
com , lus + tec `
das - mat @ tis =
den " med & wut ?
dip { nap [ zap !
```
It's fun to confuse people by using these outside Urbit. A few
digraphs also have irregular sounds:
```
== stet
-- shed
++ slus
-> dart
-< dusk
+> lark
+< lush
```
### The shape of a twig
A twig, of course, is a noun. As usual, the easiest way to
explain both the syntax that compiles into that noun, and the
semantic meaning of the noun, is the noun's physical structure.
#### Autocons
A twig is always a cell, and any cell of twigs is a twig
producing a cell. As an homage to Lisp, we call this
"autocons." Where you'd write `(cons a b)` in Lisp, you write
`[a b]` in Hoon, and the shape of the twig follows.
The `???` prefix prints a twig as a noun instead of running it.
Let's see autocons in action:
```
~tasfyn-partyv:dojo/sandbox> ??? 42
[%dtzy %ud 42]
~tasfyn-partyv:dojo/sandbox> ??? 0x2a
[%dtzy %ux 42]
~tasfyn-partyv:dojo/sandbox> ??? [42 0xa]
[[%dtzy %ud 42] %dtzy %ux 42]
```
(As always, it may confuse *you* that this is the same noun as
`[[%dtzy %ud 42] [%dtzy %ux 42]]`, but it doesn't confuse Hoon.)
#### The stem-bulb pattern
If the head of your twig is a cell, it's an autocons. If the
head is an atom, it's an unpronounceable four-letter symbol like
the `%dtzy` above.
This is the same pattern as we see in the `span` mold -- a
variant record, essentially, in nouns. The head of one of these
cells is called the "stem." The tail is the "bulb." The shape
of the bulb is totally dependent on the value of the stem.
#### Runes and stems
A "rune" (a word intentionally chosen to annoy Go programmers) is
a digraph - a sequence of two ASCII glyphs. If you know C, you
know digraphs like `->` and `?:` and are used to reading them as
single characters.
In Hoon you can *say* them as words: "dasran" and "wattis"
respectively. In a metalhead language, if we had to say
"minus greater-than" and "question-colon", we'd just die.
Most twig stems are made from runes, by concatenating the glyph
names and removing the vowels. For example, the rune `=+`,
pronounced "tislus," becomes the stem `%tsls`. (Note that in
many noun implementations, this is a 31-bit direct value.)
(Some stems (like `%dtzy`) are not runes, simply because they
don't have regular-form syntax and don't need to use precious
ASCII real estate. They are otherwise no different.)
An important point to note about runes: they're organized. The
first glyph in the rune defines a category. For instance, runes
starting with `.` compute intrinsics; runes starting with `|`
produce cores; etc.
Another important point about runes: they come in two flavors,
"natural" (stems interpreted directly by the compiler) and
"synthetic" (macros, essentially).
(Language food fight warning: one advantage of Hoon over Lisp is
that all Hoon macros are inherently hygienic. Another advantage
is that Hoon has no (user-level) macros. In Hoon terms, nobody
gets to invent their own runes. A DSL is always and everywhere
a write-only language. Hoon shreds its ASCII pretty hard, but
the same squiggles mean the same things in everyone's code.)
#### Wide and tall regular forms
A good rune example is the simple rune `=+`, pronounced "tislus",
which becomes the stem `%tsls`. A `%tsls` twig has the shape
`[%tsls twig twig]`.
The very elegance of functional languages creates a visual
problem that imperative languages lack. An imperative language
has distinct statements (with side effects) and (usually pure)
expressions; it's natural that in most well-formatted code,
statements flow vertically down the screen, and expressions grow
horizontally across this. This interplay creates a natural and
relaxing shape on your screen.
In a functional language, there's no difference. The trivial
functional syntax is Lisp's, which has two major problems. One:
piles of expression terminators build up at the bottom of complex
functions. Two: the natural shape of code is diagonal. The more
complex a function, the more it wants to besiege the right
margin. The children of a node have to start to the right of its
parent, so the right margin bounds the tree depth.
Hoon does not completely solve these problems, but alleviates
them. In Hoon, there are actually two regular syntax forms for
most twig cases: "tall" and "wide" form. Tall twigs can contain
wide twigs, but not vice versa, so the visual shape of a program
is very like that of a statements-and-expressions language.
Also, in tall mode, most runes don't need terminators. Take
`=+`, for example. Since the parser knows to expect exactly
two twigs after the `=+` rune, it doesn't need any extra syntax
to tell it that it's done.
Let's try a wide `=+` in the dojo:
```
~tasfyn-partyv:dojo/sandbox> =+(planet=%world [%hello planet])
[%hello %world]
```
(`=+` seems to be some sort of variable declaration? Let's not
worry about it right now. We're on syntax.)
The wide syntax for a `=+` twig, or any binary rune: `(`, the
first subtwig, one space, the second subtwig, and `)`). To read
this twig out loud, you'd say:
```
tislus lap planet is cen world ace nep cen hello ace planet pen
pal
```
("tis" not in a rune gets contracted to "is".)
Let's try a tall `=+` in `test.hoon`:
```
:- %say |= * :- %noun
=+ planet=%world
[%hello planet]
```
The tall syntax for a `=+` twig, or any binary rune: the rune, at
least two spaces or one newline, the first subtwig, at least two
spaces or one newline, the second subtwig. Again, tall subtwigs
can be tall or wide; wide subtwigs have to be wide.
(Note that our boilerplate line is a bunch of tall runes on one
line, with two-space gaps. This is unusual but quite legal, and
not to be confused with the actual wide form.)
To read this twig out loud, you'd say:
```
tislus gap planet is cen world gap nep cen hello ace planet pen
```
#### Layout conventions
Should you use wide twigs or tall twigs? When? How? What
should your code look like? You're the artist. Except for the
difference between one space (`ace`) and more space (`gap`), the
parser doesn't care how you format your code. Hoon is not Go --
there are no fixed rules for doing it right.
However, the universal convention is to keep lines under 80
characters. Also, hard tab characters are illegal. And when in
doubt, make your code look like the kernel code.
##### Backstep indentation
Note that the "variable declaration" concept of `=+` (which is no
more a variable declaration than a Tasmanian tiger is a tiger)
works perfectly here. Because `[%hello planet]` -- despite being
a subtree of the the `=+` twig -- is at the same indent level.
So our code flows down the screen, not down and to the right, and
of course there are no superfluous terminators. It looks good,
and creates fewer hard-to-find syntax errors than you'd think.
This is called "backstep" indentation. Another example, using a
ternary rune that has a strange resemblance to C:
```
:- %say |= * :- %noun
=+ planet=%world
?: =(%world planet)
[%hello planet]
[%goodbye planet]
```
It's not always the case when backstepping that the largest
subtwig is at the bottom and loses no margin, but it often is.
And not all runes have tuple structure; some are n-ary, and use
the `==` terminator (again, pronounced "stet"):
```
:- %say |= * :- %noun
=+ planet=%world
?+ planet
[%unknown planet]
%world [%hello planet]
%ocean [%goodbye planet]
==
```
So we occasionally lose right-margin as we descend a deep twig.
But we can keep this lossage low with good layout design. The
goal is to keep the heavy twigs on the right, and Hoon tries as
hard as possible to help you with this.
For instance, `=+` ("tislus") is a binary rune: `=+(a b)`. In
most cases of `=+` the heavy twig is `b`, but sometimes it's `a`.
So we can use its friend the `=-` rune ("tisdas") to get the same
semantics with the right shape: `=-(b a)`.
#### Irregular forms
There are more regular forms than we've shown above, but not a
lot more. Hoon would be quite easy to learn if it was only its
regular forms. It wouldn't be as easy to read or use, though.
The learning curve is important, but not all-important.
Some stems (like the `%dtzy` constants above) obviously don't and
can't have any kind of regular form (which is why `%dtzy` is not
a real digraph rune). Many of the true runes have only regular
forms. But some have irregular forms. Irregular forms are
always wide, but there is no other constraint on their syntax.
We've already encountered one of the irregular forms: `foo=42`
from the last chapter, and `planet=%world` here. Let's unpack
this twig:
```
~tasfyn-partyv:dojo/sandbox> ?? %world
[%cube 431.316.168.567 %atom %tas]
%world
~tasfyn-partyv:dojo/sandbox> ??? %world
[%dtzz %tas 431.316.168.567]
```
Clearly, `%dtzz` is one of our non-regulars. But we can wrap it
with our irregular form:
```
~tasfyn-partyv:dojo/sandbox> ?? planet=%world
[%face %planet [%cube 431.316.168.567 %atom %tas]]
planet=%world
~tasfyn-partyv:dojo/sandbox> ??? planet=%world
[%ktts %planet %dtzz %tas 431.316.168.567]
```
Since `%ktts` is "kettis", ie, `^=`, this has to be the irregular
form of
```
~tasfyn-partyv:dojo/sandbox> ^=(planet %world)
planet=world
```
So if we wrote our example without this irregular form, it'd be
```
:- %say |= * :- %noun
=+ ^=(planet %world)
[%hello planet]
```
Or with a gratuitous use of tall form:
```
:- %say |= * :- %noun
=+ ^= planet %world
[%hello planet]
```
Now you know how to read Hoon! For fun, try to pronounce more of
the code on this page. Please don't laugh too hard at yourself.

316
pub/doc/hoon/tutorial/3-program.md Normal file
View File

@ -0,0 +1,316 @@
# Hoon 3: our first program
It's time for us to do some actual programming. In this section,
we'll work through that classic Urbit pons asinorum, decrement.
If you learned Nock before Hoon, you've already done decrement.
If not, all you need to know is that the only arithmetic
intrinsic in Nock is increment -- in Hoon, the unary `.+` rune.
So an actual decrement function is required.
In chapter 3, we write a decrement builder: more or less the
simplest nontrivial Urbit program. We should be able to run this
example:
```
~tasfyn-partyv:dojo/sandbox> +test 42
41
```
## What's in that subject?
As we've seen, Hoon works by running a twig against a subject.
We've been cheerfully running twigs through three chapters while
avoiding the question: what's in the subject? To avoid the issue
we've built a lot of constants, etc.
Of course your twig's subject comes from whoever runs it. There
is no one true subject. Our twigs on the command line are not
run against the same subject as our generator code, even though
they are both run by the same `:dojo` appliance.
But the short answer is that both command-line and builder get
*basically* the same subject: some ginormous noun containing all
kinds of bells and whistles and slicers and dicers, including a
kernel library which can needless to say decrement in its sleep.
As yet you have only faced human-sized nouns. We need not yet
acquaint you with this mighty Yggdrasil, Mother of Trees. First
we need to figure out what she could even be made of.
## Clearing the subject
We'll start by clearing the subject:
```
:- %say |= * :- %noun
=> ~
[%hello %world]
```
The `=>` rune ("tisran"), for `=>(p q)` executes `p` against
the subject, then uses that product as the subject of `q`.
(We've already used an irregular form of `=>`, or to be more
precise its mirror `=<` ("tislit"). In chapter 1, when we wrote
`+3:test`, we meant `=>(test +3)` or `=<(+3 test)`.)
What is this `~`? It's Hoon `nil`, a zero atom with this span:
```
~tasfyn-partyv:dojo/sandbox> ?? ~
[%cube 0 %atom %n]
~
```
We use it for list terminators and the like. Obviously, since
our old test code is just a constant, a null subject works fine:
```
~tasfyn-partyv:dojo/sandbox> +test
[%hello %world]
```
## Getting an argument
Obviously, if we want to write a decrement builder, we'll have to
get an argument from the command line. This involves changing
the `test.hoon` boilerplate a little:
```
:- %say |= [* [[arg=@ud ~] ~]] :- %noun
=> arg=arg
[%hello arg]
~tasfyn-partyv:dojo/sandbox> +test 42
[%hello 42]
```
`=> arg=arg` looks a little odd. We wouldn't ordinarily do
this. We're just replacing a very interesting subject that
contains `arg` with a very boring one that contains only `arg`,
for the same reason we cleared the subject with `~`.
In case there's any doubt about the subject (`.` is limb syntax
for `+1`, ie, the whole noun):
```
:- %say |= [* [[arg=@ud ~] ~]] :- %noun
=> arg=arg
.
~tasfyn-partyv:dojo/sandbox> +test 42
arg=42
```
We can even write a trivial increment function using `.+`:
```
:- %say |= [* [[arg=@ud ~] ~]] :- %noun
=> arg=arg
+(arg)
~tasfyn-partyv:dojo/sandbox> +test 42
43
```
Below we'll skip both boilerplate lines in our examples.
## A core is a code-data cell
But how do we actually, like, code? The algorithm for decrement
is clear. We need to count up to 41. (How do we run useful
programs on a computer with O(n) decrement? That's an
implementation detail.)
We'll need another kind of noun: the *core*. Briefly, the core
is always a cell `[battery payload]`. The payload is data, the
battery is code -- one or more Nock formulas, to be exact.
Consider a simple core with a one-formula battery. Remember, we
create Nock formulas by compiling a twig against a subject. The
subject is dynamic data, but its span is static. What span do we
give the compiler, and what noun do we give the formula?
A core formula always has the core as its subject. The formula
is essentially a computed attribute on the payload. But if the
subject was just the payload, the formula couldn't recurse.
Of course, there is no need to restrict ourselves to one computed
attribute. We can just stick a bunch of formulas together and
call them a battery. The source twigs in this core are called
"arms," which have labels just like the faces we saw earlier.
Hoon overloads computed attributes (arms) and literal attributes
(legs) in the same namespace. A label in a wing may refer to
either. To extend the name-resolution tree search described in
chapter 1, when searching a core, we look for a matching arm.
If we find it we're done. If we don't, or if a `^` mark makes us
skip, we search into the payload.
If a name resolves to a core arm, but it's not the last limb in the
wing, the arm produces the core itself. Similarly, when the
wing is not an access but a mutation, the arm refers to the core.
This demands an example: if `foo` produces some core `c`, and
`bar` is an arm in that `c` (which may be `foo` itself, or some
leg within `foo`), `bar.foo` runs the arm formula with `c` as the
subject. You might think that `moo.bar.foo` would compute
`bar.foo`, then search for `moo` within that result. Instead, it
searches for `moo` within `c`. (You can get the other result
with `moo:bar.foo`.)
Does this sound too tricky? It should - it's about the most
complicated feature of Hoon. It's all downhill once you
understand cores.
Let's again extend our `++span` mold:
```
++ span
$% [%atom @tas]
[%cell span span]
[%core span (map ,@tas twig)]
[%cube * span]
[%face @tas span]
==
```
This definition of `%core` is somewhat simplified from the
reality, but basically conveys it. (Moreover, this version of
`span` describes every kind of noun we build.) In our `%core` we
see a payload span and a name-to-twig arm table, as expected.
Is a core an object? Not quite, because an arm is not a method.
Methods in an OO language have arguments. Arms are functions
only of the payload. (A method in Hoon is an arm that produces a
gate, which is another core -- but we're getting too far ahead.)
However, the battery does look a lot like a classic "vtable."
## Increment with a core
Let's increment with a core:
```
=< inc
|%
++ inc
+(arg)
--
~tasfyn-partyv:dojo/sandbox> +test 42
43
```
What's going on? We used the `|%` rune ("barcen") to produce a
core. (There are a lot of runes which create cores; they all
start with `|`, and are basically macros that turn into `|%`.)
The payload of a core produced with `|%` is the subject with
which `|%` is compiled. We might say that `|%` wraps a core
around its subject. In this case, the subject of the `|%`,
and thus payload, is our `arg=@ud` argument.
Then we used this core as the subject of the simple wing `inc`.
(Remember that `=<(a b)` is just `=>(b a)`.)
We can actually print out a core. Take out the `=< inc`:
```
|%
++ inc
+(arg)
--
~tasfyn-partyv:dojo/sandbox> +test 42
!!!
~tasfyn-partyv:dojo/sandbox> ? +test 42
!!!
```
Cores can be large and complex, and we obviously can't render all
the data in them, either when printing a type or a value. At
some point, you'll probably make the mistake of printing a big
core, maybe even the whole kernel, as an untyped noun. Just
press ^C.
## Adding a counter
To decrement, we need to count up to the argument. So we need a
counter in our subject, because where else would it go? Let's
change the subject to add a counter, `pre`:
```
=> [pre=0 .]
=< inc
|%
++ inc
+(arg)
--
~tasfyn-partyv:dojo/sandbox> +test 42
43
```
Once again, `.` is the whole subject, so we're wrapping it in a
cell whose head is `pre=0`. Through the magic of labels, this
doesn't change the way we use `arg`, even though it's one level
deeper in the subject tree. Let's look at the subject again:
```
=> [pre=0 .]
.
~tasfyn-partyv:dojo/sandbox> +test 42
[pre=0 arg=42]
~tasfyn-partyv:dojo/sandbox> ? +test 42
[pre=@ud arg=@ud]
[pre=0 arg=42]
```
There's actually a simpler way to write this. We've seen it
already. It's not exactly a variable declaration:
```
=+ pre=0
.
~tasfyn-partyv:dojo/sandbox> +test 42
[pre=0 arg=42]
```
## We actually decrement
Now we can write our actual decrement program:
```
=+ pre=0
=< dec
|%
++ dec
?: =(arg +(pre))
pre
dec(pre +(pre))
--
~tasfyn-partyv:dojo/sandbox> +test 42
41
```
`=(a b)` is an irregular form of `.=(a b)`, ie, "dottis" or the
noun `[%dtts a b]`. Likewise, `+(a)` is `.+(a)`, ie, "dotlus"
or `[%dtls a]`.
`?:` is a regular rune which does exactly what you think it does.
Bear in mind, though, that in Hoon 0 (`&`, "rob") is true and 1
(`|`, "bar") is false.
The real action is in `dec(pre +(pre))`. This is obviously an
irregular form -- it's the same mutation form we saw before.
Writing it out in full regular form:
```
=+ pre=0
=< dec
|%
++ dec
?: =(arg +(pre))
pre
%= dec
pre +(pre)
==
--
~tasfyn-partyv:dojo/sandbox> +test 42
41
```
`%=`, "centis", is the rune which almost every use of a wing
resolves to. It might be called "evaluate with changes."
When we evaluate with changes, we take a wing (`dec`) here and
evaluate it as described above. Searching in the subject, which
is of course our core, we find an arm called `dec` and run it.
The changes (replacing `pre` with `+(pre)`) are always applied
relative to the core we landed on (or the leg we landed on).
The change wing is relative to this target; the subject of the
replacement (`+(pre)`) is the original subject.
So, in English, we compute the `dec` arm again, against a new
core with a new payload that contains an incremented `pre`.
And thus, we decrement. Doesn't seem so hard, does it?

261
pub/doc/hoon/tutorial/4-functions.md Normal file
View File

@ -0,0 +1,261 @@
# Hoon 4: toward actual functions
Okay, we've programmed. We've achieved decrement. We've written
what is in some sense a loop. What next?
Well... we're still feeling vaguely disappointed. Because we're
supposed to be doing *functional programming*. And we haven't
yet written any *functions*.
After all, in Hoon we don't really write a command-line utility
to decrement `42`. We write `(dec 42)`. You probably realize
that on the inside, this is not the same thing as a function in a
normal functional language. The Tasmanian tiger is not a tiger.
On the other hand, it certainly *looks* like a function call.
So how do we write the function?
In this chapter, we'll modify `+test` to extend the subject so
that we can write our result as `(dec arg)`. Or rather, `(duck
arg)`, because we want to get out of training wheels and stop
clearing the subject soon.
## Form of the solution
```
=< :- %say |= [* [[arg=@ud ~] ~]] :- %noun
(duck arg)
!! :: some interesting core
```
`!!`, or "zapzap" or `[%zpzp ~]`, can go anywhere a twig can and
always crashes. Because its span is the empty set (`%void`), it
doesn't cause type inference problems.
In place of the `!!`, we'll put a core, effectively a library,
that provides our new, improved decrement function `duck`. We'll
then call it with the irregular form, `(duck arg)`, which looks
like a function call but is in fact some mysterious macro.
## Some interesting core
Translated into imperative programming, what we did in chapter 3
was more like computing a function of a global variable. Now,
we have to actually pass an argument to a function.
Here's our first try:
```
=< :- %say |= [* [[arg=@ud ~] ~]] :- %noun
=+ gat=duck
=<(run gat(sam arg))
=> ~
|%
++ duck
=+ sam=0
=+ pre=0
|%
++ run
?: =(sam +(pre))
pre
run(pre +(pre))
--
--
~tasfyn-partyv:dojo/sandbox> +test 42
41
```
We step back and contemplate our handiwork. Is it good? Well...
it works. Reading programs written without syntactic sugar is
about as fun as eating raw chocolate nibs.
What did we do? In the `duck` arm (we often write `++duck`, for
obvious reasons) we produce a core whose payload is `[pre=0 num=0
~]`, and whose battery contains `++run`.
In the result twig, we first use `++duck` to extend our subject
with a core named `gat`. We then use `run` on that gate. Why do
we need this `gat`? Why can't we just write `=<(run duck(sam
arg))`?
Because the arm is computed *after* the mutation. But here we
need the mutated *result* of `++duck`. Instead, what this code
is doing is trying to mutate `sam` within the core that contains
`++duck`. Where it doesn't exist, so your code won't compile.
And note that with `=<`, we've placed our library structurally
between the original subject and the program we're writing,
but lexically at the bottom with zero left margin. We also
clear the subject to keep things simple.
## A more regular structure
It actually gets worse. To make this code look simpler, we need
to make it more complex. While "function calls" actually fit
quite well into the Hoon architecture, they're also a nontrivial
synthetic construction. We'll build the desugared form the hard
way, then show you where we put the sugar in.
The desugared canonical decrement:
```
=< :- %say |= [* [[arg=@ud ~] ~]] :- %noun
=+ gat=duck
=<(run gat(sam arg))
=> ~
|%
++ duck
=+ sam=0
|%
++ run
=+ pre=0
=< loop
|%
++ loop
?: =(sam +(pre))
pre
loop(pre +(pre))
--
--
--
~tasfyn-partyv:dojo/sandbox> +test 42
41
```
Yuck. Okay, let's fix this.
## Art of the loop
First, look at our little `++loop`. It works just like our old
`++run` loop. We notice that there's actually something nice
about it: we don't use the symbol `loop` anywhere outside these 7
lines of code. It's not exported at all.
Actually, the symbol `loop` name is useless and redundant.
Making up names is one of the hard problems in computer science,
so why solve it? For just this reason, Hoon has an *empty name*,
which as a constant is a zero-length symbol (`%$` instead of
`%foo`), and as a limb is the `buc` symbol (`$`). With `$`,
our loop becomes:
```
=< $
|%
++ $
?: =(sam +(pre))
pre
$(sam +(run))
--
```
This may not seem like a huge improvement. It's not. But it's
exactly equivalent to the synthetic rune `|-`, "bardas":
```
|- ?: =(sam +(pre))
pre
$(pre +(pre))
```
This is obviously the canonical Hoon loop. It leaves us with
```
=< :- %say |= [* [[arg=@ud ~] ~]] :- %noun
=+ gat=duck
=<(run gat(sam arg))
=> ~
|%
++ duck
=+ sam=0
|%
++ run
=+ pre=0
|- ?: =(sam +(pre))
pre
$(pre +(pre))
--
--
~tasfyn-partyv:dojo/sandbox> +test 42
41
```
## Is this a lambda?
Could we use `$` for `++run`? It certainly sounds like the same
kind of thing as `++loop` -- just a word we invented to mean "do
it." Should the programmer have to invent these kinds of words?
```
=< :- %say |= [* [[arg=@ud ~] ~]] :- %noun
=+ gat=duck
=<($ gat(sam arg))
=> ~
|%
++ duck
=| sam=@ud
|%
=+ pre=0
++ $
|- ?: =(sam +(pre))
pre
$(pre +(pre))
--
--
~tasfyn-partyv:dojo/sandbox> +test 42
41
```
(Besides `run` to `$`, we changed `=+ sam=0` to `=| sam=@ud`.
Let's just remember that there's some magic here. We'll come
back and explain it later.)
This is still kind of ugly -- but it's exactly equivalent to
```
=< :- %say |= [* [[arg=@ud ~] ~]] :- %noun
=+ gat=duck
=<($ gat(sam arg))
=> ~
|%
++ duck
|= sam=@ud
=+ pre=0
|- ?: =(sam +(pre))
pre
$(pre +(pre))
--
~tasfyn-partyv:dojo/sandbox> +test 42
41
```
Doesn't that look like a function? Indeed, we're done with
`++duck` -- that's what a Hoon decrement should look like.
If you squint a little, `|=` ("bartis") might even be a strange,
deformed lambda rune.
Since it's doing something simple, we might well even compress
the whole body of the function into one wide-form line:
```
=+(pre=0 |-(?:(=(sam +(pre)) pre $(pre +(pre)))))
```
(According, of course, to taste -- this is a bit tight for some.)
## Gates and how to call them
Our call site remains a disaster, though. We'll need moar sugar.
But first, let's look at this lambda-thing we've made. What is
the noun produced by `++duck`? Our term for it is a "gate," but
nobody will hate you for saying "function." And while we "slam"
our gates, you can feel free to just "call" them.
A gate is a core, of course, but a special kind of core. All
cores are shaped like `[battery payload]`. A gate is shaped like
`[formula [sample context]]`. A gate has one arm, `$`, so its
battery is just a formula. To slam a gate, you replace its
sample (`+6` or `+<`, "luslit" or "lust") with your own noun,
and apply the formula to the mutated gate.
As we explained earlier, `duck(sam arg)` is not the right way to
mutate the gate we make with `duck`, because it's actually
trying to mutate the core we used to make `duck`. But there has
to be some sugar to do this, and there is: `%*`, "centar". We
can replace our call site with `%*($ duck sam arg)`.
This is also not quite orthodox, because the whole point of a
gate is the canonical shape that defines a calling convention.
We can and should say: `%*($ duck +< arg)`.
Unsurprisingly, this in turn is `%-(duck arg)` in regular form,
or `(duck arg)`

8
pub/doc/reference.md → pub/doc/interpreter.mdy
View File

@ -1,9 +1,13 @@
---
sort: 3
---
<div class="short">
References
Interpreter
==========
These references cover terminology and our interpreter, `vere`.
The urbit interpreter and C code.
</div>

0
pub/doc/reference/glossary.md → pub/doc/interpreter/glossary.md
View File

0
pub/doc/reference/u3.md → pub/doc/interpreter/u3.md
View File

0
pub/doc/reference/vere.md → pub/doc/interpreter/vere.md
View File

4
pub/doc/nock.md → pub/doc/nock.mdy
View File

@ -1,3 +1,7 @@
---
sort: 0
---
<div class="short">
nock

14
pub/doc/talk.md
View File

@ -1,14 +0,0 @@
<div class="short">
talk
====
talk is our messaging application.
talk is in dire need of better documentation
</div>
------------------------------------------------------------------------
This document should include <a href="./talk/help">the command reference</a> somehow.

24
pub/doc/talk/help.txt
View File

@ -1,24 +0,0 @@
Besides `;help`, there are four main `talk` commands:
;join ~urbit-name/channel
`;join` subscribes your main feed to a remote channel.
;create channel %name 'description'
`;create` creates a channel on your urbit.
;<number>
`;<number>` activates a previous message number, like a URL that got
clipped.
;<target>
`;<target>` sets the target for your messages, such as `;~urbit-name`
for a private message, or `;/channel`
;
By itself is "autotarget", and maintains the audience of the last message
heard.

10
pub/doc/tools.mdy Normal file
View File

@ -0,0 +1,10 @@
---
sort: 4
---
tools
====
User-level tools and utilities.
<list></list>

207
pub/doc/tools/clay.md Normal file
View File

@ -0,0 +1,207 @@
`%clay`
========
## Paths
### Structure
Urbit paths have a very specific structure. First, since the clay
filesystem has a global namespace, the first element in any path
is the particular urbit whose filesystem you are trying to
access.
The second element specifies which desk you wish to access on
that urbit. Desks are independent branches (in the
revision-control sense) of their filesystem.
The third element specifies the revision number for that
desk. The remainder of the path is the path to the file.
Thus, a path in clay is:
`/urbit/desk/revision/path`.
For example, to get revision 5 of `/try/readme/md` off the `home`
desk on `~sampel-sipnym`, use:
`/~sampel-sipnym/home/5/try/readme/md`.
### Shortcuts
`%` refers to the current working
directory. `%%` refers to our parent, `%%%` refers to our
grandparent, and so forth.
For example:
XX TBD
From the other direction, inserting a `=` into a path copies the
corresponding element from the current path into the path that
you're trying to access.
For example, if the current path is referencing our ship at the
current time, to reference `/try/readme`, use:
`/===try/readme`.
### Accessing commits
There are three ways to refer to particular commits in the
revision history. First, one can use the revision number.
Second, one can use any absolute time between the one numbered
commit and the next (inclusive of the first, exclusive of the
second). Thirdly, every desk has a map of labels to revision
numbers. These labels may be used to refer to specific commits.
## `ls`
`+ls /path` gives a directory listing at a path
## `cat`
`+cat /path`
prints out the file at the given path.
## `mount`
It's often useful to "mount" the clay filesystem to unix, so that
you can interact with it with the traditional unix tools. The
syntax to do this is as follows:
|mount /path [%mount-point]
This mirrors the desk out to unix in at the path
`<pier-directory> <mount-point>`. If you don't supply a
`%mount-point`, we use the last element in the path. Thus, if
you mount `%/pub/doc`, it'll by default put it in `doc`.
*The mount point is monitored Dropbox-style, so every change you
make to the file in unix is automatically commited to clay.*
You can unmount by specifying either the path or the mount point.
|unmount /path
|unmount %mount-point
## `merge`
Often, it's useful to be able to merge a desk into another desk.
The other desk does not, of course, need to be on the same urbit:
for example, the standard way to distribute an app is to put it
on a desk and let other people merge it into their own urbit.
The syntax is as follows:
|merge %to-desk ~from-urbit %from-desk [%strategy]
There are seven different merge strategies. Throughout our
discussion, we'll say that the merge is from Alice's desk to
Bob's.
### Native strategies
A `%init` merge should be used iff it's the first commit to a
desk. The head of Alice's desk is used as the number 1 commit to
Bob's desk. Obviously, the ancestry remains intact when
traversing the parentage of the commit, even though previous
commits are not numbered for Bob's desk.
A `%this` merge means to keep what's in Bob's desk, but join the
ancestry. Thus, the new commit has the head of each desk as
parents, but the data is exactly what's in Bob's desk. For those
following along in git, this is the 'ours' merge strategy, not
the '--ours' option to the 'recursive' merge strategy. In other
words, even if Alice makes a change that does not conflict with
Bob, we throw it away.
A `%that` merge means to take what's in Alice's desk, but join
the ancestry. This is the reverse of `%this`.
A `%fine` merge is a "fast-forward" merge. This succeeds iff one
head is in the ancestry of the other. In this case, we use the
descendant as our new head.
For `%meet`, `%mate`, and `%meld` merges, we first find the most
recent common ancestor to use as our merge base. If we have no
common ancestors, then we fail. If we have multiple most
recent common ancestors, then we have a criss-cross situation,
which should be handled delicately. At present, we don't handle
this kind of situation, but something akin to git's 'recursive'
strategy should be implemented in the future.
There's a functional inclusion ordering on `%fine`, `%meet`,
`%mate`, and `%meld` such that if an earlier strategy would have
succeeded, then every later strategy will produce the same
result. Put another way, every earlier strategy is the same as
every later strategy except with a restricted domain.
A `%meet` merge only succeeds if the changes from the merge base
to Alice's head (hereafter, "Alice's changes") are in different
files than Bob's changes. In this case, the parents are both
Alice's and Bob's heads, and the data is the merge base plus
Alice's changed files plus Bob's changed files.
A `%mate` merge attempts to merge changes to the same file when
both Alice and Bob change it. If the merge is clean, we use it;
otherwise, we fail. A merge between different types of changes --
for example, deleting a file vs changing it -- is always a
conflict. If we succeed, the parents are both Alice's and Bob's
heads, and the data is the merge base plus Alice's changed files
plus Bob's changed files plus the merged files.
A `%meld` merge will succeed even if there are conflicts. If
there are conflicts in a file, then we use the merge base's
version of that file, and we produce a set of files with
conflicts. The parents are both Alice's and Bob's heads, and the
data is the merge base plus Alice's changed files plus Bob's
changed files plus the successfully merged files plus the merge
base's version of the conflicting files.
### Metastrategies
There's also a meta-strategy `%auto`, which is the most common.
If no strategy is supplied, then `%auto` is assumed. `%auto`
checks to see if Bob's desk exists, and if it doesn't we use a
`%init` merge. Otherwise, we progressively try `%fine`,
`%meet`, and `%mate` until one succeeds.
If none succeed, we merge Bob's desk into a scratch desk. Then,
we merge Alice's desk into the scratch desk with the `%meld`
option to force the merge. For each file in the produced set of
conflicting files, we call the `++mash` function for the
appropriate mark, which annotates the conflicts if we know how.
Finally, we display a message to the user informing them of the
scratch desk's existence, which files have annotated conflicts,
and which files have unannotated conflicts. When the user has
resolved the conflicts, they can merge the scratch desk back into
Bob's desk. This will be a `%fine` merge since Bob's head is in
the ancestry of the scratch desk.
## Autosync
Since clay is reactive, it's possible for changes to the
filesystem to cause various actions. An important use of this is
in enabling "autosync". When a desk is synced to another, any
changes to the first desk are automatically applied to the
second.
This isn't simply mirroring, since the local desk might have
changes of its own. We use the full merge capabilities of clay
to try to make the merge clean. If there are conflicts, it'll
notify you and let you resolve them.
There can be complex sync flows, some of which are useful.
Often, many urbits will be synced to some upstream desk that is
trusted to provide updates. Sometimes, it's useful to sync two
desks to each other, so that changes to one or the other are
mirrored.
The syntax for syncing and unsyncing desks is as follows:
|sync %to-desk ~from-urbit %from-desk
|unsync %to-desk ~from-urbit %from-desk

548
pub/doc/tools/dojo.md Normal file
View File

@ -0,0 +1,548 @@
# `:dojo`
The dojo is a typed functional shell. Its prompt is:
~urbit-name:dojo>
### Quickstart
To print a Hoon expression or other recipe:
~urbit-name:dojo> (add 2 2)
To save a recipe as a variable `foo`:
~urbit-name:dojo> =foo (add 2 2)
To save as a unix file (`$pier/.urb/put/foo/bar.baz`):
~urbit-name:dojo> .foo/bar/baz (add 2 2)
To save as an urbit file (`/===/foo/bar/baz`):
~urbit-name:dojo> *foo/bar/baz (add 2 2)
A noun generator with ordered and named arguments:
~urbit-name:dojo> +make one two three, =foo (add 2 2), =bar 42
A poke message to an urbit daemon:
~urbit-name:dojo> :~urbit-name/talk (add 2 2)
A system command to `:hood`:
~urbit-name:dojo> |reload %vane
### Manual
An Urbit value is called a "noun." A noun is either an unsigned
integer ("atom") or an ordered pair of nouns ("cell"). Nouns
are just values, with no cyclic structure or pointer identity.
The dojo is your safe space for hand-to-hand combat with nouns.
Every dojo command builds a "product" noun functionally, then
applies this product in a side effect -- show, save, or send.
#### Theory
The dojo is not just a Hoon interpreter. Hoon is a purely
functional language; dojo recipes are *conceptually* functional,
but they often use concrete actions or interactions. A simple
Hoon expression is only one kind of recipe.
A recipe can get data from an HTTP GET request or an interactive
input dialog. It can also query, even block on, the Urbit
namespace. These operations are *conceptually* functional, but
not *actually* functional. They don't belong in a pure Hoon
expression, but they do belong in a dojo recipe. A recipe is "FP
in the large," more like Unix pipes than Haskell monads.
The dojo is "single-threaded" in each session. One session can
work on one command at a time. The session does not accept user
input while processing a command, even when it blocks over the
network. And each session's state is independent. (If you want
to work on two things at a time, connect two console sessions to
your dojo.)
Once you've built your product noun, you show, save, or send it.
You can pretty-print the product to the console. You can save it
-- as a dojo variable, as a revision to the Urbit filesystem, or
as an export to a file in the Unix filesystem. Or you can
send it -- staying native with an Urbit poke, or going retro
with an HTTP PUT/POST.
All these operations are typed. Hoon is a statically typed
language, but the dojo is a dynamic interpreter. The nouns you
build in the dojo are dynamically typed nouns, or "cages".
A cage actually has two layers of type: "mark," a network label
(like a MIME type), and "range," a Hoon language type. When a
cage is sent across the Urbit network, the receiving daemon
validates the noun against its own version of the mark, and
regenerates the range.
Of course, sometimes a recipe produces a noun with mark `%noun`,
meaning "any noun," and range `*`, the set of all nouns. We have
no choice but to do the best we can with mystery nouns, but we
prefer a formal description.
Marks let us perform a variety of formal typed operations on
nouns: validation of untrusted data, format conversion, even
patch and diff for revision control.
#### Other resources
An excellent way to understand `:dojo` is to read the source,
which is in `/===/ape/dojo/hoon`.
Unfortunately, you may or may not know Hoon. We'll use some Hoon
snippets here for defining structures and grammars. Just think
of it as pseudocode -- the meaning should be clear from context.
#### Syntax and semantics
To use the dojo, type a complete command at the dojo prompt.
The simplest command just prints a Hoon expression:
~urbit-name:dojo> (add 2 2)
Hit return. You'll see:
> (add 2 2)
4
~urbit-name:dojo>
Similarly in tall form,
~urbit-name:dojo> %+ add 2 2
> %+ add 2 2
4
~urbit-name:dojo>
An incomplete command goes into a multiline input buffer. Use
the up-arrow (see the console history section) to get the last
command back, edit it so it's just `%+ add 2`, and press return.
You'll see:
> %+ add 2
~urbit-name/dojo<
Enter `2`. You'll see:
> %+ add 2
2
4
~urbit-name/dojo>
The full command that parses and runs is the concatenation of all
the partial lines, with a space inserted between them. To clear
all multiline input, just hit return on an empty prompt.
##### Command structure
Every finished line is parsed into one `++dojo-command`:
++ dojo-command ::
$% [%edit p=path q=dojo-recipe] :: modify clay file
[%http p=? q=purl r=dojo-recipe] :: http post or put
[%poke p=goal q=dojo-recipe] :: send request
[%save p=path q=dojo-recipe] :: replace clay file
[%show p=dojo-recipe] :: print to console
[%unix p=path q=dojo-recipe] :: export to unix
[%verb p=term q=dojo-recipe] :: store variable
== ::
Each kind of `++dojo-command` is an action that depends on one
noun thproduction, a `++dojo-recipe`. We describe first the
commands, then the recipes.
---
###### `[%show p=dojo-recipe]`
To print the product, the command is just the recipe:
~urbit-name:dojo> (add 2 2)
---
###### `[%verb p=term q=dojo-recipe]`
To save the product to a variable `foo`:
~urbit-name:dojo> =foo (add 2 2)
`foo` goes into your Hoon subject (scope) and is available to all
expressions.
To unbind `foo`:
~urbit-name:dojo> =foo
The dojo has a set of special variables, some read-write and some
read-only: `dir`, `lib`, `arc`, `now`, `our`.
The read-write specials are `dir`, `lib` and `arc`. `dir` is the beak
(revision-control branch) and directory this session is operating in,
and normally accessed/set with `%`. `lib` is a set of libraries, and
`arc` a set of structures, to put in the Hoon subject.
Read-only specials are `now`, the current (128-bit `@da`) time,
and `our`, the current urbit.
---
###### `[%edit p=path q=dojo-recipe]`
###### `[%save p=path q=dojo-recipe]`
The product is either a new version of, or a modification to,
the Urbit file at the given path. (See the discussion of Urbit
filesystem paths.)
To save:
~urbit-name:dojo> *%/numbers/four (add 2 2)
To edit:
~urbit-name:dojo> -%/numbers/four (add 2 2)
A save (`*`) overwrites the current (if any) version of the file
with a new version of any mark. The save command above will work
(if you want `/numbers/four` at your current path).
An edit (`-`) produces a diff whose mark has to match the diff
mark for the current version of the file. The edit command above
will not work, because evaluating a Hoon expression like `(add 2
2)` just produces a `%noun` mark, ie, an arbitrary noun.
For either saves or edits, the current version of the file must
be the same version specified in the write -- in other words,
we can only write to HEAD. If someone else has sneaked in a
change since the version specified, the command will fail.
---
###### `[%unix p=path q=dojo-recipe]`
~urbit-name:dojo> ./numbers/four (add 2 2)
The product is saved as a Unix file (its mark is translated
to MIME, and the MIME type is mapped as the extension).
---
###### `[%poke p=goal q=dojo-recipe]`
A poke is a one-way transactional request. It either succeeds
and returns no information, or fails and produces an error dump.
Every poke is sent to one daemon on one urbit. The default urbit
is your urbit. The default daemon is the system daemon, `:hood`.
The following syntactic forms are equivalent:
~urbit-name:dojo> :~urbit-name/hood (add 2 2)
~urbit-name:dojo> :hood (add 2 2)
~urbit-name:dojo> :~urbit-name (add 2 2)
~urbit-name:dojo> : (add 2 2)
Urbit pokes do not have a separate verb. The mark of the message
defines the semantics of the operation. You don't call a method
`foo` whose argument is a noun in mark `bar` -- you poke a noun
in mark `bar`. The mark is the protocol is the method.
If the poke succeeds, you'll see an `>=` line. If not, you'll
see an error report, typically with a stack trace.
It's common (but not necessary) to use a custom generator for the
daemon you're talking to. (For generators, see below.) Hence
~urbit-name:dojo> :~urbit-name/fish +fish/catch (add 2 2)
It's irritating to type "fish" twice, just because we're using a
fish generator to talk to a fish daemon. Hence a shortcut:
~urbit-name:dojo> :~urbit-name/fish|catch (add 2 2)
If we combine all these defaults, we get the "system command"
shortcut:
~urbit-name:dojo> :~urbit-name/hood +hood/reload %ames
~urbit-name:dojo> |reload %ames
This is the most common poke, a generated message to your own
hood.
---
##### `[%http p=? q=purl r=dojo-recipe]`
The Web has its own poke, unfortunately in two flavors. To POST,
~urbit-name:dojo> +http://website.com (add 2 2)
To PUT:
~urbit-name:dojo> -http://website.com (add 2 2)
As with a poke, you'll get a >= for success, or an error report.
---
##### Recipes, models and filters
But wait, what's a recipe? Simplifying the actual code slightly:
++ dojo-recipe :: functional build
$% [%ex p=twig] :: hoon expression
[%as p=mark q=dojo-recipe] :: conversion
[%do p=twig q=dojo-recipe] :: apply gate
[%ge p=dojo-script] :: generator
[%ur p=purl] :: get url
[%tu p=(list dojo-recipe)] :: tuple
== ::
++ dojo-script :: script
$: p=path :: core recipe
q=dojo-config :: configuration
== ::
++ dojo-config :: configuration
$: p=(list dojo-recipe) :: by order
q=(map term (unit dojo-recipe)) :: by keyword
== ::
---
###### `[%ex p=twig]`
The twig in an `%ex` recipe is a Hoon expression. The recipe
syntax is just the Hoon syntax.
The subject of the twig is a core stack: first the Hoon kernel,
then the Arvo standard library, then the structures and libraries
in `lib` and `arc`. On the very top are the dojo variables.
A twig produces the trivial mark `%noun`, except in two cases
where the dojo can do better. The dojo analyzes the twig to
detect two trivial cases where direct evaluation gives us a mark:
a variable reference like `foo` that matches a dojo variable, or
an urbitspace dereference like `.^(/cx/~urbit-name/main/1/foo)`.
---
###### `[%tu p=(list dojo-recipe)]`
A is just a tuple of recipes, using the normal Hoon syntax for
a tuple. `[a]` is `a`, `[a b]` the cell `[a b]`, `[a b c]` the
cell `[a [b c]]`.
A tuple, unless it's a trivial 1-tuple, is always marked `%noun`.
---
###### `[%ge p=dojo-script]`
A `%ge` is a generator, a configurable script loaded from the
filesystem.
The script recipe `++dojo-script` specifies a script path, a list
of ordered arguments, and a list of keyword arguments. All the
arguments are recipes. The path specifies a Hoon source file in
`/===/gen/[path]`.
For the path `/fun/make`, the ordered arguments `1`, `2` and `3`,
and the named arguments `foo` and `bar`, the syntax is:
~urbit-name:dojo> +fun/make 1 2 3, =foo (add 2 2), =bar 42
Unless this non-closed form is the end of a command, it needs to
be surrounded by `[]` to make it play well with others.
Generator programming is covered in the dojo developer's guide.
The user doesn't need to know or notice how the generator gets
its input (if any), except in one case: a dialog.
A dialog generator will take over the prompt and ask you
questions. If this seems terrifying, ^D will abort the dialog,
the recipe, and the command, and take you back to the dojo.
---
###### `[%as p=mark q=dojo-recipe]`
`%as` is a mark conversion. Since the input to it is another
recipe, we can chain them to make a conversion pipeline.
To convert a recipe, just precede it with the converison form, `&mark`:
~urbit-name:dojo> &noun (add 2 2)
~urbit-name:dojo> &md (add 50 7)
---
###### `[%do p=twig q=dojo-recipe]`
`%do` is a Hoon functino (gate) application. It can also be in a pipeline.
Its syntax is a hoon expression preceeded by `_`:
~urbit-name:dojo> _lore 'hello\0aworld'
~urbit-name:dojo> _|=(a=@ (mul 3 a))} (add 2 2)
---
###### `[%ur p=purl]`
A simple HTTP get produces the result as a `%httr` noun.
---
### Development
Developing dojo generators is the easiest form of Hoon programming.
Generator scripts are found in the `gen` folder.
#### Configuration
All generator scripts are configured with the same configuration gate:
|= $: [now=@da eny=@ bec=beak]
[arg=my-arguments opt=my-options]
==
We try to minimize boilerplate, but you can't get out of this
one. The dojo will slam this configuration gate to create your
generator.
The head of the sample is a system context. `now` is the date of
the call; `eny` is 256 bits of entropy; `bec` is a triple
`[p=ship q=desk r=case]` (ie, the root of a filesystem path).
This beak is the path to the script, not the current path within
the dojo (dojo variables are not, unlike in Unix, visible to
generator scripts).
`arg` and `opt` are whatever you want them to be. (Use `~` if
you have no arguments or options.) The dojo will replace `arg`
with the user's ordered arguments, and replace any options in
`opt` specified by the user's named arguments. (More exactly,
if the user specifies `=foo 42`, your `opt` is replaced with
`opt(foo 42)`.)
Bear in mind that dojo syntax is list-centric, so your `arg` will
always end with a `~`. For instance,
~urbit-name/dojo> +fun/make 1 2 3
will generate an `arg` of `[1 2 3 ~]`. Yes, this is the only
place in Urbit where we do list-centric arguments.
Note also that script configuration is typed. The user's command
will fail if there's a type mismatch. But `arg` does not have to
be a homogeneous list -- just a tuple with `~` on the end. Also,
you can use `arg=*` and sort out the nouns by hand.
You can also use `*` anywhere if you're not interested in the
system context, or in
#### Generators
There are three kinds of generators: builders (with no special
I/O), dialogs (which read console input), and scrapers (which
pull data from the webs). Any generator can use `.^` to both
read from and block (wait for remote or delayed results) on
the Urbit global namespace.
A generator produces a cell whose tail is the configuration gate,
and whose head is either `%say` for a builder, `%ask` for a
dialog, or `%get` for a scraper.
(If you want to write one generator which both prompts the user
and scrapes the web, don't. Write two, and configure the second
with the result of the first. We pay a price for keeping things
stupid.)
##### Builders
A builder just produces a cask (mark-value cell) directly from
the configuration gate. Here's the simplest builder, with a
blank configuration:
:- %say |= *
:- %noun
"hello, world."
##### Dialogs
A dialog is a console input form. We recommend using the helpful
`sole` structures, with
/- *sole
(If you're interested in building your own dialogs without `sole`
(not that complicated at all), it's easiest to start by
reverse-engineering `sole`.)
Otherwise, a dialog boilerplate (with blank configuration), which
generates a `my-result` result with mark `%my-result-mark`:
:- %ask |= *
^- (sole-result (cask my-result))
%+ sole-so %my-result-mark
*my-result
Internally, a `++sole-result` is either a final result or a new
dialog core with a new prompt. The dojo keeps running the dialog
until it produces a final result.
A dialog step can do one of three things: print a message, prompt
for a value, or finish with a result. These are done with
`sole-yo`, `sole-lo`, and `sole-so` respectively. Here's a
simple dialog which uses all of them:
:- %ask |= *
^- (sole-result (cask ,@ud))
%+ sole-yo leaf/"let's multiply two numbers..."
%+ sole-lo [%& %number "number one: "]
%+ sole-go dim:ag
|= one=@ud
%+ sole-lo [%& %number "number two: "]
%+ sole-go dim:ag
|= two=@ud
%+ sole-so %noun
(mul one two)
`++sole-yo` prints a tank (prettyprint structure). See `++tank`
in hoon.hoon.
`++sole-lo` takes a prompt and a new dialog. In the example,
`[%& %number "your number: "]` is a `++sole-prompt`. `&` as
opposed to `|` means input is echoed (not a password).
`%number` is a history label; all inputs with the same label
share the same history buffer.
The `++sole-dialog` is generally built with `++sole-go`, as used
above. This takes a parsing `++rule` (here `dim:ag`, which
parses a decimal), and a gate whose sample is the parsed value,
producing a new dialog.
##### Scrapers
Most stuff on the internets is crap, but there's exceptions.
Sometimes it's nice to get it and compute functions on it.
A scraper is much like a dialog, except instead of `sole-lo` and
`sole-go` it uses `sole-at`.
:- %get |= *
%+ sole-yo leaf/"Fetching example.com"
%+ sole-at [[& ~ `/com/example] `/ ~]
|= hit=httr
%+ sole-yo leaf/"Fetched."
%+ sole-so %httr
hit
`++sole-at` takes a `purl` request url, and a gate through
which to slam the result `httr`.

287
pub/doc/tools/talk.md Normal file
View File

@ -0,0 +1,287 @@
# `:talk`
`:talk` is the Urbit appliance for chatter and notifications.
For less sophisticated users, Urbit *is* just `:talk`. If you
see `:talk` as "like Slack, but distributed," or "like IRC, but
persistent and encrypted," you're not completely wrong.
`:talk` is an unusual messenger in two ways. One: by default, it
multiplexes all content streams into a single flow. Most UI
researchers agree that context-switching is cognitively expensive
and leads to surfing the Internet. (`:talk` is also used for
your system notifications.)
Two: text lines are limited to 64 ASCII bytes, no uppercase.
This restriction is mobile-friendly and reduces the aesthetic
impact of low-quality content.
Messages in `:talk` are called "posts". Posts go to "stations,"
which are just like IRC or Slack channels. Any urbit can host or
subscribe to any number of stations.
`:talk` is not a text-only messenger; it's designed to support
arbitrary content in posts, from URLs to images to long-form
text. (Only URLs right now.) However, any message on `:talk`
has to be able to summarize itself in a 64-byte text line.
There are four kinds of station: a write-only "mailbox" for
direct messages, an invite-only "party" for private conversation,
a read-only "journal" for curated content, and a public-access
"board" for general use or abuse.
While there's obviously no central `:talk` server for all of
Urbit, and thus no such thing as a truly global station space,
active Urbit stars cooperate to federate, manage and mirror a
collectively-managed namespace, very like Usenet. These
"federal" stations are generally public-access boards.
### Quickstart
Let's post something! At the default `:talk` prompt
```
~tasfyn-partyv:talk:
```
type the message:
```
~tasfyn-partyv:talk: hello, world.
```
And hit return. Don't worry, no one but you will see this. The
`:` means you're posting to yourself. You'll get the post:
```
~tasfyn-partyv: hello, world.
~tasfyn-partyv:talk:
```
It's boring to post to yourself. Let's join a station:
```
~tasfyn-partyv: ;join /urbit-test
```
(`/urbit-test` is a federal station, meaning it's hosted by your
star (for `~tasfyn-partyv`, `~doznec`). The `/` notation is just
an abbreviation for `~doznec/urbit-test`.)
You'll see:
```
---------:talk| %porch subscribed to /urbit-test, called `>`
---------:talk| rules of /urbit-test:
---------:talk| test posts only. no shitposting. no pedos/nazis.
~doznec> ~tasfyn-partyv admitted to %urbit-test
~tasfyn-partyv:talk>
```
Notice the character assignment - stations you're subscribed to are
assigned [consistent ASCII glyphs](#-station-glyphs), which you'll
see in the log when you hear from these stations, and on the prompt
when you're talking to them.
Post a line to `/urbit-test`:
```
~tasfyn-partyv:talk> hello, world
```
You'll see, echoed back at you through `~doznec`:
```
~tasfyn-partyv:talk> hello, world
```
And of course, anyone else in `/urbit-test` will see it as well.
But you don't care about `/urbit-test`, so leave it:
```
~tasfyn-partyv:talk> ;leave
```
You'll see:
```
---------:talk| %porch has left /urbit-test, called `>`
```
Everyone else will see:
```
~doznec> ~tasfyn-partyv has left %urbit-test
```
Now you're ready to use `:talk` for real! List the federal
groups currently available with
```
~tasfyn-partyv:talk> ;list
```
For general discussion about Urbit, we recommend `/urbit-meta`.
### Basic usage
#### Input conventions
There are three kinds of inputs you can type at the `:talk`
prompt: lines, URLs, and commands.
A line is 64 bytes of ASCII lowercase and spaces. If the line
starts with '@', it's an action (IRC `/me`).
The `:talk` interface will let you keep typing past 64 bytes, but
insert a Unicode bullet-point character in an appropriate space
in your post, to show you the prospective linebreak. Your essay
will be posted in multiple lines.
A URL is any valid URL. A command is any line starting with `;`.
#### Source annotation
Any post in your flow is shown with its author, together with a
glyph that shows how the post reached you. A post can reach you
in one of three ways:
Any post you see reached you in one of three ways. Either it was
sent directly to just you; to you and others; or to a station you
subscribe to.
Posts to just you are `:`. Posts to you and others (a multiparty
conversation) are `*`, unless you've bound this conversation to a
glyph. Posts to a station use that station's glyph.
You can see a list of glyph bindings with `;what`. Write
`;what >` to see what station `>` is bound to, or
`;what /urbit-test` to see if `/urbit-test` has a binding.
#### Audience selection
Audience selection is important in a multiplexed communicator!
The audience is always shown in your prompt. If there's a glyph
for it, it's shown as the glyph:
```
~tasfyn-partyv:talk>
```
Otherwise, the audience is shown in parens:
```
~tasfyn-partyv:talk(~wictuc-folrex)
```
`:talk` works fairly hard to get the audience right and minimize
manual switching. But to manually set the audience, the command
is simply `;station` - eg, `;~wictuc-folrex` for a direct post;
`/urbit-test` or `~doznec/urbit-test` to post to a federal
station, `%mystation` to post to a station on your own ship.
For a station bound to a glyph, `;` then the glyph; eg, `;>`.
You can post a line and set the audience in one command, eg:
```
;~wictuc-folrex this is a private message
```
You can configure your audience in a number of ways, which are
applied in priority order. From strongest to weakest:
- if typing a post, the audience when you started typing.
- if you activated a post (see below), the post you activated.
- if you manually locked the audience (see above), that audience.
- audience of the last post received.
- audience of the last post sent.
You can clear any audience setting layer by moving your cursor to
the start of the line and pressing backspace (whether the line is
empty or not). Posting a line clears the typing and activation
configurations.
#### Post activation and numbering
Every post can summarize itself in 64 bytes. But some posts
contain more information, which is not displayed by default.
Displaying this "attachment" is an opt-in operation. In the
post, it's marked by an underscore `_`, instead of a space,
between source and content.
The conventional example is a URL. When you post a URL:
```
~tasfyn-partyv:talk> http://foobar.com/moo/baz
```
This will appear in the flow as:
```
~tasfyn-partyv>_foobar.com
```
meaning that `~tasfyn-partyv` posted a link to `foobar.com`,
on the station or conversation whose glyph is `>`.
The effect of activating a post depends on the post. For a link,
the full URL is shown and (system permitting) put into the OS's
clipboard, or even automatically navigated to. Even for a text
post, activating shows the full audience, for complex audiences.
Posts in your `:talk` flow are numbered; the numbers are printed
every five posts, as
```
----------[5955]
```
You can specify a post to activate in two ways: by absolute or
relative position. Absolute position is a direct history number:
```
;5955
```
If you use fewer digits than are in the current flow number, the
high digits are defaulted "deli style" - if the current number is
5955, typing `;3` means `;5953`, and `;140` means `;5140`. To
actually activate post `3`, write `;0003`.
A unary sequence of `;` characters looks backward from the
present. `;` activates the most recent post; `;;` the second
most recent; etc.
#### Nicknames
Sometimes you know your Urbit friends by other names, on or
offline. Use the `;nick` command to assign or look up
nicknames.
`;nick` with no arguments lists all nicknames; `;nick
~tasfyn-partyv` looks up a nickname; `;nick curtis` searches in
reverse; `;nick ~tasfyn-partyv curtis` creates a nickname.
All nicknames must be 14 characters or less, lowercase.
Of course, nicknames are strictly local - like the names on
entries in a phonebook. Sometimes in a post you want to mention
someone you know by a nickname. Just type `~curtis`, and `:talk`
will replace it magically with `~tasfyn-partyv` (or beep if no
`~curtis` is bound).
#### Presence
You'll see presence notifications when people enter or leave
stations you're subscribed to.
`;who` lists everyone in all your stations. `;who station`
lists everyone in that station.
#### Typing indicator
If one or more urbits in your audience is typing, `:talk`'s
presence system will detect it and change the prompt:
```
~tasfyn-partyv [~wictuc-folrex...]>
```
#### Creating and managing stations
To create your own mailbox, party, journal or board:
```
;create party %myfunparty
;create journal %serious-journal
;create board %bizarre-board
```
etc.
Every form of station has an exception list; to block
`~wictuc-folrex` from your default mailbox `%porch`,
```
;block %porch ~wictuc-folrex
```
To invite people to `%myfunparty`:
```
;invite %myfunparty ~wictuc-folrex, ~sondel-forsut
```
To ban from `%bizarre-board`:
```
;banish %bizarre-board ~wictuc-folrex
```
To appoint a coauthor of `%serious-journal`:
```
;author %serious-journal ~sondel-forsut
```
#### Station Glyphs
Station are assigned out of the list `:|}>`, then
randomly out of it and the sets `-+*.`, ``,=`'^\/``,
`$%&@`, and `{<[]()`, in decreasing order of probabilty.
Alphanumeric characters and `!#?;~_` are reserved.

50
pub/doc/tools/tree.md Normal file
View File

@ -0,0 +1,50 @@
# `:tree`
`:tree` is the web filesystem interface.
`:tree` is a single-page app that uses a backend in `/home/tree` to load contents from `%clay` as the user navigates around as `%json`. The frontend lives in `/home/pub/tree` and is a fairly straightforward [React](https://facebook.github.io/react/) / [Flux](https://facebook.github.io/flux/) app.
## Frontend
The frontend code for `:tree` can be found in `/home/pub/tree/src/`.
### CSS
The CSS is written in [Stylus](https://learnboost.github.io/stylus/). The main entry point is `main.styl` and can be compiled with `stylus main.styl` which should output a `main.css`
### JS
The JS is written in [CoffeeScript](http://coffeescript.org/) and packaged with [Browserify](http://browserify.org/). The main entry point is `main.coffee` and is compiled with `browserify -t coffeeify main.coffee > main.js`. You'll need to `npm install` first.
Each page is loaded as JSON and then rendered using React on the page. This allows us to write JSX in our markdown to implement simple components. Check out `/home/pub/tree/src/js/components` to see the component library.
You'll notice that some of these doc pages use things like `<list>` in the raw markdown files.
## JSON API
Async provides loading by schema
`{path name sein sibs next prev}` are all immediately accesible from the store
a `getPath` method, if present (defaulting to current url), is used to determine the query root node.
## JSON Internals
### `/[desk]/tree/{path}.json`
`tree/json.hook` accepts a query string schema `q` in light noun encoding
++ schema (dict ,[term $|(mark schema)])
++ dict |*(a=_,* $&([a (dict a)] a))
which is normalized and type-checked to a `query` list of
- `[%kids query]`, the only recursive value, which executes for all subpaths
XX descent is only currently supported to a single level as a performance optimization
- `[%name %t]`, the node name
- `[%path %t]`, the current path
- `[%snip %r]`, a snippet, extracted via `react-snip-json`
- `[%head %r]`, the first `<h1/>`, extracted via `react-head-json`
- `[%body %r]`, the `react-json` body
- `[%meta %j]`, json frontmatter per the `mdy` mark definition
The request types above are `%t` text, `%r` html-derived tree, and `%j`
arbitrary json; an example query, used by the main content renderer, is
`"q=body.r__kids_name.t"` (`body:'r' kids:{name:'t'}` )

34
pub/doc/tree.md
View File

@ -1,34 +0,0 @@
# Tree
`:tree` is the web filesystem interface.
# Data retrieval interface
Async provides loading by schema
`{path name sein sibs next prev}` are all immediately accesible from the store
a `getPath` method, if present (defaulting to current url), is used to determine the query root node.
# Internals
something something coffeescript
## `/[desk]/tree/{path}.json`
tree/json.hook accepts a query string schema `q` in light noun encoding
++ schema (dict ,[term $|(mark schema)])
++ dict |*(a=_,* $&([a (dict a)] a))
which is normalized and type-checked to a `query` list of
- `[%kids query]`, the only recursive value, which executes for all subpaths
XX descent is only currently supported to a single level as a performance optimization
- `[%name %t]`, the node name
- `[%path %t]`, the current path
- `[%snip %r]`, a snippet, extracted via `react-snip-json`
- `[%head %r]`, the first `<h1/>`, extracted via `react-head-json`
- `[%body %r]`, the `react-json` body
- `[%meta %j]`, json frontmatter per the `mdy` mark definition
The request types above are `%t` text, `%r` html-derived tree, and `%j`
arbitrary json; an example query, used by the main content renderer, is
`"q=body.r__kids_name.t"` (`body:'r' kids:{name:'t'}` )

9
pub/tree/src/js/components/ListComponent.coffee
View File

@ -37,12 +37,17 @@ module.exports = query {
elem = @props.kids[item]
href = window.tree.basepath path
parts = []
title = null
if elem.meta?.title
title =
gn: 'h1'
c: [elem.meta.title]
else title = elem.head
title ||= (h1 {},item)
if elem.head.c.length > 0
title = elem.head
if not title
title =
gn: 'h1'
c: [item]
parts.push title
unless @props.titlesOnly # redundant? this seems familiar
if @props.dataPreview

11
pub/tree/src/js/main.js
View File

@ -646,15 +646,22 @@ module.exports = query({
elem = this.props.kids[item];
href = window.tree.basepath(path);
parts = [];
title = null;
if ((ref4 = elem.meta) != null ? ref4.title : void 0) {
title = {
gn: 'h1',
c: [elem.meta.title]
};
} else {
}
if (elem.head.c.length > 0) {
title = elem.head;
}
title || (title = h1({}, item));
if (!title) {
title = {
gn: 'h1',
c: [item]
};
}
parts.push(title);
if (!this.props.titlesOnly) {
if (this.props.dataPreview) {