4This 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.
6While 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`.
13 * [/client prize](#client-prize)
14 * [/client rumor](#client-rumor)
16 * [/public prize](#public-prize)
17 * [/public rumor](#public-rumor)
19 * [/peers prize](#peers-prize)
20 * [/peers rumor](#peers-rumor)
22 * [/circle prize](#circle-prize)
23 * [/circle rumor](#circle-rumor)
25 * [Circle configuration](#circle-configuration)
26 * [Messaging](#messaging)
27 * [Personal metadata](#personal-metadata)
28 * [Changing shared UI](#changing-shared-ui)
29 * [Miscellaneous changes](#miscellaneous-changes)
34Queries 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.
38To 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.
42 $% {$client $~} :< shared ui state
56Contains a map of glyphs and the audiences they map to, as well as a map of ships and their locally set nicknames.
59++ prize :> query result
60 $% {$client prize-client} :< /client
63++ prize-client :> shared ui state
64 $: gys/(jug char audience) :< glyph bindings
65 nis/(map ship nick) :< local nicknames
71Contains 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.
74++ rumor :> query result change
75 $% {$client rum/rumor-client} :< /client
78++ rumor-client :< changed ui state
79 $% {$glyph diff-glyph} :< un/bound glyph
80 {$nick diff-nick} :< changed nickname
82++ diff-glyph {bin/? gyf/char aud/audience} :< un/bound glyph
83++ diff-nick {who/ship nic/nick} :< changed nickname
89To 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.
93 $% {$public $~} :< public memberships
101:> all public memberships
107Contains the set of circles the user has on their public list.
110++ prize :> query result
111 $% {$public cis/(set circle)} :< /public
118Contains a circle that was either added or removed from the public list.
121++ rumor :> query result change
122 $% {$public add/? cir/circle} :< /public
129To allow a circle owner to inspect who is actually currently subscribed to their stories, they can issue a query to retrieve subscription data.
133 $% {$peers nom/naem} :< readers of story
138Query paths are structured as follows:
147:> peers for circle %urbit-meta
153Contains a map of ships and the different queries they currently have active for the selected story.
156++ prize :> query result
157 $% {$peers pes/(jar ship query)} :< /peers
164Contains a ship and a query, and a flag to indicate whether that subscription has started or ended.
167++ rumor :> query result change
168 $% {$peers add/? who/ship qer/query} :< /peers
175Circle 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.
177A 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`.
181 $% $: $circle :> story query
182 nom/naem :< circle name
183 wer/(unit circle) :< from source
184 wat/(set circle-data) :< data to get
185 ran/range :< query duration
189++ circle-data :> kinds of circle data
190 $? $grams :< messages
191 $group-l :< local presence
192 $group-r :< remote presences
193 $config-l :< local config
194 $config-r :< remote configs
196++ range :> inclusive msg range
197 %- unit :< ~ means everything
198 $: hed/place :< start of range
199 tal/(unit place) :< opt end of range
201++ place :> range indicators
203 {$ud @ud} :< message number
207Query paths are structured as follows:
210/circle/[circle-name]/(from-circle)/[what/data]/(range-start(/range-end))
211(from-circle) : optional message source, ~ship/circle
212[what/data] : one or more of grams, group, group-l, group-r,
213 : config, config-l, config-r, combined using /
214(range) : an optional range with an optional end, its points denoted
215 : in either message number (@ud) or date (@da)
221:> get all messages from circle %urbit-meta
222/circle/urbit-meta/grams
223:> get all messages, all presences and local configs from %urbit-meta
224/circle/urbit-meta/grams/group/config-l
225:> get all messages %urbit-meta has heard from its source ~zod/fora
226/circle/urbit-meta/~zod/fora/grams
227:> get the first 100 messages from %urbit-meta
228/circle/urbit-meta/grams/0/99
229:> get the first 100 messages %urbit-meta has heard from its source ~zod/fora
230/circle/urbit-meta/~zod/fora/grams/0/99
231:> get all messages from %urbit-meta, starting now
232/circle/urbit-meta/grams/group/(scow %da now)
233:> get all messages from %urbit-meta, starting now, ending at the 100th message
234/circle/urbit-meta/grams/(scow %da now)/99
235:> get local presences from %urbit-meta for a week
236/circle/urbit-meta/group-l/(scow %da now)/(scow %da (add now ~d7))
241Contains (where applicable) messages in envelopes (with message numbers), local and remote configurations and presences.
244++ prize :> query result
245 $% {$circle package} :< /circle
248++ package :> story state
249 $: nes/(list envelope) :< messages
250 cos/lobby :< loc & rem configs
251 pes/crowd :< loc & rem presences
257Contains a detailed change description of the data relevant to the query that changed.
258Messages are wrapped in envelopes to include their sequence number, and note the source they were heard from.
259Configuration and status changes specify the circle they apply to.
262++ rumor :> query result change
263 $% {$circle rum/rumor-story} :< /circle
266++ rumor-story :> story rumor
267 $% {$new cof/config} :< new story
268 {$gram src/circle nev/envelope} :< new/changed message
269 {$config cir/circle dif/diff-config} :< new/changed config
270 {$status cir/circle who/ship dif/diff-status} :< new/changed status
271 {$remove $~} :< removed story
273++ diff-config :> config change
274 $% {$full cof/config} :< set w/o side-effects
275 {$source add/? src/source} :< add/rem sources
276 {$caption cap/cord} :< changed description
277 {$filter fit/filter} :< changed filter
278 {$secure sec/security} :< changed security
279 {$permit add/? sis/(set ship)} :< add/rem to b/w-list
280 {$remove $~} :< removed config
282++ diff-status :> status change
283 $% {$full sat/status} :< fully changed status
284 {$presence pec/presence} :< changed presence
285 {$human dif/diff-human} :< changed name
286 {$remove $~} :< removed status
288++ diff-human :> name change
289 $% {$full man/human} :< fully changed name
290 {$handle han/(unit cord)} :< changed handle
291 {$true tru/(unit truename)} :< changed true name
298Actions 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`.
300### Circle configuration
302Since all of these apply to a specific circle, they all specify a name `nom` of the circle to operate on.
305++ action :> user action
306 $% {$create nom/naem des/cord sec/security} :< create circle
307 {$delete nom/naem why/(unit cord)} :< delete + announce
308 {$depict nom/naem des/cord} :< change description
309 {$filter nom/naem fit/filter} :< change message rules
310 {$permit nom/naem inv/? sis/(set ship)} :< invite/banish
311 {$source nom/naem sub/? srs/(set source)} :< un/sub to/from src
316`%create`: Creates a circle with description `des` and security mode `sec`. If this mode is a whitelist, the user is automatically added to it.
318`%delete`: Deletes the circle. If a reason `why` is provided, posts that as the last message to the circle before deleting it.
320`%depict`: Set the description of the circle to `des`.
322`%filter`: Set the filter (message sanitation rules) for the circle to `fit`.
324`%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.
326`%source`: Add or remove sources to/from the circle, un/subscribing it to/from the `grams`, `group-l` and `config-l` each one.
330There 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.
333++ action :> user action
334 $% {$convey tos/(list thought)} :< post exact
335 {$phrase aud/audience ses/(list speech)} :< post easy
340`%convey`: Sends the thoughts to their audiences.
342`%phrase`: Turns the speeches into thoughts by applying sane defaults for metadata (auto-generated `uid`, `now` for `wen`), and then sends those thoughts.
346These concern the presence users have in circles they are participating in.
349++ action :> user action
350 $% {$notify aud/audience pes/(unit presence)} :< our presence update
351 {$naming aud/audience man/human} :< our name update
356`%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.)
358`%naming`: Sets the user's name (handle and real name) for the given audience. Good clients can display these in place of ship names.
360### Changing shared UI
362When the user makes any changes to shared UI elements (elements that should persist between clients), this has to be communicated to Hall.
365++ action :> user action
366 $% {$glyph gyf/char aud/audience bin/?} :< un/bind a glyph
367 {$nick who/ship nic/nick} :< new identity
373`%glyph`: Adds or removed a binding of a glyph to an audience.
375`%nick`: Sets a local nickname for a ship. An empty nickname `''` means the ship has no nickname.
377### Miscellaneous changes
380++ action :> user action
381 $% {$public add/? cir/circle} :< show/hide membership
386`%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