Design discussion: Declarative scheme config

[pascalkuthe]

While the fundamental implementation of our scheme config will be build around something like :set I want to offer a more declarative config syntax that more closely resembles the current toml config.

The declarative config should smoothly allow incorporating lambdas and programmatically defined values so you can still use a declarative config with a scripted config.

Syntax wise I quite like what gnu guile does. I will maintain a version of what I want the config to look like that I will keep updated. This is not a final version yet (hence its a discussion) so this can definitely change with time and nothing is final yet.

I will first show off an example that shows off all features and then add some explanation afterward (hopefully some of this can be turned into docs later)

Main Config (currently under editor.*)

(defn (custom-gutter cx) /* palceholder /)
(config 
  (auto-format #t)
  (jump-label-alphabet "eirsaotndhfuywgm(cplbjvkx)z_")
  (line-number relative)
  (soft-wrap 
    (enable #t)
    (wrap-indicator ""))
  (indent-guides.enable #t)
  (gutters diagnostics spacer line-numbers spacer diff spacer custom-gutter)
  (status-line.right+  version-control)
  (status-line.right-  file-line-ending))

config is a macro that allows declaratively setting editor configuration. It will essentially expand to a bunch of :set calls. While (config) accepts an arbitrary number of arguments this is just syntactic sugar and exactly the same as writing this out manually. Specifically the following two configs are equivalent:

(config 
  (auto-format #t)
  (jump-label-alphabet "eirsaotndhfuywgm(cplbjvkx)z_"))

(config (auto-format #t))
(config (jump-label-alphabet "eirsaotndhfuywgm(cplbjvkx)z_"))

Enumerations/String Constants

Some config options like line-number only accept a limited set of values (usually these are string enumerations in rust). These options are represented as strings in the config system (already the case). So the following two configs are equivalent:

(config (line-number relative))

(config (line-number "relative"))

The former syntax is syntactic sugar enabled by the macro (a manual set call needs to use a string literal). This syntactic sugar is enabled for two reasons:

• keep the config terse and easy to read
• these constants can be suggested by an lsp

I expect these to work as follows:

The macro would expand (line-number relative) to

(set-config "line-number" (let (relative "relative") (absolute "absolute") relative))

these let bindings allow the use of an identifier instead of literals. Since this is normal macro expansion a good lsp (implemented similarly to RA) could do this expansion, parse the let bindings and to autocomplete based on that. Alternatively we can just build the macro into the language servers (same way RA has support for macros builtin). The latter option is probably both easier to implement and will yield better results.

A couple points about this

• you may notice that "line-number" turned into a literal here quite similarly to what happened to "relative". I am not sure if we may also want to achieve this with local let bindings (that would pollute the scope with a let binding for every config option). It would also require defining every config option in scheme (more on that in the next point). Instead we should just turn these values into strings and handle autcompletions with custom lsp support
• these values are hard-coded in scheme essentially duplication large parts of our config. I think a better approach (and again requiring hard-coded support for every config option). I hope that our scheme implementation will let us define a macro using the rust interface where we can query the config system for possible values (and the create these let bindings programmatically)

nested configs

The config system does not have a notion of nested config options like toml does. What is currently a nested config options (like soft-wrap.enable) will simply have the its full path as its name (so soft-wrap is not a map that contains enable and wrap-indicator but instead soft-wrap.enable and soft-wrap.wrap-indicator are just two seprate options).

So its always possible to set them using the qualified path like in toml.

(config (indent-guides.enable #t))

Additionally the config macro offers convenience syntax for setting multiple nested/related config at once. For example the following two configs are equivalent

(config 
  (soft-wrap 
    (enable #t)
    (wrap-indicator ""))

(config 
  (soft-wrap.enable #t)
  (soft-wrap.wrap-indicator ""))

Lists

We use lispy syntax so config options that accept a list of values are defined by just adding more values.

(config (gutters diagnostics spacer line-numbers spacer diff spacer custom-gutter))

Additionally config options that accept lists can append to the currently defined value (either in a different set command, or for example a workspace config can append to the global config). While this will be handeled by a flag with set the macro allows this by simply postfixing a + to the name. For example:

(config 
  (status-line.left+  version-control))

Keymap

A keymap is defined by (keymap ...). There will be an equivalent of keymap so it will be possible to set mappings programmatically too and then (keymap) will msotly just expand to that.

The first argument of the keymap is the mode you want edit. Usally that will be normal, select or insert but you can also define your own custom modes. By default keymap will append/merge the keymap but you can use (keymap! to forcefully overwrite a map). Inside a keymap macro you can also postfix a binding with ! to overwrite instead of merging.

(keymap goto ((sticky #t) (show-help #f)) 
  (h extend-to-line-start label "Goto line start") )
  (l "@t<ret>" (label "Goto line end")))

(keymap my-mode (label "hello world")
   (x move-line-up move-word-end))

(defn my-move-line-up (cx) 
  (if (!= (command-count cx) 0) 
    (move-line-up cx) 
    (move-visual-line_up cx)))

(keymap normal ()
   (= write-buffer)
   (k my-move-line-up)
   (space! (label "Leader")
     (x (fn (cx) (sh "rm foo"))))
   (X keymap->my-mode)
   (")" keymap-unimpaired-rev)
   ("]" null))


(display keymap->normal)

(this example is purpusfully complex to show off all features a real keymap would usually be simpler)

TODO document details

[gyreas]

I don't understand why there's a need for defn and fn to take the context as argument explicitly since they'll be reading/writing its 'fields'. Why not expose those directly since the editor context is global?
So that

(defn my-move-line-up (cx) 
  (if (!= cx->count 0) 
    (move-line-up cx) 
    (move-visual-line_up cx)))

becomes

(defn my-move-line-up ()
  (if (!= .count 0) 
    (move-line-up) 
    (move-visual-line_up)))

whereas
(x (fn (cx) (sh "rm foo"))) becomes (x (fn () (sh "rm foo"))).

I imagine the need for that to be context-awareness since the editor isn't the only 'context', there are other elements f.e. completion, picker etc, since the commands/functions are contextual (ie their behaviour is vary depending on their target) f.e. move-line-up may go up one line in the editor view or in the picker.

Am I misunderstanding anything here?

[pascalkuthe]

hmm I do like having implicit context for things that are essentially implementation details like compositor or editor and that should be (given sufficient refactors in core) available everywhere.

But for command-count and command-register I would like there to be an explicit context. Let me try to explain:

• these are explicit "arguments" that are passed to a (keymap) function and not some kind of "execution context". I really wanted the rest of the command context to be global since these are implementation details.
• I want keymap functions to be callable from everywhere (like moving the cursor a line down from a hook). That means you should be able to construct your own context/copy and modify it. If these were global there would be a mutable global count and register variable. I think (user visible) mutable state is generally an anti-pattern and it would be too easy to get tripped up by some old count value that was set somewhere and not properly reset (we had bugs like that before where a command changed the register and then forgot to reset it causing other commands to misbehave).

Hope that reasoning make sense. Sorry if I wasn't super clear about that before. I think you efforts still make sense since I do think editor, compositor, ... should behave like that. And for a first prototype we can also just stick with what you have right now. This is meant as a "this is where I want to be in the longterm" thread

[mattwparas]

I think I understand - let me try to reiterate it in my own words to confirm we're on the same page:

There is a notion of a general context (in this case, that would be the compositor context), and then for keybinding functions there are optionally additional things passed in at the callsite when it happens? Those things are then more or less immutable values, and these only apply to keybinding commands, not typed command?

[pascalkuthe]

Yeah that sounds right

[gyreas]

Essentially, to each keymap/command its own context (cloned from the global one), am I on track here?

If so, I still think making it implicit is not against what you're suggesting. Here, since the context has to be localized to each "client" (we can dichotomise here) so as to avoid global user-facing mutable state, we can clone (the necessary part of)that state under the hood -- which we're going to do anyway, and let the user deal with that.
There are internal mechanisms such as compositor whose state are global, which can be updated by allowed mechanism, this is the one hand. My proposition can extend to them but not necessarity since they're often internal.

All in all, I'm arguing for the simplicy of the syntax in this aspect.

PS: Are we deciding/designing steel's syntax here or something else?

[pascalkuthe]

I don't think you understand what exactly I am staying here. The cx argument is not somekind of state or execution context and thr keymap functions are not special functions.

Keymappings are functions which require two values:

• the register they should use
• the count (number of repetitions)

In fact I considered just making it (defn (move-line-up count register) ...).

If you want to call these functions from a hook you just pass some values (like say you want to create a keymap to move 3 lines down you would do (move-line-dow (command-ctx (count 3))) for example.

If you allow accessing count without a cx variable by making it an implicit global you need to also allow setting it.

Then the following will almost certainly happen:

(set! command-count 3)
(move-line-down)
; do something else 
(delete-selection) ; we forgot to set count here so now we delete too much

In fact we already had a bug exactly like that in helix in the past.

I find passing arguments to functions as globals just bad form. That should only be done for singletons (like the compositor context Mathew was talking about).

[gabydd]

Just two small things I can think of right now I would think things like cx->count would have to be functions so to get there value you would have to do (!= (cx->count) 0)(cc @mattwparas) (edit I see this is being discussed in the other thread). Also if we have add do we want subtract like you proposed in the config RFC?

[pascalkuthe]

yeah that was a bit async but totally a brain fart on my side. This post was already pretty long and I needed to do something else so I rushed s bit at the end.

Yeah we probably want subtract too good point