Add Steel as an optional plugin system

[mattwparas]

Notes:

• I still need to rebase up with the latest master changes, however doing so causes some headache with the lock file, so I'll do it after some initial feedback. Also, this depends on the event system in Add an event system #8021.
• The large diff size is a combination of lock file changes + the dependency on the event system PR. The diff has ended up quite large with all of the other stuff
• I'm currently pointing to the master branch of steel as a dependency. This will point to a stable release on crates once I cut a release.

---

Opening this just to track progress on the effort and gather some feedback. There is still work to be done but I would like to gather some opinions on the direction before I continue more.

You can see my currently functioning helix config here and there are instructions listed in the STEEL.md file. The main repo for steel lives here, however much documentation is in works and will be added soon.

The bulk of the implementation lies in the engine.rs and scheme.rs files.

Design

Given prior conversation about developing a custom language implementation, I attempted to make the integration with Steel as agnostic of the engine as possible to keep that door open.

The interface I ended up with (which is subject to change and would love feedback on) is the following:

pub trait PluginSystem {
    /// If any initialization needs to happen prior to the initialization script being run,
    /// this is done here. This is run before the context is available.
    fn initialize(&self) {}

    fn engine_name(&self) -> PluginSystemKind;

    /// Post initialization, once the context is available. This means you should be able to
    /// run anything here that could modify the context before the main editor is available.
    fn run_initialization_script(&self, _cx: &mut Context) {}

    /// Allow the engine to directly handle a keymap event. This is some of the tightest integration
    /// with the engine, directly intercepting any keymap events. By default, this just delegates to the
    /// editors default keybindings.
    #[inline(always)]
    fn handle_keymap_event(
        &self,
        _editor: &mut ui::EditorView,
        _mode: Mode,
        _cxt: &mut Context,
        _event: KeyEvent,
    ) -> Option<KeymapResult> {
        None
    }

    /// This attempts to call a function in the engine with the name `name` using the args `args`. The context
    /// is available here. Returns a bool indicating whether the function exists or not.
    #[inline(always)]
    fn call_function_if_global_exists(
        &self,
        _cx: &mut Context,
        _name: &str,
        _args: &[Cow<str>],
    ) -> bool {
        false
    }

    /// This is explicitly for calling a function via the typed command interface, e.g. `:vsplit`. The context here
    /// that is available is more limited than the context available in `call_function_if_global_exists`. This also
    /// gives the ability to handle in progress commands with `PromptEvent`.
    #[inline(always)]
    fn call_typed_command_if_global_exists<'a>(
        &self,
        _cx: &mut compositor::Context,
        _input: &'a str,
        _parts: &'a [&'a str],
        _event: PromptEvent,
    ) -> bool {
        false
    }

    /// Given an identifier, extract the documentation from the engine.
    #[inline(always)]
    fn get_doc_for_identifier(&self, _ident: &str) -> Option<String> {
        None
    }

    /// Fuzzy match the input against the fuzzy matcher, used for handling completions on typed commands
    #[inline(always)]
    fn available_commands<'a>(&self) -> Vec<Cow<'a, str>> {
        Vec::new()
    }

    /// Retrieve a theme for a given name
    #[inline(always)]
    fn load_theme(&self, _name: &str) -> Option<Theme> {
        None
    }

    /// Retrieve the list of themes that exist within the runtime
    #[inline(always)]
    fn themes(&self) -> Option<Vec<String>> {
        None
    }

    /// Fetch the language configuration as monitored by the plugin system.
    ///
    /// For now - this maintains backwards compatibility with the existing toml configuration,
    /// and as such the toml error is exposed here.
    #[inline(always)]
    fn load_language_configuration(&self) -> Option<Result<Configuration, toml::de::Error>> {
        None
    }
}

If you can implement this, the engine should be able to be embedded within Helix. On top of that, I believe what I have allows the coexistence of multiple scripting engines, with a built in priority for resolving commands / configurations / etc.

As a result, Steel here is entirely optional and also remains completely backwards compatible with the existing toml configuration. Steel is just another layer on the existing configuration chain, and as such will be applied last. This applies to both the config.toml and the languages.toml. Keybindings can be defined via Steel as well, and these can be buffer specific, language specific, or global. Themes can also be defined from Steel code and enabled, although this is not as rigorously tested and is a relatively recent addition. Otherwise, I have been using this as my daily driver to develop for the last few months.

I opted for a two tiered approach, centered around a handful of design ideas that I'd like feedback on:

The first, there is a init.scm and a helix.scm file - the helix.scm module is where you define any commands that you would like to use at all. Any function exposed via that module is eligible to be used as a typed command or via a keybinding. For example:

;; helix.scm

(provide shell)

;;@doc
;; Specialized shell - also be able to override the existing definition, if possible.
(define (shell cx . args)
  ;; Replace the % with the current file
  (define expanded (map (lambda (x) (if (equal? x "%") (current-path cx) x)) args))
  (helix.run-shell-command cx expanded helix.PromptEvent::Validate))

This would then make the command :shell available, and it will just replace the % with the current file. The documentation listed in the @doc doc comment will also pop up explaining what the command does:

Once the helix.scm module is require'd - then the init.scm file is run. One thing to note is that the helix.scm module does not have direct access to a running helix context. It must act entirely stateless of anything related to the helix context object. Running init.scm gives access to a helix object, currently defined as *helix.cx*. This is something I'm not sure I particularly love, as it makes async function calls a bit odd - I think it might make more sense to make the helix context just a global inside of a module. This would also save the hassle that every function exposed has to accept a cx parameter - this ends up with a great deal of boilerplate that I don't love. Consider the following:

;;@doc
;; Create a file under wherever we are
(define (create-file cx)
  (when (currently-in-labelled-buffer? cx FILE-TREE)
    (define currently-selected (list-ref *file-tree* (helix.static.get-current-line-number cx)))
    (define prompt
      (if (is-dir? currently-selected)
          (string-append "New file: " currently-selected "/")
          (string-append "New file: "
                         (trim-end-matches currently-selected (file-name currently-selected)))))

    (helix-prompt!
     cx
     prompt
     (lambda (cx result)
       (define file-name (string-append (trim-start-matches prompt "New file: ") result))
       (temporarily-switch-focus cx
                                 (lambda (cx)
                                   (helix.vsplit-new cx '() helix.PromptEvent::Validate)
                                   (helix.open cx (list file-name) helix.PromptEvent::Validate)
                                   (helix.write cx (list file-name) helix.PromptEvent::Validate)
                                   (helix.quit cx '() helix.PromptEvent::Validate)))

       (enqueue-thread-local-callback cx refresh-file-tree)))))

Every function call to helix built ins requires passing in the cx object - I think just having them be able to reference the global behind the scenes would make this a bit ergonomic. The integration with the helix runtime would make sure whether that variable actually points to a legal context, since we pass this in via reference, so it is only alive for the duration of the call to the engine.

Async functions

Steel has support for async functions, and has successfully been integrated with the tokio runtime used within helix, however it requires constructing manually the callback function yourself, rather than elegantly being able to use something like await. More to come on this, since the eventual design will depend on the decision to use a local context variable vs a global one.

Built in functions

The basic built in functions are first all of the function that are typed and static - i.e. everything here:

• Typed
• Static

However, these functions don't return values so aren't particularly useful for anything but their side effects to the editor state. As a result, I've taken the liberty of defining functions as I've needed/wanted them. Some care will need to be decided what those functions actually exposed are.

Examples

Here are some examples of plugins that I have developed using Steel:

File tree

Source can be found here

filetree.webm

Recent file picker

Source can be found here

recent-files.webm

This persists your recent files between sessions.

Scheme indent

Since steel is a scheme, there is a relatively okay scheme indent mode that only applied on .scm files, which can be found here. The implementation requires a little love, but worked enough for me to use helix to write scheme code 😄

Terminal emulator

I did manage to whip up a terminal emulator, however paused the development of it while focusing on other things. When I get it back into working shape, I will post a video of it here. I am not sure what the status is with respect to a built in terminal emulator, but the one I got working did not attempt to do complete emulation, but rather just maintained a shell to interact with non-interactively (e.g. don't try to launch helix in it, you'll have a bad time 😄 )

Steel as a choice for a language

I understand that there is skepticism around something like Steel, however I have been working diligently on improving it. My current projects include shoring up the documentation, and working on an LSP for it to make development easier - but I will do that in parallel with maintaining this PR. If Steel is not chosen and a different language is picked, in theory the API I've exposed should do the trick at least with matching the implementation behavior that I've outlined here.

Pure rust plugins

As part of this, I spent some time trying to expose a C ABI from helix to do rust to rust plugins directly in helix without a scripting engine, with little success. Steel supports loading dylibs over a stable abi (will link to documentation once I've written it). I used this to develop the proof of concept terminal emulator. So, you might not be a huge fan of scheme code, but in theory you can write mostly Rust and use Steel as glue if you'd like - you would just be limited to the abi compatible types.

System compatibility

I develop off of Linux and Mac - but have not tested on windows. I have access to a windows system, and will get around to testing on that when the time comes.

[mattwparas]

How do I get the steel globals required for the LSP to work correctly?

the contents of my globals are:

(define keymaps (#%module "helix/core/keymaps"))

(define (register-values module values)
  (map (lambda (ident) (#%module-add module (symbol->string ident) void)) values))

(register-values keymaps
  '(helix-current-keymap *buffer-or-extension-keybindings*
    *reverse-buffer-map*
    helix-merge-keybindings
    helix-string->keymap
    *global-keybinding-map*
    helix-deep-copy-keymap))

(define typable-commands (#%module "helix/core/typable"))
(define static-commands (#%module "helix/core/static"))
(define editor (#%module "helix/core/editor"))

(register-values typable-commands '())

(define configuration (#%module "helix/core/configuration"))
(define misc (#%module "helix/core/misc"))

(#%ignore-unused-identifier "_")

keymaps

@merisbahti To fix this error, try adding this line to your config:

(#%register-additional-search-path "/Users/matt/.config/helix") ;; Replace this to the path to your helix config

[voidcontext]

It seems, the descriptions is not present anymore for custom keymaps, there's just an "uh oh, couldn't find the thing" message:

[mattwparas]

It seems, the descriptions is not present anymore for custom keymaps, there's just an "uh oh, couldn't find the thing" message:

Sorry about that, must have slipped through the cracks on some refactoring. Will have a fix shortly

This fix is pushed - you'll need the updated cogs/keymaps.scm from my config, and re install helix

[mattwparas]

Just updating with some screenshots of things that now seem to work well:

Custom completion drop down, with arbitrary function on selection:

Custom picker with preview (styling could use some love):

Embedded terminal, now snaps to the side rather than floating:

And a fun one, running a web server from within steel:

[merisbahti]

How do I get the steel globals required for the LSP to work correctly?

the contents of my globals are:

(define keymaps (#%module "helix/core/keymaps"))

(define (register-values module values)
  (map (lambda (ident) (#%module-add module (symbol->string ident) void)) values))

(register-values keymaps
  '(helix-current-keymap *buffer-or-extension-keybindings*
    *reverse-buffer-map*
    helix-merge-keybindings
    helix-string->keymap
    *global-keybinding-map*
    helix-deep-copy-keymap))

(define typable-commands (#%module "helix/core/typable"))
(define static-commands (#%module "helix/core/static"))
(define editor (#%module "helix/core/editor"))

(register-values typable-commands '())

(define configuration (#%module "helix/core/configuration"))
(define misc (#%module "helix/core/misc"))

(#%ignore-unused-identifier "_")

keymaps

@merisbahti To fix this error, try adding this line to your config:

(#%register-additional-search-path "/Users/matt/.config/helix") ;; Replace this to the path to your helix config

I think this might have fixed the problem but exposed another one. When I try to open the ~/.config/helix/helix/configuration.scm I get this error: Error: BadSyntax: require-builtin: module not found: helix/core/configuration

Which makes it feel like the helix-term-modules aren't being picked up.

The way I installed hx, steel, and steel-language-server is by doing a cargo xtask steel on this branch. And from what I can see in helix-term we're adding that module:

helix-term/src/commands/engine/steel.rs:    let mut module = BuiltInModule::new("helix/core/configuration");

The plugins work, so at least steel or helix knows about it - but why does steel-language-server not know about it?

Even more trivially, if I try to look for *helix.cx* in my lsp autocomplete, I can't find *helix.cx*

Which I think I would expect to do since obviously my plugins are making use of *helix.cx* since I can open the embedded terminal in helix using :open-term.

Any ideas why for example *helix.cx* isn't being suggested in this case?

[mattwparas]

Yes, at the moment the steel language server does not know about the bindings provided by the helix runtime. The plan is to have the language server pick up a configuration from helix that does provide the bindings so it at least doesn't show free identifiers for bindings from the built in modules

[mattwparas]

@merisbahti - if you run cargo xtask code-gen - the proper builtins should be configured in the LSP. You no longer need all of what I've put in the globals.scm file, you only need this (of which will also soon be baked in):

(#%register-additional-search-path "/Users/matt/.config/helix")
(#%ignore-unused-identifier "_")

[merisbahti]

@merisbahti - if you run cargo xtask code-gen - the proper builtins should be configured in the LSP. You no longer need all of what I've put in the globals.scm file, you only need this (of which will also soon be baked in):

(#%register-additional-search-path "/Users/matt/.config/helix")
(#%ignore-unused-identifier "_")

Nice! I get a lot better completions in the config directory now! LSP is useful and helps, which is really nice, but it seems like *helix.cx* isn't being suggested in autocomplete, haven't investigated why but this is a great improvement.

[mattwparas]

You shouldn't need to access the global context directly - all relevant functions should reference it for you. Is there a reason you need it?

[merisbahti]

You shouldn't need to access the global context directly - all relevant functions should reference it for you. Is there a reason you need it?

Nope! Works good this way so far!

[mattwparas]

You shouldn't need to access the global context directly - all relevant functions should reference it for you. Is there a reason you need it?

Nope! Works good this way so far!

Globals should be included in the completions now, they weren't getting included before. Thanks for the heads up

[noor-tg]

@mattwparas what is missing from steel to make it official helix plugin manager ?

[Ben-PH]

Just dropping in to say that I would only move on from my neovim when I can say "I'm missing $FUNCTIONALITY" and there is an elegant story to add that functionality. Typically done with plugins, and most likely the solution to this, but a hard-requirement for me is that features and functionalities are not 100% determined by the core project.

nvm: found this: #3806 (comment) leaving the following for posterity

Personally, I would consider locking in a scheme-like syntax as a red flag. For a plugin ecosystem to take off, motivated individuals would have to either come from emacs, or overcome the learning curve of what they are used to (most likely rust (helix fans), vimscript (vi[m] fans), or lua (neo-vim fans)).

I don't know what the solution is there, but might be something to keep in mind.

[Dietr1ch]

Personally, I would consider locking in a scheme-like syntax as a red flag.

I'm thinking that helix+steeel may finally bridge the gap between emacs and vim enough to take off as a single editor.

I'm sure bindings closer to emacs can be worked out, but I feel bindings are superficial and any plugin might implement them.
Also, if you actually start reading the thread you'll notice that this project tries to make plugins language-agnostic, it's mentioned on the very first post, so even if parentheses scare you, you'll be fine writing plugins on other language, or using plugins that you don't really care in which language are written.

Lastly, don't assume people using emacs don't use vi-bindings, emacs is likely one of the best editors around with vi-bindings available 😎, but please don't make this a vi v/s emacs discussion as this is meant for work on Plugin support spearheaded by Steel and many people are spectating, so no need to spam them with off-topic discussions.

[Ben-PH]

@Dietr1ch No need to be personal. No need to start an editor flame war. No need to misrepresent me.

Be nice.

ETA: Any reasonable feedback/criticism in your reply is wasted. I hope you treat your colleagues that are stuck with you with a bit more respect.