11This document describes the different interfaces Hall provides and the data that is accessible and modifyable through them. Knowledge of the Urbit application model (including [new gall](gall.md)) and #[Hall's architecture](architecture.md) 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 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 ncikname. A `nic`kname 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 actually 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, 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.
184A 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`.
188 $% $: $circle :> story query
189 nom/naem :< circle name
190 wer/(unit circle) :< from source
191 wat/(set circle-data) :< data to get
192 ran/range :< query duration
196++ circle-data :> kinds of circle data
197 $? $grams :< messages
198 $group-l :< local presence
199 $group-r :< remote presences
200 $config-l :< local config
201 $config-r :< remote configs
203++ range :> inclusive msg range
204 %- unit :< ~ means everything
205 $: hed/place :< start of range
206 tal/(unit place) :< opt end of range
208++ place :> range indicators
210 {$ud @ud} :< message number
214Query paths are structured as follows:
217/circle/[circle-name]/(from-circle)/[what/data]/(range-start(/range-end))
218(from-circle) : optional message source, ~ship/circle
219[what/data] : one or more of grams, group, group-l, group-r,
220 : config, config-l, config-r, combined using /
221(range) : an optional range with an optional end, its points denoted
222 : in either message number (@ud) or date (@da)
228:> get all messages from circle %urbit-meta
229/circle/urbit-meta/grams
230:> get all messages, all presences and local configs from %urbit-meta
231/circle/urbit-meta/grams/group/config-l
232:> get all messages %urbit-meta has heard from its source ~zod/fora
233/circle/urbit-meta/~zod/fora/grams
234:> get the first 100 messages from %urbit-meta
235/circle/urbit-meta/grams/0/99
236:> get the first 100 messages %urbit-meta has heard from its source ~zod/fora
237/circle/urbit-meta/~zod/fora/grams/0/99
238:> get all messages from %urbit-meta, starting now
239/circle/urbit-meta/grams/group/(scow %da now)
240:> get all messages from %urbit-meta, starting now, ending at the 100th message
241/circle/urbit-meta/grams/(scow %da now)/99
242:> get local presences from %urbit-meta for a week
243/circle/urbit-meta/group-l/(scow %da now)/(scow %da (add now ~d7))
248Contains (where applicable) messages in envelopes (with message numbers), local and remote configurations and presences.
251++ prize :> query result
252 $% {$circle package} :< /circle
255++ package :> story state
256 $: nes/(list envelope) :< messages
257 cos/lobby :< loc & rem configs
258 pes/crowd :< loc & rem presences
264Contains 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.
266Configuration and status changes specify the circle they apply to.
269++ rumor :> query result change
270 $% {$circle rum/rumor-story} :< /circle
273++ rumor-story :> story rumor
274 $% {$new cof/config} :< new story
275 {$gram src/circle nev/envelope} :< new/changed message
276 {$config cir/circle dif/diff-config} :< new/changed config
277 {$status cir/circle who/ship dif/diff-status} :< new/changed status
278 {$remove $~} :< removed story
280++ diff-config :> config change
281 $% {$full cof/config} :< set w/o side-effects
282 {$source add/? src/source} :< add/rem sources
283 {$caption cap/cord} :< changed description
284 {$filter fit/filter} :< changed filter
285 {$secure sec/security} :< changed security
286 {$permit add/? sis/(set ship)} :< add/rem to b/w-list
287 {$remove $~} :< removed config
289++ diff-status :> status change
290 $% {$full sat/status} :< fully changed status
291 {$presence pec/presence} :< changed presence
292 {$human dif/diff-human} :< changed name
293 {$remove $~} :< removed status
295++ diff-human :> name change
296 $% {$full man/human} :< fully changed name
297 {$handle han/(unit cord)} :< changed handle
298 {$true tru/(unit truename)} :< changed true name
305Actions 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`.
307### Circle configuration
309Since all of these apply to a specific circle, they all specify a name `nom` of the circle to operate on.
312++ action :> user action
313 $% {$create nom/naem des/cord sec/security} :< create circle
314 {$delete nom/naem why/(unit cord)} :< delete + announce
315 {$depict nom/naem des/cord} :< change description
316 {$filter nom/naem fit/filter} :< change message rules
317 {$permit nom/naem inv/? sis/(set ship)} :< invite/banish
318 {$source nom/naem sub/? srs/(set source)} :< un/sub to/from src
323`%create`: Creates a circle with description `des` and security mode `sec`. If this mode is a whitelist, the user is automatically added to it.
325`%delete`: Deletes the circle. If a reason `why` is provided, posts that as the last message to the circle before deleting it.
327`%depict`: Set the description of the circle to `des`.
329`%filter`: Set the filter (message sanitation rules) for the circle to `fit`.
331`%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.
333`%source`: Add or remove sources to/from the circle, un/subscribing it to/from the `grams`, `group-l` and `config-l` each one.
337There 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.
340++ action :> user action
341 $% {$convey tos/(list thought)} :< post exact
342 {$phrase aud/audience ses/(list speech)} :< post easy
347`%convey`: Sends the thoughts to their audiences.
349`%phrase`: Turns the speeches into thoughts by applying sane defaults for metadata (auto-generated `uid`, `now` for `wen`), and then sends those thoughts.
353These concern the presence users have in circles they are participating in.
356++ action :> user action
357 $% {$notify aud/audience pes/(unit presence)} :< our presence update
358 {$naming aud/audience man/human} :< our name update
363`%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.)
365`%naming`: Sets the user's name (handle and real name) for the given audience. Good clients can display these in place of ship names.
367### Changing shared UI
369When the user makes any changes to shared UI elements (elements that should persist between clients), this has to be communicated to Hall.
372++ action :> user action
373 $% {$glyph gyf/char aud/audience bin/?} :< un/bind a glyph
374 {$nick who/ship nic/nick} :< new identity
380`%glyph`: Adds or removed a binding of a glyph to an audience.
382`%nick`: Sets a local nickname for a ship. An empty nickname `''` means the ship has no nickname.
384### Miscellaneous changes
387++ action :> user action
388 $% {$public add/? cir/circle} :< show/hide membership
393`%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