5insert_anchor_links = "right"
10In this walkthrough we will go in-depth on how to build command line interface (CLI)
11applications in Urbit using the `shoe` library.
13There are three CLI apps that currently ship with urbit - `%dojo`, `%chat-cli`,
14and `%shoe`. You should be familiar with the former two, the latter is an example
15app that shows off how the `shoe` library works that we will be looking at
16closely. These are all Gall apps, and as such their source can be found in the `app/` folder of your `%home` desk.
18In [the `shoe` library](#the-shoe-library) we take a closer look at the `shoe` library and its
19cores and how they are utilized in CLI apps. Then in [the `sole`
20library](#the-sole-library) we look at what `shoe` effects ultimately break down
21into. Finally in [`%shoe` app walkthrough](#shoe-app-walkthrough) we explore
22the functionality of the `%shoe` app and then go through the code line-by-line.
25considered to be an application equivalent of the [Hoon school
26lesson](@/docs/tutorials/hoon/hoon-school/generators.md#ask) on `sole` and `%ask`
27generators, which only covers the bare minimum necessary to write generators
31## The `shoe` library {#the-shoe-library}
33Here we describe how sessions are identified, the specialized `card`s that Gall agents
34with the `shoe` library are able to utilize, and the different cores of `/lib/shoe.hoon` and their purpose.
36### Session identifiers
38An app using the `shoe` library will automatically track sessions by their `sole-id=@ta`.
39These are opaque identifiers generated by the connecting client. An app using the `shoe`
40library may be connected to by a local or remote ship in order to send commands,
41and each of these connections is assigned a unique `@ta` that identifies the
42ship and which session on that ship if there are multiple.
46Gall agents with the `shoe` library are able to utilize `%shoe` `card`s. These
47additions to the standard set of `cards` have the following shape:
49[%shoe sole-ids=(list @ta) effect=shoe-effect]`
51`sole-ids` is the `list` of session ids that the following `effect` is
52emitted to. An empty `sole-ids` sends the effect to all connected sessions.
53`shoe-effect`s, for now, are always of the shape `[%sole effect=sole-effect]`, where
54`sole-effect`s are basic console events such as displaying text, changing the
55prompt, beeping, etc. These are described in the section on the [`sole` library](#the-sole-library).
57For example, a `%shoe` `card` that causes all connected sessions to beep would
58be `[%shoe ~ %sole %bel ~]`.
62An iron (contravariant) door that defines an interface for Gall agents utilizing
63the `shoe` library. Use this core whenever you want to receive input from the user and run a command. The input will get
64put through the parser (`+command-parser`) and results in a noun of
65`command-type` that the underlying application specifies, which shoe then feeds back into the underlying app as an `+on-command` callback.
67In addition to the ten arms that all Gall core apps possess, `+shoe` defines and expects a few
68more, tailored to common CLI logic. Thus you will need to wrap the `shoe:shoe` core using the `agent:shoe` function to obtain a standard
6910-arm Gall agent core. See the [shoe example app
70walkthrough](#shoe-example-app-walkthrough) for how to do this.
72The additional arms are described below. The Hoon code shows their expected type signature. As we'll see [later](#shoe-app-walkthrough), the `command-type` can differ per application. Note also that most of these take a session identifier as an argument. This lets applications provide different users (at potentially different "places" within the application) with different affordances.
79 |~(nail *(like [? command-type]))
82Input parser for a specific command-line session. Will be run on whatever the user tries to input into the command prompt, and won't let them type anything that doesn't parse. If the head of the result is true,
83instantly run the command. If it's false, require the user to press return.
90 *(list (option:auto tank))
93Autocomplete options for the command-line session (to match `+command-parser`).
99 |~ [sole-id=@ta command=command-type]
103Called when a valid command is run.
113Called to determine whether a session may be opened or connected to. For example, you
114may only want the local ship to be able to connect.
121 *(quip card _^|(..on-init))
124Called when a session is opened or connected to.
131 *(quip card _^|(..on-init))
134Called when a previously made session gets disconnected from.
138This core contains the bare minimum implementation of the additional `shoe` arms
139beyond the 10 standard Gall app ams. It is used
140analogously to how the `default-agent` core is used for regular Gall apps.
144This is a function for wrapping a `shoe` core, which has too many
145arms to be a valid Gall agent core. This turns it into a standard Gall agent core by
146integrating the additional arms into the standard ones.
149## The `sole` library {#the-sole-library}
151`shoe` apps may create specialized `card`s of the `[%shoe
152(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.
154The list of possible `sole-effects` can be found in `/sur/sole.hoon`. A few
155commonly used ones are as follows.
156- `[%txt tape]` is used to display a line of text.
157- `[%bel ~]` is used to emit a beep.
158- `[%pro sole-prompt]` is used to set the prompt.
159- `[%mor (list sole-effect)]` is used to emit multiple effects.
161For example, a `sole-effect` that beeps and displays `This is some text.` would
164[%mor [%txt "This is some text."] [%bel ~] ~]
167## `%shoe` app walkthrough {#shoe-app-walkthrough}
169Here we explore the capabilities of the `%shoe` example app and then go through
170the code, explaining what each line does.
172### Playing with `%shoe`
174First let's test the functionality of `%shoe` so we know what we're getting
177Start two fake ships, one named `~zod` and the other can have any name - we will
178go with `~nus`. Fake ships run locally are able to see each other, and our
179intention is to connect their `%shoe` apps.
181On each fake ship start `%shoe` by entering `|start %shoe` into dojo. This will
183change the prompt to `~zod:shoe>` and `~nus:shoe>`. Type `demo` and watch the following appear:
188`~zod ran the command` should be displayed in bold green text, signifying that
189the command originated locally.
191Now we will connect the sessions. Switch `~zod` back to dojo with `Ctrl-X` and enter `|link
192~nus %shoe`. If this succeeds you will see the following.
195; ~nus is your neighbor
196[linked to [p=~nus q=%shoe]]
198Now `~zod` will have two `%shoe` sessions running - one local one on `~zod` and
199one remote one on `~nus`, which you can access by pressing `Ctrl-X` until you see
200`~nus:shoe>` from `~zod`'s console. On the other hand, you should not see
201`~zod:shoe>` on `~nus`'s side, since you have not connected `~nus` to `~zod`'s
202`%shoe` app. When you enter `demo` from `~nus:shoe>` on
203`~zod`'s console you will again see `~zod ran the command`, but this time it
204should be in the ordinary font used by the console, signifying that the command
205is originating from a remote session. Contrast this with entering `demo` from
206`~nus:shoe>` in `~nus`'s console, which will display `~nus ran the command` in
209Now try to link to `~zod`'s `%shoe` session from `~nus` by switching to the dojo
210on `~nus` and entering `|link ~zod %shoe`. You should see
213[unlinked from [p=~zod q=%shoe]]
215and if you press `Ctrl-X` you will not get a `~zod:shoe>` prompt. This is
216because the example app is set up to always allow `~zod` to connect (as well as
217subject moons if the ship happens to be a planet) but not `~nus`, so this
218message means that `~nus` failed to connect to `~zod`'s `%shoe` session.
223:: shoe: example usage of /lib/shoe
225:: the app supports one command: "demo".
226:: running this command renders some text on all sole clients.
228/+ shoe, verb, dbug, default-agent
231`/+` is the Ford rune which imports libraries from the `/lib` directory into
233 * `shoe` is the `shoe` library.
234 * `verb` is a library used to print what a Gall agent is doing.
235 * `dbug` is a library of debugging tools.
236 * `default-agent` contains a Gall agent core with minimal implementations of
247The types used by the app.
249`state-0` stores the state of the app, which is null as there is no state to
250keep track of. It is good practice to include a version number anyways,
251in case the app is made stateful at a later time.
253`command` is typically a set of tagged union types that represent the possible
254commands that can be entered by the user. Since this app only supports one
255command, it is unnecessary for it to have any associated data, thus the command
256is represented by `~`.
258In a non-trivial context, a `command` is commonly given by `[%name
259data]`, where `%name` is the identifier for the type of command and `data` is
260a type or list of types that contain data needed to execute the command. See
261`app/chat-cli.hoon` for examples of commands, such as `[%say letter:store]` and
262`[%delete path]`. This is not required though, and you could use something like
263`[chat-room=@t =action]`.
265`card` is either an ordinary Gall agent `card` or a `%shoe` `card`, which takes
266the shape `[%shoe sole-ids=(list @ta) effect=shoe-effect]`. A `%shoe` `card` is
267sent to all `sole`s listed in `sole-ids`, imaking them run the `sole-effect`
268specified by `effect` (i.e. printing some text). Here we can
269reference `card:shoe` because of `/+ shoe` at the beginning of the app.
276Add the bunt value of `state-0` to the head of the subject, then give it the
277macro `state`. The `-` here is a lark expression referring to the head of the
278subject. This allows us to use `state` to refer to the state elsewhere in the
279code no matter what version we're using, while also getting direct access to the
280contents of `state` (if it had any).
286%- (agent:shoe command)
287^- (shoe:shoe command)
290The casts here are just reminders of what is being produced. So let's focus on
291what the `%` runes are doing, from bottom to top. We call `(agent:shoe command)`
292on what follows (i.e. the rest of the app),
293producing a standard Gall agent core. Then we call wrap the Gall agent core with
294`agent:dbug`, endowing it with additional arms useful for debugging, and then
295wrap again with `verb`.
301 def ~(. (default-agent this %|) bowl)
302 des ~(. (default:shoe this command) bowl)
304This is boilerplate Gall agent core code. We set `this` to be a macro for the
305subject, which is the Gall agent core itself. We set `def` and `des` to be
306macros for initialized `default-agent` and `default:shoe` doors respectively.
308Next we implement all of the arms required for a `shoe` agent. Starting with
309the standard Gall arms:
312++ on-init on-init:def
319++ on-poke on-poke:def
320++ on-watch on-watch:def
321++ on-leave on-leave:def
322++ on-peek on-peek:def
323++ on-agent on-agent:def
324++ on-arvo on-arvo:def
325++ on-fail on-fail:def
327These are minimalist Gall app arm implementations using the default behavior found in `def`.
329Here begins the implementation of the additional arms required by the
330`(shoe:shoe command)` interface.
334 ^+ |~(nail *(like [? command]))
335 (cold [& ~] (jest 'demo'))
337`+command-parser` is of central importance - it is what is used to parse user
338input and transform it into `command`s for the app to execute. Writing a proper
339command parser requires understanding of the Hoon parsing functions found in the
340standard library. How to do so may be found in the [parsing tutorial](@/docs/tutorials/hoon/parsing.md). For now, it is sufficient to know that this arm matches the text "demo" and
341produces a `[? command]`-shaped noun in response. Note how the `&` signifies that the command will be run as soon as it has been entered, without waiting for the user to press return.
348 :~ ['demo' leaf+"run example command"]
351`+tab-list` is pretty much plug-n-play. For each command you want to be tab
352completed, add an entry to the `list` begun by `:~` of the form `[%command
353leaf+"description"]`. Now whenever the user types a partial command and presses
354tab, the console will display the list of commmands that match the partial
355command as well as the descriptions given here.
357Thus here we have that starting to type `demo` and pressing tab will result in
358the following output in the console:
360demo run example command
363with the remainder of `demo` now added to the input line.
365Next we have `+on-command`, which is called whenever `+command-parser`
366recognizes that `demo` has been entered by a user.
369 |= [sole-id=@ta =command]
372This is a gate that takes in the `sole-id` corresponding to the session and the
373`command` noun parsed by `+command-parser` and returns a `list` of `card`s and
374`_this`, which is our shoe agent core including its state.
376 =- [[%shoe ~ %sole -]~ this]
378This creates a cell of a `%shoe` card that triggers a `sole-effect` given by the head of
379the subject `-`, then the Gall agent core `this` - i.e. the return result of
380this gate. The use of the `=-` rune means that what follows this
381expression is actually run first, which puts the desired `sole-effect` into the
384 =/ =tape "{(scow %p src.bowl)} ran the command"
386We define the `tape` that we want to be printed.
390 [%klr [[`%br ~ `%g] [(crip tape)]~]~]
392We cannot just produce the `tape` we want printed, - it needs to fit the
393`sole-effect` type. This tells us that if the
394origin of the command is not our ship to just print it normally with the `%txt`
395`sole-effect`. Otherwise we use `%klr`, which prints it stylistically (here it
396makes the text green and bold).
398The following allows either `~zod`, or the host ship and its moons, to connect to
399this app's command line interface using `|link`.
405 (team:title [our src]:bowl)
409We use the minimal implementations for the final two `shoe` arms, since we don't
410want to do anything special when users connect or disconnect.
412++ on-connect on-connect:des
413++ on-disconnect on-disconnect:des
417This concludes our review of the code of the `%shoe` app. To continue learning
418how to build your own CLI app, we recommend checking out `/app/chat-cli.hoon`.
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list