ilyakooo0/urbit
1
0
Fork 0
mirror of https://github.com/ilyakooo0/urbit.git synced 2024-12-04 20:54:21 +03:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
pier on do 2015-10-21 13:50:22 -04:00
commit 3d12bcb1f1
7 changed files with 166 additions and 152 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
pub/docs/dev.mdy
View File

@ -20,7 +20,7 @@ internals, but again it helps. But you need to know Hoon.
Don't worry, Don't worry,
Alas, the developer doc is still under construction. We'll have Alas, the developer doc is still under construction. We'll have
more soon, starting with Nock. more soon.
<list></list> <list></list>

26
pub/docs/theory/whitepaper.mdy
View File

@ -1,12 +1,12 @@
--- ---
title: Urbit Whitepaper title: Urbit whitepaper
sort: 0 sort: 0
--- ---
Urbit: an operating function Urbit: an operating function
============================ ============================
<div class="warning">This is Urbit whitepaper DRAFT 41K. Some small details <div class="warning">This is Urbit whitepaper DRAFT 40K. Some small details
remain at variance with the codebase.</div> remain at variance with the codebase.</div>
Abstract Abstract
@ -1049,17 +1049,17 @@ is easier than it looks.
Languages do need to be read out loud, and the conventional names Languages do need to be read out loud, and the conventional names
for punctuation are clumsy. So Hoon replaces them: for punctuation are clumsy. So Hoon replaces them:
ace [1 space] dot . pan ] ace [1 space] gal < pel (
bar | fas / pel ) bar | gap [>1 space, nl] per )
bis \ gap [>1 space, nl] pid } bas \ gar > sel [
buc $ hax # ran > buc $ hax # sem ;
cab _ ket ^ rep ' cab _ hep - ser ]
cen % lep ( sac ; cen % kel { soq '
col : lit < tar * col : ker } tar *
com , lus + tec ` com , ket ^ tec `
das - mat @ tis = doq " lus + tis =
den " med & wut ? dot . pam & wut ?
dip { nap [ zap ! fas / pat @ zap !
For example, `%=` sounds like "centis" rather than "percent For example, `%=` sounds like "centis" rather than "percent
equals." Since even a silent reader will subvocalize, the length equals." Since even a silent reader will subvocalize, the length

2
pub/docs/user.mdy
View File

@ -17,7 +17,7 @@ For power users, the [appliance handbook](appliance) explains
your apps and how to control them. The [filesystem handbook](clay) your apps and how to control them. The [filesystem handbook](clay)
explains the Urbit filesystem and how to sync it with Unix. explains the Urbit filesystem and how to sync it with Unix.
Finally, the [:dojo manual](dojo) and [:talk manual](talk) Finally, the [:dojo manual](dojo) and [:talk manual](talk)
reveal the fine points of our shell and messenger respectively. explore the fine points of our shell and messenger respectively.
<list dataSort="true"></list> <list dataSort="true"></list>

162
pub/docs/user/dojo.mdy
View File

@ -5,39 +5,42 @@ sort: 8
# `:dojo` manual # `:dojo` manual
The dojo is a typed functional shell. Its prompt is: The dojo is a typed functional shell. Assuming our default
plot `~fintud-macrep`,
~urbit-name:dojo> Its prompt is:
~fintud-macrep:dojo>
## Quickstart ## Quickstart
To print a Hoon expression or other recipe: To print a Hoon expression or other recipe:
~urbit-name:dojo> (add 2 2) ~fintud-macrep:dojo> (add 2 2)
To save a recipe as a variable `foo`: To save a recipe as a variable `foo`:
~urbit-name:dojo> =foo (add 2 2) ~fintud-macrep:dojo> =foo (add 2 2)
To save as a unix file (`$pier/.urb/put/foo/bar.baz`): To save as a unix file (`$pier/.urb/put/foo/bar.baz`):
~urbit-name:dojo> .foo/bar/baz (add 2 2) ~fintud-macrep:dojo> .foo/bar/baz (add 2 2)
To save as an urbit file (`/===/foo/bar/baz`): To save as an urbit file (`/===/foo/bar/baz`):
~urbit-name:dojo> *foo/bar/baz (add 2 2) ~fintud-macrep:dojo> *foo/bar/baz (add 2 2)
A noun generator with ordered and named arguments: A noun generator with ordered and named arguments:
~urbit-name:dojo> +make one two three, =foo (add 2 2), =bar 42 ~fintud-macrep:dojo> +make one two three, =foo (add 2 2), =bar 42
A poke message to an urbit daemon: A poke message to an urbit daemon:
~urbit-name:dojo> :~urbit-name/talk (add 2 2) ~fintud-macrep:dojo> :~fintud-macrep/talk (add 2 2)
A system command to `:hood`: A system command to `:hood`:
~urbit-name:dojo> |reload %vane ~fintud-macrep:dojo> |reload %vane
## Manual ## Manual
@ -51,10 +54,18 @@ applies this product in a side effect -- show, save, or send.
### Theory ### Theory
The dojo is not just a Hoon interpreter. Hoon is a purely In the quickstart we learned a crude interpretation of the dojo
functional language; dojo recipes are *conceptually* functional, in terms of "expressions, generators and operations." While
but they often use concrete actions or interactions. A simple nothing in the quickstart section is inaccurate, it's not the way
Hoon expression is only one kind of recipe. the system works internally.
*All* dojo lines are commands. An operation uses a *recipe*
to create a noun, which the command uses in its side effect.
Just printing the noun is a trivial case of a command.
Recipes are *conceptually* functional, but often use concrete,
stateful action sequences. A simple Hoon expression (*twig*) is
purely functional, but it's only one kind of recipe.
A recipe can get data from an HTTP GET request or an interactive A recipe can get data from an HTTP GET request or an interactive
input dialog. It can also query, even block on, the Urbit input dialog. It can also query, even block on, the Urbit
@ -70,7 +81,8 @@ network. And each session's state is independent. (If you want
to work on two things at a time, connect two console sessions to to work on two things at a time, connect two console sessions to
your dojo.) your dojo.)
Once you've built your product noun, you show, save, or send it. Once you've built the product of your recipe, you show, save,
or send it.
You can pretty-print the product to the console. You can save 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 a dojo variable, as a revision to the Urbit filesystem, or
@ -83,19 +95,19 @@ language, but the dojo is a dynamic interpreter. The nouns you
build in the dojo are dynamically typed nouns, or "cages". build in the dojo are dynamically typed nouns, or "cages".
A cage actually has two layers of type: "mark," a network label A cage actually has two layers of type: "mark," a network label
(like a MIME type), and "range," a Hoon language type. When a (like a MIME type), and "span," a Hoon language type. When a
cage is sent across the Urbit network, the receiving daemon cage is sent across the Urbit network, the receiving daemon
validates the noun against its own version of the mark, and validates the noun against its own version of the mark, and
regenerates the range. regenerates the span.
Of course, sometimes a recipe produces a noun with mark `%noun`, Of course, sometimes a recipe produces a noun with mark `%noun`,
meaning "any noun," and range `*`, the set of all nouns. We have meaning "any noun," and span `*`, the set of all nouns. We have
no choice but to do the best we can with mystery nouns, but we no choice but to do the best we can with mystery nouns, but we
prefer a formal description. prefer a formal description.
Marks let us perform a variety of formal typed operations on A mark is also called a "format." Marks let us perform a variety
nouns: validation of untrusted data, format conversion, even of formal typed operations on nouns: validation, translation,
patch and diff for revision control. even patch and diff for revision control.
### Other resources ### Other resources
@ -111,20 +123,20 @@ of it as pseudocode -- the meaning should be clear from context.
To use the dojo, type a complete command at the dojo prompt. To use the dojo, type a complete command at the dojo prompt.
The simplest command just prints a Hoon expression: The simplest command just prints a Hoon expression:
~urbit-name:dojo> (add 2 2) ~fintud-macrep:dojo> (add 2 2)
Hit return. You'll see: Hit return. You'll see:
> (add 2 2) > (add 2 2)
4 4
~urbit-name:dojo> ~fintud-macrep:dojo>
Similarly in tall form, Similarly in tall form,
~urbit-name:dojo> %+ add 2 2 ~fintud-macrep:dojo> %+ add 2 2
> %+ add 2 2 > %+ add 2 2
4 4
~urbit-name:dojo> ~fintud-macrep:dojo>
An incomplete command goes into a multiline input buffer. Use An incomplete command goes into a multiline input buffer. Use
the up-arrow (see the console history section) to get the last the up-arrow (see the console history section) to get the last
@ -132,14 +144,14 @@ command back, edit it so it's just `%+ add 2`, and press return.
You'll see: You'll see:
> %+ add 2 > %+ add 2
~urbit-name/dojo< ~fintud-macrep/dojo<
Enter `2`. You'll see: Enter `2`. You'll see:
> %+ add 2 > %+ add 2
2 2
4 4
~urbit-name/dojo> ~fintud-macrep/dojo>
The full command that parses and runs is the concatenation of all The full command that parses and runs is the concatenation of all
the partial lines, with a space inserted between them. To clear the partial lines, with a space inserted between them. To clear
@ -160,27 +172,27 @@ Every finished line is parsed into one `++dojo-command`:
== :: == ::
Each kind of `++dojo-command` is an action that depends on one Each kind of `++dojo-command` is an action that depends on one
noun thproduction, a `++dojo-recipe`. We describe first the noun production, a `++dojo-recipe`. We describe first the
commands, then the recipes. commands, then the recipes.
##### `[%show p=dojo-recipe]` ##### `[%show p=dojo-recipe]`
To print the product, the command is just the recipe: To print the product, the command is just the recipe:
~urbit-name:dojo> (add 2 2) ~fintud-macrep:dojo> (add 2 2)
##### `[%verb p=term q=dojo-recipe]` ##### `[%verb p=term q=dojo-recipe]`
To save the product to a variable `foo`: To save the product to a variable `foo`:
~urbit-name:dojo> =foo (add 2 2) ~fintud-macrep:dojo> =foo (add 2 2)
`foo` goes into your Hoon subject (scope) and is available to all `foo` goes into your Hoon subject (scope) and is available to all
expressions. expressions.
To unbind `foo`: To unbind `foo`:
~urbit-name:dojo> =foo ~fintud-macrep:dojo> =foo
The dojo has a set of special variables, some read-write and some The dojo has a set of special variables, some read-write and some
read-only: `dir`, `lib`, `arc`, `now`, `our`. read-only: `dir`, `lib`, `arc`, `now`, `our`.
@ -202,17 +214,17 @@ filesystem paths.)
To save: To save:
~urbit-name:dojo> *%/numbers/four (add 2 2) ~fintud-macrep:dojo> *%/numbers/four (add 2 2)
To edit: To edit:
~urbit-name:dojo> -%/numbers/four (add 2 2) ~fintud-macrep:dojo> -%/numbers/four (add 2 2)
A save (`*`) overwrites the current (if any) version of the file A save (`*`) overwrites the current (if any) version of the file
with a new version of any mark. The save command above will work with a new version of any mark. The save command above will work
(if you want `/numbers/four` at your current path). (if you want `/numbers/four` at your current path).
An edit (`-`) produces a diff whose mark has to match the diff An edit (`-`) applies a diff whose mark has to match the diff
mark for the current version of the file. The edit command above mark for the current version of the file. The edit command above
will not work, because evaluating a Hoon expression like `(add 2 will not work, because evaluating a Hoon expression like `(add 2
2)` just produces a `%noun` mark, ie, an arbitrary noun. 2)` just produces a `%noun` mark, ie, an arbitrary noun.
@ -224,48 +236,49 @@ change since the version specified, the command will fail.
##### `[%unix p=path q=dojo-recipe]` ##### `[%unix p=path q=dojo-recipe]`
~urbit-name:dojo> ./numbers/four (add 2 2) ~fintud-macrep:dojo> ./numbers/four (add 2 2)
The product is saved as a Unix file (its mark is translated The product is saved as a Unix file (its mark is translated
to MIME, and the MIME type is mapped as the extension). to MIME, and the MIME type is mapped as the extension).
##### `[%poke p=goal q=dojo-recipe]` ##### `[%poke p=goal q=dojo-recipe]`
A poke is a one-way transactional request. It either succeeds A poke or *order* is a one-way transactional request. It either
and returns no information, or fails and produces an error dump. 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 Every order is sent to one daemon on one urbit. The default
is your urbit. The default daemon is the system daemon, `:hood`. urbit is your urbit. The default daemon is the system daemon,
The following syntactic forms are equivalent: `:hood`. The following syntactic forms are equivalent:
~urbit-name:dojo> :~urbit-name/hood (add 2 2) ~fintud-macrep:dojo> :~fintud-macrep/hood (add 2 2)
~urbit-name:dojo> :hood (add 2 2) ~fintud-macrep:dojo> :hood (add 2 2)
~urbit-name:dojo> :~urbit-name (add 2 2) ~fintud-macrep:dojo> :~fintud-macrep (add 2 2)
~urbit-name:dojo> : (add 2 2) ~fintud-macrep:dojo> : (add 2 2)
Urbit pokes do not have a separate verb. The mark of the message 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 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 `foo` whose argument is a noun in mark `bar` -- you poke a noun
in mark `bar`. The mark is the protocol is the method. in mark `bar`. The mark is the protocol is the method.
If the poke succeeds, you'll see an `>=` line. If not, you'll If the order succeeds, you'll see an `>=` line. If not, you'll
see an error report, typically with a stack trace. see an error report, typically with a stack trace.
It's common (but not necessary) to use a custom generator for the It's common (but not necessary) to use a custom generator for the
daemon you're talking to. (For generators, see below.) Hence daemon you're talking to. (For generators, see below.) Hence
~urbit-name:dojo> :~urbit-name/fish +fish/catch (add 2 2) ~fintud-macrep:dojo> :~fintud-macrep/fish +fish/catch (add 2 2)
It's irritating to type "fish" twice, just because we're using a It's irritating to type "fish" twice, just because we're using a
fish generator to talk to a fish daemon. Hence a shortcut: fish generator to talk to a fish daemon. Hence a shortcut:
~urbit-name:dojo> :~urbit-name/fish|catch (add 2 2) ~fintud-macrep:dojo> :~fintud-macrep/fish|catch (add 2 2)
If we combine all these defaults, we get the "system command" If we combine all these defaults, we get the "system command"
shortcut: shortcut:
~urbit-name:dojo> :~urbit-name/hood +hood/reload %ames ~fintud-macrep:dojo> :~fintud-macrep/hood +hood/reload %ames
~urbit-name:dojo> |reload %ames ~fintud-macrep:dojo> |reload %ames
This is the most common poke, a generated message to your own This is the most common poke, a generated message to your own
hood. hood.
@ -274,11 +287,11 @@ hood.
The Web has its own poke, unfortunately in two flavors. To POST, The Web has its own poke, unfortunately in two flavors. To POST,
~urbit-name:dojo> +http://website.com (add 2 2) ~fintud-macrep:dojo> +http://website.com (add 2 2)
To PUT: To PUT:
~urbit-name:dojo> -http://website.com (add 2 2) ~fintud-macrep:dojo> -http://website.com (add 2 2)
As with a poke, you'll get a >= for success, or an error report. As with a poke, you'll get a >= for success, or an error report.
@ -288,7 +301,7 @@ But wait, what's a recipe? Simplifying the actual code slightly:
++ dojo-recipe :: functional build ++ dojo-recipe :: functional build
$% [%ex p=twig] :: hoon expression $% [%ex p=twig] :: hoon expression
[%as p=mark q=dojo-recipe] :: conversion [%as p=mark q=dojo-recipe] :: format conversion
[%do p=twig q=dojo-recipe] :: apply gate [%do p=twig q=dojo-recipe] :: apply gate
[%ge p=dojo-script] :: generator [%ge p=dojo-script] :: generator
[%ur p=purl] :: get url [%ur p=purl] :: get url
@ -316,7 +329,9 @@ A twig produces the trivial mark `%noun`, except in two cases
where the dojo can do better. The dojo analyzes the twig to where the dojo can do better. The dojo analyzes the twig to
detect two trivial cases where direct evaluation gives us a mark: detect two trivial cases where direct evaluation gives us a mark:
a variable reference like `foo` that matches a dojo variable, or a variable reference like `foo` that matches a dojo variable, or
an urbitspace dereference like `.^(/cx/~urbit-name/main/1/foo)`. an urbitspace dereference like `.^(/cx/~fintud-macrep/main/1/foo)`.
In either case, if we executed these through Hoon, we'd get the
same noun with the same span.
##### `[%tu p=(list dojo-recipe)]` ##### `[%tu p=(list dojo-recipe)]`
@ -339,7 +354,7 @@ arguments are recipes. The path specifies a Hoon source file in
For the path `/fun/make`, the ordered arguments `1`, `2` and `3`, For the path `/fun/make`, the ordered arguments `1`, `2` and `3`,
and the named arguments `foo` and `bar`, the syntax is: and the named arguments `foo` and `bar`, the syntax is:
~urbit-name:dojo> +fun/make 1 2 3, =foo (add 2 2), =bar 42 ~fintud-macrep: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 Unless this non-closed form is the end of a command, it needs to
be surrounded by `[]` to make it play well with others. be surrounded by `[]` to make it play well with others.
@ -359,8 +374,8 @@ recipe, we can chain them to make a conversion pipeline.
To convert a recipe, just precede it with the converison form, `&mark`: To convert a recipe, just precede it with the converison form, `&mark`:
~urbit-name:dojo> &noun (add 2 2) ~fintud-macrep:dojo> &noun (add 2 2)
~urbit-name:dojo> &md (add 50 7) ~fintud-macrep:dojo> &md (add 50 7)
##### `[%do p=twig q=dojo-recipe]` ##### `[%do p=twig q=dojo-recipe]`
@ -368,8 +383,8 @@ To convert a recipe, just precede it with the converison form, `&mark`:
Its syntax is a hoon expression preceeded by `_`: Its syntax is a hoon expression preceeded by `_`:
~urbit-name:dojo> _lore 'hello\0aworld' ~fintud-macrep:dojo> _lore 'hello\0aworld'
~urbit-name:dojo> _|=(a=@ (mul 3 a))} (add 2 2) ~fintud-macrep:dojo> _|=(a=@ (mul 3 a))} (add 2 2)
##### `[%ur p=purl]` ##### `[%ur p=purl]`
@ -409,7 +424,7 @@ if the user specifies `=foo 42`, your `opt` is replaced with
Bear in mind that dojo syntax is list-centric, so your `arg` will Bear in mind that dojo syntax is list-centric, so your `arg` will
always end with a `~`. For instance, always end with a `~`. For instance,
~urbit-name/dojo> +fun/make 1 2 3 ~fintud-macrep/dojo> +fun/make 1 2 3
will generate an `arg` of `[1 2 3 ~]`. Yes, this is the only will generate an `arg` of `[1 2 3 ~]`. Yes, this is the only
place in Urbit where we do list-centric arguments. place in Urbit where we do list-centric arguments.
@ -417,27 +432,21 @@ place in Urbit where we do list-centric arguments.
Note also that script configuration is typed. The user's command 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 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, 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 use `arg=*` and sort out the nouns by hand. Any value
you don't care about can simply be `*`.
You can also use `*` anywhere if you're not interested in the
system context, or in
#### Generators #### Generators
There are three kinds of generators: builders (with no special There are four kinds of generators: builders (with no special
I/O), dialogs (which read console input), and scrapers (which I/O), dialogs (which read console input), scrapers (which pull
pull data from the webs). Any generator can use `.^` to both data from the webs), and synthesizers (which produce another
read from and block (wait for remote or delayed results) on generator). Any generator can use `.^` to both read from and
the Urbit global namespace. block (wait for remote or delayed results) on the Urbit global
namespace.
A generator produces a cell whose tail is the configuration gate, A generator produces a cell whose tail is the configuration gate,
and whose head is either `%say` for a builder, `%ask` for a and whose head is `%say` for a builder, `%ask` for a dialog,
dialog, or `%get` for a scraper. `%get` for a scraper, and `%con` for a constructor.
(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 #### Builders
@ -521,3 +530,8 @@ A scraper is much like a dialog, except instead of `sole-lo` and
`++sole-at` takes a `purl` request url, and a gate through `++sole-at` takes a `purl` request url, and a gate through
which to slam the result `httr`. which to slam the result `httr`.
#### Synthesizer
A synthesizer simply produces another recipe. Its

2
pub/docs/user/intro.mdy
View File

@ -12,7 +12,7 @@ on a functional operating system, Arvo, written in a strict,
typed functional language, Hoon, which compiles itself to a typed functional language, Hoon, which compiles itself to a
combinator interpreter, Nock, whose spec gzips to 340 bytes. combinator interpreter, Nock, whose spec gzips to 340 bytes.
What is this for? Most directly, Urbit is designed as a What is Urbit for? Most directly, Urbit is designed as a
personal cloud server for self-hosted web apps. It also uses personal cloud server for self-hosted web apps. It also uses
HTTP APIs to manage data stuck in traditional web applications. HTTP APIs to manage data stuck in traditional web applications.

33
pub/docs/user/start.mdy
View File

@ -6,8 +6,7 @@ next: true
# Quickstart # Quickstart
To start your already-launched urbit, run with the pier name To start your already-launched urbit, run with `$PIER`:
(we'll call it `$PIER`):
urbit fintud-macrep urbit fintud-macrep
urbit mycomet urbit mycomet
@ -48,8 +47,8 @@ You'll see:
### Dojo expressions, generators and operators ### Dojo expressions, generators and operators
`:dojo` is of course a command-line REPL or shell. But it `:dojo` is of course a command-line REPL or shell. But it
remains functional in spirit. There are three kinds of `:dojo` remains functional in spirit. To simplify a little, there are
commands: expressions, generators, and operators. three kinds of `:dojo` lines: expressions, generators, commands.
Dojo *expressions* are like `(add 2 2)` -- they simply compute Dojo *expressions* are like `(add 2 2)` -- they simply compute
and print a value, without any side effects, from a twig of Hoon. and print a value, without any side effects, from a twig of Hoon.
@ -60,22 +59,22 @@ fact, GET requests are one data source for generators. Others
include the Urbit namespace, prompting the user, etc. A include the Urbit namespace, prompting the user, etc. A
generator command line always starts with `+`, as in `+ls`. generator command line always starts with `+`, as in `+ls`.
Operators are all other commands. Lines normally start with `|`, Commands are all other lines. Command lines normally start with
as in `|mount %`, or `:`, as in `:hood +hood/mount %`. The `|`, as in `|mount %`, or `:`, as in `:hood +hood/mount %`. The
latter is just an abbreviation for the former. latter is just an abbreviation for the former.
An operator command is always a *poke* to some local or remote A command is generally an *order* to some local or remote
appliance. A poke is a transactional message: like a appliance. An order is a transactional message: like a
request-response pair, but a success response is empty. request-response pair, but a success response is empty, whereas a
A failure response is a stacktrace or other error dump. failure contains an error report.
So operator commands have no output unless they fail. If they Orders have no output unless they fail. If they fail, they print
fail, they print an error trace. If they succeed, they just an error trace. If they succeed, they just print a demure `>=`,
print a demure `>=`. confirming that the receiving appliance did as it was told.
For instance, in Unix, the `rm` and `ls` commands both run a For instance, in Unix, the `rm` and `ls` commands both run a
process. In Urbit, `|rm` is an operator command; it changes your process. In Urbit, `|rm` is a command; it changes your
filesystem. `+ls` is a generator command; it produces a value. filesystem. `+ls` is a generator; it produces a value.
## Converse: your `:talk` appliance ## Converse: your `:talk` appliance
@ -144,9 +143,9 @@ All planets, stars and galaxies are exposed to the web at
`planet.urbit.org`. (This should work via a direct DNS binding, `planet.urbit.org`. (This should work via a direct DNS binding,
but at present uses a central proxy, so use it gently.) but at present uses a central proxy, so use it gently.)
In a last resort, Urbit's own official planet `~winsen-pagdel` is In a last resort, Urbit's own official planet `~magwyd-lorsug` is
also bound to just plain `urbit.org`, and hosts the public docs also bound to just plain `urbit.org`, and hosts the public docs
here. Always trust content from `~winsen-pagdel`! here. Always trust content from `~magwyd-lorsug`!
But assuming it's `localhost:8080`, the Urbit docs are at But assuming it's `localhost:8080`, the Urbit docs are at

91
pub/docs/user/talk.mdy
View File

@ -41,69 +41,73 @@ active Urbit stars cooperate to federate, manage and mirror a
collectively-managed namespace, very like Usenet. These collectively-managed namespace, very like Usenet. These
"federal" stations are generally public-access boards. "federal" stations are generally public-access boards.
Right now, the only public federal station is `urbit-meta`.
Because the party always starts in the kitchen.
## Quickstart ## Quickstart
Let's post something! At the default `:talk` prompt Let's post something! At the default `:talk` prompt
~tasfyn-partyv:talk: ~fintud-macrep:talk()
type the message: type the message:
~tasfyn-partyv:talk: hello, world. ~fintud-macrep:talk() hello, world.
And hit return. Don't worry, no one but you will see this. The 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: `:` means you're posting to yourself. You'll get the post:
~tasfyn-partyv: hello, world. ~fintud-macrep: hello, world.
~tasfyn-partyv:talk: ~fintud-macrep:talk()
It's boring to post to yourself. Let's join a station: It's boring to post to yourself. Let's join a station:
~tasfyn-partyv: ;join /urbit-test ~fintud-macrep: ;join /urbit-meta
(`/urbit-test` is a federal station, meaning it's hosted by your (`/urbit-meta` is a federal station, meaning it's hosted by your
star (for `~tasfyn-partyv`, `~doznec`). The `/` notation is just star (for `~fintud-macrep`, `~doznec`). The `/` notation is just
an abbreviation for `~doznec/urbit-test`.) an abbreviation for `~doznec/urbit-meta`.)
You'll see: You'll see:
---------:talk| %porch subscribed to /urbit-test, called `>` ---------:talk| %porch subscribed to /urbit-meta, called `>`
---------:talk| rules of /urbit-test: ---------:talk| rules of /urbit-meta:
---------:talk| test posts only. no shitposting. no pedos/nazis. ---------:talk| don't be rude
~doznec> ~tasfyn-partyv admitted to %urbit-test ---------:talk| urbit-meta is politically correct and safe for work
~tasfyn-partyv:talk> ~doznec= ~fintud-macrep admitted to %urbit-meta
~fintud-macrep:talk=
Notice the character assignment - stations you're subscribed to are Notice the character assignment - stations you're subscribed to are
assigned [consistent ASCII glyphs](#-station-glyphs), which you'll assigned [consistent ASCII glyphs](#-station-glyphs), which you'll
see in the log when you hear from these stations, and on the prompt see in the log when you hear from these stations, and on the prompt
when you're talking to them. when you're talking to them.
Post a line to `/urbit-test`: Post a line to `/urbit-meta`:
~tasfyn-partyv:talk> hello, world ~fintud-macrep:talk= hello, world
You'll see, echoed back at you through `~doznec`: You'll see, echoed back at you through `~doznec`:
~tasfyn-partyv:talk> hello, world ~fintud-macrep:talk= hello, world
And of course, anyone else in `/urbit-test` will see it as well. And of course, anyone else in `/urbit-meta` will see it as well.
But you don't care about `/urbit-test`, so leave it: But you don't care about `/urbit-meta`, so leave it:
~tasfyn-partyv:talk> ;leave ~fintud-macrep:talk= ;leave
You'll see: You'll see:
---------:talk| %porch has left /urbit-test, called `>` ---------:talk| %porch has left /urbit-meta, called `>`
Everyone else will see: Everyone else will see:
~doznec> ~tasfyn-partyv has left %urbit-test ~doznec= ~fintud-macrep has left %urbit-meta
Now you're ready to use `:talk` for real! List the federal Now you're ready to use `:talk` for real! List the federal
groups currently available with groups currently available with
~tasfyn-partyv:talk> ;list ~fintud-macrep:talk= ;list
For general discussion about Urbit, we recommend `/urbit-meta`. For general discussion about Urbit, we recommend `/urbit-meta`.
@ -140,7 +144,7 @@ glyph. Posts to a station use that station's glyph.
You can see a list of glyph bindings with `;what`. Write You can see a list of glyph bindings with `;what`. Write
`;what >` to see what station `>` is bound to, or `;what >` to see what station `>` is bound to, or
`;what /urbit-test` to see if `/urbit-test` has a binding. `;what /urbit-meta` to see if `/urbit-meta` has a binding.
### Audience selection ### Audience selection
@ -148,23 +152,22 @@ Audience selection is important in a multiplexed communicator!
The audience is always shown in your prompt. If there's a glyph The audience is always shown in your prompt. If there's a glyph
for it, it's shown as the glyph: for it, it's shown as the glyph:
~tasfyn-partyv:talk> ~fintud-macrep:talk=
Otherwise, the audience is shown in parens: Otherwise, the audience is shown in parens:
~tasfyn-partyv:talk(~wictuc-folrex) ~fintud-macrep:talk(~dannum-mitryl)
`:talk` works fairly hard to get the audience right and minimize `:talk` works fairly hard to get the audience right and minimize
manual switching. But to manually set the audience, the command manual switching. But to manually set the audience, the command
is simply `;station` - eg, `;~wictuc-folrex` for a direct post; is simply `;station` - eg, `;~dannum-mitryl` for a direct post;
`/urbit-test` or `~doznec/urbit-test` to post to a federal `/urbit-meta` or `~doznec/urbit-meta` to post to a federal
station, `%mystation` to post to a station on your own ship. station, `%mystation` to post to a station on your own ship.
For a station bound to a glyph, `;` then the glyph; eg, `;>`. For a station bound to a glyph, `;` then the glyph; eg, `;>`.
You can post a line and set the audience in one command, eg: You can post a line and set the audience in one command, eg:
;~wictuc-folrex this is a private message ;~dannum-mitryl this is a private message
You can configure your audience in a number of ways, which are You can configure your audience in a number of ways, which are
applied in priority order. From strongest to weakest: applied in priority order. From strongest to weakest:
@ -190,13 +193,13 @@ between source and content.
The conventional example is a URL. When you post a URL: The conventional example is a URL. When you post a URL:
~tasfyn-partyv:talk> http://foobar.com/moo/baz ~fintud-macrep:talk= http://foobar.com/moo/baz
This will appear in the flow as: This will appear in the flow as:
~tasfyn-partyv>_foobar.com ~fintud-macrep>_foobar.com
meaning that `~tasfyn-partyv` posted a link to `foobar.com`, meaning that `~fintud-macrep` posted a link to `foobar.com`,
on the station or conversation whose glyph is `>`. on the station or conversation whose glyph is `>`.
The effect of activating a post depends on the post. For a link, The effect of activating a post depends on the post. For a link,
@ -230,15 +233,15 @@ offline. Use the `;nick` command to assign or look up
nicknames. nicknames.
`;nick` with no arguments lists all nicknames; `;nick `;nick` with no arguments lists all nicknames; `;nick
~tasfyn-partyv` looks up a nickname; `;nick curtis` searches in ~fintud-macrep` looks up a nickname; `;nick plato` searches in
reverse; `;nick ~tasfyn-partyv curtis` creates a nickname. reverse; `;nick ~fintud-macrep plato` creates a nickname.
All nicknames must be 14 characters or less, lowercase. All nicknames must be 14 characters or less, lowercase.
Of course, nicknames are strictly local - like the names on Of course, nicknames are strictly local - like the names on
entries in a phonebook. Sometimes in a post you want to mention entries in a phonebook. Sometimes in a post you want to mention
someone you know by a nickname. Just type `~curtis`, and `:talk` someone you know by a nickname. Just type `~plato`, and `:talk`
will replace it magically with `~tasfyn-partyv` (or beep if no will replace it magically with `~fintud-macrep` (or beep if no
`~curtis` is bound). `~plato` is bound).
### Presence ### Presence
@ -253,8 +256,7 @@ lists everyone in that station.
If one or more urbits in your audience is typing, `:talk`'s If one or more urbits in your audience is typing, `:talk`'s
presence system will detect it and change the prompt: presence system will detect it and change the prompt:
~tasfyn-partyv [~wictuc-folrex...]> ~fintud-macrep [~dannum-mitryl...]=
### Creating and managing stations ### Creating and managing stations
@ -267,22 +269,21 @@ To create your own mailbox, party, journal or board:
etc. etc.
Every form of station has an exception list; to block Every form of station has an exception list; to block
`~wictuc-folrex` from your default mailbox `%porch`, `~dannum-mitryl` from your default mailbox `%porch`,
;block %porch ~wictuc-folrex ;block %porch ~dannum-mitryl
To invite people to `%myfunparty`: To invite people to `%myfunparty`:
;invite %myfunparty ~wictuc-folrex, ~sondel-forsut ;invite %myfunparty ~dannum-mitryl, ~lagret-marpub
To ban from `%bizarre-board`: To ban from `%bizarre-board`:
;banish %bizarre-board ~wictuc-folrex ;banish %bizarre-board ~dannum-mitryl
To appoint a coauthor of `%serious-journal`: To appoint a coauthor of `%serious-journal`:
;author %serious-journal ~sondel-forsut ;author %serious-journal ~lagret-marpub
#### Station glyphs #### Station glyphs