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`.
19 - [/client prize](#client-prize)
20 - [/client rumor](#client-rumor)
22 - [/public prize](#public-prize)
23 - [/public rumor](#public-rumor)
25 - [/peers prize](#peers-prize)
26 - [/peers rumor](#peers-rumor)
28 - [/circle prize](#circle-prize)
29 - [/circle rumor](#circle-rumor)
31 - [Circle configuration](#circle-configuration)
32 - [Messaging](#messaging)
33 - [Personal metadata](#personal-metadata)
34 - [Changing shared UI](#changing-shared-ui)
35 - [Miscellaneous changes](#miscellaneous-changes)
39Queries 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.
43To 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.
47 $% {$client $~} :< shared ui state
61Contains a map of glyphs and the audiences that they map to, as well as a map of ships and their locally set nicknames.
64++ prize :> query result
65 $% {$client prize-client} :< /client
68++ prize-client :> shared ui state
69 $: gys/(jug char audience) :< glyph bindings
70 nis/(map ship nick) :< local nicknames
76Contains 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.
79++ rumor :> query result change
80 $% {$client rum/rumor-client} :< /client
83++ rumor-client :< changed ui state
84 $% {$glyph diff-glyph} :< un/bound glyph
85 {$nick diff-nick} :< changed nickname
87++ diff-glyph {bin/? gyf/char aud/audience} :< un/bound glyph
88++ diff-nick {who/ship nic/nick} :< changed nickname
94To 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.
98 $% {$public $~} :< public memberships
106:> all public memberships
112Contains the set of circles the user has on their public list.
115++ prize :> query result
116 $% {$public cis/(set circle)} :< /public
123Contains a circle that was either added or removed from the public list.
126++ rumor :> query result change
127 $% {$public add/? cir/circle} :< /public
134To allow a circle owner to inspect who is currently subscribed to their stories, they can issue a query to retrieve subscription data.
138 $% {$peers nom/naem} :< readers of story
143Query paths are structured as follows:
152:> peers for circle %urbit-meta
158Contains a map of ships and the different queries they currently have active for the selected story.
161++ prize :> query result
162 $% {$peers pes/(jar ship query)} :< /peers
169Contains a ship and a query, and a flag to indicate whether that subscription has started or ended.
172++ rumor :> query result change
173 $% {$peers add/? who/ship qer/query} :< /peers
180Circle 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.
183A 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`.
187 $% $: $circle :> story query
188 nom/naem :< circle name
189 wer/(unit circle) :< from source
190 wat/(set circle-data) :< data to get
191 ran/range :< query duration
195++ circle-data :> kinds of circle data
196 $? $grams :< messages
197 $group-l :< local presence
198 $group-r :< remote presences
199 $config-l :< local config
200 $config-r :< remote configs
202++ range :> inclusive msg range
203 %- unit :< ~ means everything
204 $: hed/place :< start of range
205 tal/(unit place) :< opt end of range
207++ place :> range indicators
209 {$ud @ud} :< message number
213Query paths are structured as follows:
216/circle/[circle-name]/(from-circle)/[what/data]/(range-start(/range-end))
217(from-circle) : optional message source, ~ship/circle
218[what/data] : one or more of grams, group, group-l, group-r,
219 : config, config-l, config-r, combined using /
220(range) : an optional range with an optional end, its points denoted
221 : in either message number (@ud) or date (@da)
227:> get all messages from circle %urbit-meta
228/circle/urbit-meta/grams
229:> get all messages, all presences and local configs from %urbit-meta
230/circle/urbit-meta/grams/group/config-l
231:> get all messages %urbit-meta has heard from its source ~zod/fora
232/circle/urbit-meta/~zod/fora/grams
233:> get the first 100 messages from %urbit-meta
234/circle/urbit-meta/grams/0/99
235:> get the first 100 messages %urbit-meta has heard from its source ~zod/fora
236/circle/urbit-meta/~zod/fora/grams/0/99
237:> get all messages from %urbit-meta, starting now
238/circle/urbit-meta/grams/group/(scow %da now)
239:> get all messages from %urbit-meta, starting now, ending at the 100th message
240/circle/urbit-meta/grams/(scow %da now)/99
241:> get local presences from %urbit-meta for a week
242/circle/urbit-meta/group-l/(scow %da now)/(scow %da (add now ~d7))
247Contains (where applicable) messages in envelopes (with message numbers), as well as local and remote configurations and presences.
250++ prize :> query result
251 $% {$circle package} :< /circle
254++ package :> story state
255 $: nes/(list envelope) :< messages
256 cos/lobby :< loc & rem configs
257 pes/crowd :< loc & rem presences
263Contains a detailed change description of the data relevant to the query that changed.
265Messages 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.
268++ rumor :> query result change
269 $% {$circle rum/rumor-story} :< /circle
272++ rumor-story :> story rumor
273 $% {$new cof/config} :< new story
274 {$gram src/circle nev/envelope} :< new/changed message
275 {$config cir/circle dif/diff-config} :< new/changed config
276 {$status cir/circle who/ship dif/diff-status} :< new/changed status
277 {$remove $~} :< removed story
279++ diff-config :> config change
280 $% {$full cof/config} :< set w/o side-effects
281 {$source add/? src/source} :< add/rem sources
282 {$caption cap/cord} :< changed description
283 {$filter fit/filter} :< changed filter
284 {$secure sec/security} :< changed security
285 {$permit add/? sis/(set ship)} :< add/rem to b/w-list
286 {$remove $~} :< removed config
288++ diff-status :> status change
289 $% {$full sat/status} :< fully changed status
290 {$presence pec/presence} :< changed presence
291 {$human dif/diff-human} :< changed name
292 {$remove $~} :< removed status
294++ diff-human :> name change
295 $% {$full man/human} :< fully changed name
296 {$handle han/(unit cord)} :< changed handle
297 {$true tru/(unit truename)} :< changed true name
304Actions 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`.
306### Circle configuration
308Since all of these apply to a specific circle, they all specify a name `nom` of the circle to operate on.
311++ action :> user action
312 $% {$create nom/naem des/cord sec/security} :< create circle
313 {$delete nom/naem why/(unit cord)} :< delete + announce
314 {$depict nom/naem des/cord} :< change description
315 {$filter nom/naem fit/filter} :< change message rules
316 {$permit nom/naem inv/? sis/(set ship)} :< invite/banish
317 {$source nom/naem sub/? srs/(set source)} :< un/sub to/from src
322`%create`: Creates a circle with description `des` and security mode `sec`. If this mode is a whitelist, the user is automatically added to it.
324`%delete`: Deletes the circle. If a reason `why` is provided, posts that as the last message to the circle before deleting it.
326`%depict`: Set the description of the circle to `des`.
328`%filter`: Set the filter (message sanitation rules) for the circle to `fit`.
330`%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.
332`%source`: Add or remove sources to/from the circle, un/subscribing it to/from the `grams`, `group-l` and `config-l` each one.
336There 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.
339++ action :> user action
340 $% {$convey tos/(list thought)} :< post exact
341 {$phrase aud/audience ses/(list speech)} :< post easy
346`%convey`: Sends the thoughts to their audiences.
348`%phrase`: Turns the speeches into thoughts by applying sane defaults for metadata (auto-generated `uid`, `now` for `wen`), and then sends those thoughts.
352These concern the presence users have in circles they are participating in.
355++ action :> user action
356 $% {$notify aud/audience pes/(unit presence)} :< our presence update
357 {$naming aud/audience man/human} :< our name update
362`%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.)
364`%naming`: Sets the user's name (handle and real name) for the given audience. Good clients can display these in place of ship names.
366### Changing shared UI
368When the user makes any changes to shared UI elements (elements that should persist between clients), this has to be communicated to Hall.
371++ action :> user action
372 $% {$glyph gyf/char aud/audience bin/?} :< un/bind a glyph
373 {$nick who/ship nic/nick} :< new identity
378`%glyph`: Adds or removes a binding of a glyph to an audience.
380`%nick`: Sets a local nickname for a ship. An empty nickname `''` means the ship has no nickname.
382### Miscellaneous changes
385++ action :> user action
386 $% {$public add/? cir/circle} :< show/hide membership
391`%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