mirror of
https://github.com/urbit/developers.urbit.org.git
synced 2024-09-11 13:55:59 +03:00
cli tutorial: update for new sole-id type
As part of sole protocol changes released in zuse 416. See also urbit/urbit commit 3120681.
This commit is contained in:
parent
ab2830a28e
commit
7209ae4717
@ -34,11 +34,13 @@ with the `shoe` library are able to utilize, and the different cores of `/lib/sh
|
||||
|
||||
### Session identifiers
|
||||
|
||||
An app using the `shoe` library will automatically track sessions by their `sole-id=@ta`.
|
||||
These are opaque identifiers generated by the connecting client. An app using the `shoe`
|
||||
library may be connected to by a local or remote ship in order to send commands,
|
||||
and each of these connections is assigned a unique `@ta` that identifies the
|
||||
ship and which session on that ship if there are multiple.
|
||||
An app using the `shoe` library will automatically track sessions by their
|
||||
`sole-id`. A `sole-id` is made up of a "host" ship name and some identifier
|
||||
string. Generally, however, the `sole-id` as a whole should be treated as an
|
||||
opaque identifier, generated by the connecting client. An app using the `shoe`
|
||||
library may be connected to by a local or remote ship in order to send
|
||||
commands, and each of these connections is assigned a unique `sole-id` that
|
||||
identifies the ship and which session on that ship if there are multiple.
|
||||
|
||||
### `%shoe` `card`s
|
||||
|
||||
@ -46,7 +48,7 @@ Gall agents with the `shoe` library are able to utilize `%shoe` `card`s. These
|
||||
additions to the standard set of `cards` have the following shape:
|
||||
|
||||
```hoon
|
||||
[%shoe sole-ids=(list @ta) effect=shoe-effect]`
|
||||
[%shoe sole-ids=(list sole-id) effect=shoe-effect]`
|
||||
```
|
||||
|
||||
`sole-ids` is the `list` of session ids that the following `effect` is
|
||||
@ -76,7 +78,7 @@ The additional arms are described below. The Hoon code shows their expected type
|
||||
|
||||
```hoon
|
||||
++ command-parser
|
||||
|~ sole-id=@ta
|
||||
|~ =sole-id
|
||||
|~(nail *(like [? command-type]))
|
||||
```
|
||||
|
||||
@ -87,7 +89,7 @@ instantly run the command. If it's false, require the user to press return.
|
||||
|
||||
```hoon
|
||||
++ tab-list
|
||||
|~ sole-id=@ta
|
||||
|~ =sole-id
|
||||
*(list (option:auto tank))
|
||||
```
|
||||
|
||||
@ -97,7 +99,7 @@ Autocomplete options for the command-line session (to match `+command-parser`).
|
||||
|
||||
```hoon
|
||||
++ on-command
|
||||
|~ [sole-id=@ta command=command-type]
|
||||
|~ [=sole-id command=command-type]
|
||||
*(quip card _this)
|
||||
```
|
||||
|
||||
@ -107,7 +109,7 @@ Called when a valid command is run.
|
||||
|
||||
```hoon
|
||||
++ can-connect
|
||||
|~ sole-id=@ta
|
||||
|~ =sole-id
|
||||
*?
|
||||
```
|
||||
|
||||
@ -118,7 +120,7 @@ may only want the local ship to be able to connect.
|
||||
|
||||
```hoon
|
||||
++ on-connect
|
||||
|~ sole-id=@ta
|
||||
|~ =sole-id
|
||||
*(quip card _^|(..on-init))
|
||||
```
|
||||
|
||||
@ -128,7 +130,7 @@ Called when a session is opened or connected to.
|
||||
|
||||
```hoon
|
||||
++ on-disconnect
|
||||
|~ sole-id=@ta
|
||||
|~ =sole-id
|
||||
*(quip card _^|(..on-init))
|
||||
```
|
||||
|
||||
@ -148,7 +150,7 @@ integrating the additional arms into the standard ones.
|
||||
|
||||
## The `sole` library {% #the-sole-library %}
|
||||
|
||||
`shoe` apps may create specialized `card`s of the `[%shoe (list @ta) shoe-effect]` shape, where `shoe-effect` currently just wrap `sole-effect`s, i.e. instructions for displaying text and producing other effects in the console.
|
||||
`shoe` apps may create specialized `card`s of the `[%shoe (list sole-id) shoe-effect]` shape, where `shoe-effect` currently just wrap `sole-effect`s, i.e. instructions for displaying text and producing other effects in the console.
|
||||
|
||||
The list of possible `sole-effects` can be found in `/sur/sole.hoon`. A few
|
||||
commonly used ones are as follows.
|
||||
@ -158,7 +160,7 @@ commonly used ones are as follows.
|
||||
- `[%pro sole-prompt]` is used to set the prompt.
|
||||
- `[%mor (list sole-effect)]` is used to emit multiple effects.
|
||||
|
||||
For example, a `sole-effect` that beeps and displays `This is some text.` would
|
||||
For example, a `sole-effect` that displays `This is some text.` and beeps would
|
||||
be structured as
|
||||
|
||||
```hoon
|
||||
@ -270,8 +272,8 @@ a type or list of types that contain data needed to execute the command. See
|
||||
`[chat-room=@t =action]`.
|
||||
|
||||
`card` is either an ordinary Gall agent `card` or a `%shoe` `card`, which takes
|
||||
the shape `[%shoe sole-ids=(list @ta) effect=shoe-effect]`. A `%shoe` `card` is
|
||||
sent to all `sole`s listed in `sole-ids`, imaking them run the `sole-effect`
|
||||
the shape `[%shoe sole-ids=(list sole-id) effect=shoe-effect]`. A `%shoe` `card` is
|
||||
sent to all sessions listed in `sole-ids`, making them run the `sole-effect`
|
||||
specified by `effect` (i.e. printing some text). Here we can
|
||||
reference `card:shoe` because of `/+ shoe` at the beginning of the app.
|
||||
|
||||
@ -340,7 +342,7 @@ Here begins the implementation of the additional arms required by the
|
||||
|
||||
```hoon
|
||||
++ command-parser
|
||||
|= sole-id=@ta
|
||||
|= =sole-id
|
||||
^+ |~(nail *(like [? command]))
|
||||
(cold [& ~] (jest 'demo'))
|
||||
```
|
||||
@ -353,7 +355,7 @@ produces a `[? command]`-shaped noun in response. Note how the `&` signifies tha
|
||||
|
||||
```hoon
|
||||
++ tab-list
|
||||
|= sole-id=@ta
|
||||
|= =sole-id
|
||||
^- (list [@t tank])
|
||||
:~ ['demo' leaf+"run example command"]
|
||||
==
|
||||
@ -379,7 +381,7 @@ recognizes that `demo` has been entered by a user.
|
||||
|
||||
```hoon
|
||||
++ on-command
|
||||
|= [sole-id=@ta =command]
|
||||
|= [=sole-id =command]
|
||||
^- (quip card _this)
|
||||
```
|
||||
|
||||
@ -420,7 +422,7 @@ this app's command line interface using `|link`.
|
||||
|
||||
```hoon
|
||||
++ can-connect
|
||||
|= sole-id=@ta
|
||||
|= =sole-id
|
||||
^- ?
|
||||
?| =(~zod src.bowl)
|
||||
(team:title [our src]:bowl)
|
||||
|
Loading…
Reference in New Issue
Block a user