11This document describes the different interfaces Hall provides and the data that is accessible and modifiable through them. Knowledge of the Urbit application model (including [new gall](new-gall)) and [Hall's architecture](architecture) is assumed.
13While the structures here are given in Hoon, they match fairly closely to their JSON equivalent. Most important to note is that `$%({$x y/z})` becomes accessible as `json.x.y`.
20 * [/client prize](#client-prize)
21 * [/client rumor](#client-rumor)
23 * [/public prize](#public-prize)
24 * [/public rumor](#public-rumor)
26 * [/peers prize](#peers-prize)
27 * [/peers rumor](#peers-rumor)
29 * [/circle prize](#circle-prize)
30 * [/circle rumor](#circle-rumor)
32 * [Circle configuration](#circle-configuration)
33 * [Messaging](#messaging)
34 * [Personal metadata](#personal-metadata)
35 * [Changing shared UI](#changing-shared-ui)
36 * [Miscellaneous changes](#miscellaneous-changes)
41Queries are the paths you pass into `%peer` moves. Internally, they get translated to a `++query` structure for easier handling. We'll be giving examples of valid query paths alongside the structures themselves.
45To be able to keep certain UI elements like glyphs and local nicknames consistent across different Hall clients, they can query Hall for the current UI state.
49 $% {$client $~} :< shared ui state
63Contains a map of glyphs and the audiences that they map to, as well as a map of ships and their locally set nicknames.
66++ prize :> query result
67 $% {$client prize-client} :< /client
70++ prize-client :> shared ui state
71 $: gys/(jug char audience) :< glyph bindings
72 nis/(map ship nick) :< local nicknames
78Contains either a bound or unbound glyph and its target, or a ship with its new nickname. A nickname of `''` means the associated ship no longer has a nickname set for it.
81++ rumor :> query result change
82 $% {$client rum/rumor-client} :< /client
85++ rumor-client :< changed ui state
86 $% {$glyph diff-glyph} :< un/bound glyph
87 {$nick diff-nick} :< changed nickname
89++ diff-glyph {bin/? gyf/char aud/audience} :< un/bound glyph
90++ diff-nick {who/ship nic/nick} :< changed nickname
96To aid in circle discoverability, users can add circles to their "public membership" list. This can then be queried for by, for example, a profile page.
100 $% {$public $~} :< public memberships
108:> all public memberships
114Contains the set of circles the user has on their public list.
117++ prize :> query result
118 $% {$public cis/(set circle)} :< /public
125Contains a circle that was either added or removed from the public list.
128++ rumor :> query result change
129 $% {$public add/? cir/circle} :< /public
136To allow a circle owner to inspect who is currently subscribed to their stories, they can issue a query to retrieve subscription data.
140 $% {$peers nom/naem} :< readers of story
145Query paths are structured as follows:
154:> peers for circle %urbit-meta
160Contains a map of ships and the different queries they currently have active for the selected story.
163++ prize :> query result
164 $% {$peers pes/(jar ship query)} :< /peers
171Contains a ship and a query, and a flag to indicate whether that subscription has started or ended.
174++ rumor :> query result change
175 $% {$peers add/? who/ship qer/query} :< /peers
182Circle queries allow for the retrieving of data from stories. Their messages, configuration, and presences can all be accessed. Since this is a lot of data, there are lots of possibilities for filtering it built in to the query itself.
185A quick refresher on the difference between "local" and "remote" presence and configuration: "local" means it pertains to the circle itself; "remote" means it pertains to one of its configured sources. The latter is primarily useful to clients when using a circle for aggregation, like the `%inbox`.
189 $% $: $circle :> story query
190 nom/naem :< circle name
191 wer/(unit circle) :< from source
192 wat/(set circle-data) :< data to get
193 ran/range :< query duration
197++ circle-data :> kinds of circle data
198 $? $grams :< messages
199 $group-l :< local presence
200 $group-r :< remote presences
201 $config-l :< local config
202 $config-r :< remote configs
204++ range :> inclusive msg range
205 %- unit :< ~ means everything
206 $: hed/place :< start of range
207 tal/(unit place) :< opt end of range
209++ place :> range indicators
211 {$ud @ud} :< message number
215Query paths are structured as follows:
218/circle/[circle-name]/(from-circle)/[what/data]/(range-start(/range-end))
219(from-circle) : optional message source, ~ship/circle
220[what/data] : one or more of grams, group, group-l, group-r,
221 : config, config-l, config-r, combined using /
222(range) : an optional range with an optional end, its points denoted
223 : in either message number (@ud) or date (@da)
229:> get all messages from circle %urbit-meta
230/circle/urbit-meta/grams
231:> get all messages, all presences and local configs from %urbit-meta
232/circle/urbit-meta/grams/group/config-l
233:> get all messages %urbit-meta has heard from its source ~zod/fora
234/circle/urbit-meta/~zod/fora/grams
235:> get the first 100 messages from %urbit-meta
236/circle/urbit-meta/grams/0/99
237:> get the first 100 messages %urbit-meta has heard from its source ~zod/fora
238/circle/urbit-meta/~zod/fora/grams/0/99
239:> get all messages from %urbit-meta, starting now
240/circle/urbit-meta/grams/group/(scow %da now)
241:> get all messages from %urbit-meta, starting now, ending at the 100th message
242/circle/urbit-meta/grams/(scow %da now)/99
243:> get local presences from %urbit-meta for a week
244/circle/urbit-meta/group-l/(scow %da now)/(scow %da (add now ~d7))
249Contains (where applicable) messages in envelopes (with message numbers), as well as local and remote configurations and presences.
252++ prize :> query result
253 $% {$circle package} :< /circle
256++ package :> story state
257 $: nes/(list envelope) :< messages
258 cos/lobby :< loc & rem configs
259 pes/crowd :< loc & rem presences
265Contains a detailed change description of the data relevant to the query that changed.
267Messages are wrapped in envelopes to include their sequence number, and note the source they were heard from. Configuration and status changes specify the circle they apply to.
270++ rumor :> query result change
271 $% {$circle rum/rumor-story} :< /circle
274++ rumor-story :> story rumor
275 $% {$new cof/config} :< new story
276 {$gram src/circle nev/envelope} :< new/changed message
277 {$config cir/circle dif/diff-config} :< new/changed config
278 {$status cir/circle who/ship dif/diff-status} :< new/changed status
279 {$remove $~} :< removed story
281++ diff-config :> config change
282 $% {$full cof/config} :< set w/o side-effects
283 {$source add/? src/source} :< add/rem sources
284 {$caption cap/cord} :< changed description
285 {$filter fit/filter} :< changed filter
286 {$secure sec/security} :< changed security
287 {$permit add/? sis/(set ship)} :< add/rem to b/w-list
288 {$remove $~} :< removed config
290++ diff-status :> status change
291 $% {$full sat/status} :< fully changed status
292 {$presence pec/presence} :< changed presence
293 {$human dif/diff-human} :< changed name
294 {$remove $~} :< removed status
296++ diff-human :> name change
297 $% {$full man/human} :< fully changed name
298 {$handle han/(unit cord)} :< changed handle
299 {$true tru/(unit truename)} :< changed true name
306Actions can be sent by poking Hall with data marked as `%hall-action`. Actions are used for all user operations. If an error or other unexpected behavior occurs while executing an action, Hall notifies the user by sending an `%app` message to their `%inbox`.
308### Circle configuration
310Since all of these apply to a specific circle, they all specify a name `nom` of the circle to operate on.
313++ action :> user action
314 $% {$create nom/naem des/cord sec/security} :< create circle
315 {$delete nom/naem why/(unit cord)} :< delete + announce
316 {$depict nom/naem des/cord} :< change description
317 {$filter nom/naem fit/filter} :< change message rules
318 {$permit nom/naem inv/? sis/(set ship)} :< invite/banish
319 {$source nom/naem sub/? srs/(set source)} :< un/sub to/from src
324`%create`: Creates a circle with description `des` and security mode `sec`. If this mode is a whitelist, the user is automatically added to it.
326`%delete`: Deletes the circle. If a reason `why` is provided, posts that as the last message to the circle before deleting it.
328`%depict`: Set the description of the circle to `des`.
330`%filter`: Set the filter (message sanitation rules) for the circle to `fit`.
332`%permit`: Either invite or banish ships to/from the circle, modifying the access control list accordingly. Regardless of whether this actually makes any changes, sends an `%inv` message to the involved ships' `%inbox`es.
334`%source`: Add or remove sources to/from the circle, un/subscribing it to/from the `grams`, `group-l` and `config-l` each one.
338There are two interfaces for telling Hall to send a message. The first takes entire `thought`s, the second only `speech`es and the audience to send them to.
341++ action :> user action
342 $% {$convey tos/(list thought)} :< post exact
343 {$phrase aud/audience ses/(list speech)} :< post easy
348`%convey`: Sends the thoughts to their audiences.
350`%phrase`: Turns the speeches into thoughts by applying sane defaults for metadata (auto-generated `uid`, `now` for `wen`), and then sends those thoughts.
354These concern the presence users have in circles they are participating in.
357++ action :> user action
358 $% {$notify aud/audience pes/(unit presence)} :< our presence update
359 {$naming aud/audience man/human} :< our name update
364`%notify`: Sets the user's presence in the audience circles to `pes`. A good client will automatically set these based on the user's activity. (`%talk` on typing, `%idle` on idle, `%gone` on sign-off.)
366`%naming`: Sets the user's name (handle and real name) for the given audience. Good clients can display these in place of ship names.
368### Changing shared UI
370When the user makes any changes to shared UI elements (elements that should persist between clients), this has to be communicated to Hall.
373++ action :> user action
374 $% {$glyph gyf/char aud/audience bin/?} :< un/bind a glyph
375 {$nick who/ship nic/nick} :< new identity
381`%glyph`: Adds or removes a binding of a glyph to an audience.
383`%nick`: Sets a local nickname for a ship. An empty nickname `''` means the ship has no nickname.
385### Miscellaneous changes
388++ action :> user action
389 $% {$public add/? cir/circle} :< show/hide membership
394`%public`: Adds or removes a circle to/from the user's public membership list.
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