Steel plugin support

This is a squashed version of
helix-editor#8675.
2270457

Author: irh

Cargo.lock

@@ -40,6 +40,7 @@ package.helix-term.opt-level = 2
 tree-house = { version = "0.3.0", default-features = false }
 nucleo = "0.5.0"
 slotmap = "1.0.7"
+steel-core = { git = "https://github.com/mattwparas/steel.git", version = "0.7.0", features = ["anyhow", "dylibs", "sync", "triomphe", "imbl"] }
 thiserror = "2.0"
 tempfile = "3.22.0"
 bitflags = "2.9"

Cargo.toml

@@ -0,0 +1,265 @@
+# Building
+
+You will need:
+
+* A clone of this fork, on the branch `steel-event-system`
+
+## Installing helix
+
+Just run
+
+`cargo xtask steel`
+
+To install the `hx` executable, with steel as a plugin language. This also includes:
+
+The `steel` executable, the steel language server, the steel dylib installer, and the steel package manager `forge`.
+
+## Developing
+
+The easiest way to contribute would be to adjust the default features on the `helix-term` crate:
+
+```toml
+[features]
+features = ["git", "steel"]
+```
+
+## Setting up configurations for helix
+
+There are 2 important files you'll want, which should be auto generated during the installation process if they don't already exist:
+
+* `~/.config/helix/helix.scm`
+* `~/.config/helix/init.scm`
+
+Note - these both live inside the same directory that helix sets up for runtime configurations.
+
+### `helix.scm`
+
+The `helix.scm` module will be loaded first before anything else, the runtime will `require` this module, and any functions exported will now be available
+to be used as typed commands. For example:
+
+
+```scheme
+# helix.scm
+(require "helix/editor.scm")
+(require (prefix-in helix. "helix/commands.scm"))
+(require (prefix-in helix.static. "helix/static.scm"))
+
+(provide shell git-add open-helix-scm open-init-scm)
+
+;;@doc
+;; Specialized shell implementation, where % is a wildcard for the current file
+(define (shell cx . args)
+  ;; Replace the % with the current file
+  (define expanded (map (lambda (x) (if (equal? x "%") (current-path cx) x)) args))
+  (apply helix.run-shell-command expanded))
+
+;;@doc
+;; Adds the current file to git	
+(define (git-add cx)
+  (shell cx "git" "add" "%"))
+
+(define (current-path)
+  (let* ([focus (editor-focus)]
+         [focus-doc-id (editor->doc-id focus)])
+    (editor-document->path focus-doc-id)))
+
+;;@doc
+;; Open the helix.scm file
+(define (open-helix-scm)
+  (helix.open (helix.static.get-helix-scm-path)))
+
+;;@doc
+;; Opens the init.scm file
+(define (open-init-scm)
+  (helix.open (helix.static.get-init-scm-path)))
+  
+	
+```
+
+Now, if you'd like to add the current file you're editing to git, simply type `:git-add` - you'll see the doc pop up with it since we've annotated the function
+with the `@doc` symbol. Hitting enter will execute the command.
+
+You can also conveniently open the `helix.scm` file by using the typed command `:open-helix-scm`.
+
+
+### `init.scm`
+
+The `init.scm` file is run at the top level, immediately after the `helix.scm` module is `require`d. The helix context is available here, so you can interact with the editor.
+
+The helix context is bound to the top level variable `*helix.cx*`.
+
+For example, if we wanted to select a random theme at startup:
+
+```scheme
+# init.scm
+
+(require-builtin steel/random as rand::)
+(require (prefix-in helix. "helix/commands.scm"))
+(require (prefix-in helix.static. "helix/static.scm"))
+
+;; Picking one from the possible themes
+(define possible-themes '("ayu_mirage" "tokyonight_storm" "catppuccin_macchiato"))
+
+(define (select-random lst)
+  (let ([index (rand::rng->gen-range 0 (length lst))]) (list-ref lst index)))
+
+(define (randomly-pick-theme options)
+  ;; Randomly select the theme from the possible themes list
+  (helix.theme (select-random options)))
+
+(randomly-pick-theme possible-themes)
+
+```
+
+### Libraries for helix
+
+There are a handful of extra libraries in development for extending helix, and can be found here https://github.com/mattwparas/helix-config.
+
+If you'd like to use them, create a directory called `cogs` in your `.config/helix` directory, and copy the files in there.
+
+### options.scm
+
+If you'd like to override configurations from your toml config:
+
+
+```scheme
+# init.scm
+
+(require "helix/configuration.scm")
+
+(file-picker (fp-hidden #f))
+(cursorline #t)
+(soft-wrap (sw-enable #t))
+
+```
+
+
+### keymaps.scm
+
+Applying custom keybindings for certain file extensions:
+
+```scheme
+# init.scm
+
+(require "cogs/keymaps.scm")
+(require (only-in "cogs/file-tree.scm" FILE-TREE-KEYBINDINGS FILE-TREE))
+(require (only-in "cogs/recentf.scm" recentf-open-files get-recent-files recentf-snapshot))
+
+;; Set the global keybinding for now
+(add-global-keybinding (hash "normal" (hash "C-r" (hash "f" ":recentf-open-files"))))
+
+(define scm-keybindings (hash "insert" (hash "ret" ':scheme-indent "C-l" ':insert-lambda)))
+
+;; Grab whatever the existing keybinding map is
+(define standard-keybindings (deep-copy-global-keybindings))
+
+(define file-tree-base (deep-copy-global-keybindings))
+
+(merge-keybindings standard-keybindings scm-keybindings)
+(merge-keybindings file-tree-base FILE-TREE-KEYBINDINGS)
+
+(set-global-buffer-or-extension-keymap (hash "scm" standard-keybindings FILE-TREE file-tree-base))
+	
+```
+
+In insert mode, this overrides the `ret` keybinding to instead use a custom scheme indent function. Functions _must_ be available as typed commands, and are referred to
+as symbols. So in this case, the `scheme-indent` function was exported by my `helix.scm` module.
+
+
+## Writing a plugin
+
+### Getting setup
+
+Before you start, you should make sure that your configuration for the steel lsp is wired up correctly. This will give you
+access to the documentation that will help you as you write your plugin. To configure the LSP, you can add this to your
+`init.scm`:
+
+```scheme
+(require "helix/configuration.scm")
+(define-lsp "steel-language-server" (command "steel-language-server") (args '()))
+(define-language "scheme"
+                 (language-servers '("steel-language-server")))
+```
+
+This will give you an interactive setup that can help you run plugins as you go. I also like to evaluate commands
+via the buffer, by either typing them in to the command prompt or by loading the current buffer. To load the current
+buffer, you can type `:eval-buffer`, or to evaluate an individual command, you can run `:evalp` - note, in your init.scm, you
+may need to add:
+
+```scheme
+(require (only-in "helix/ext" evalp eval-buffer))
+```
+
+This brings those functions to the top level scope so that you can interact with them. You may also be keen to peruse all of the steel
+functions and modules available. Those can be found in `steel-docs.md`.
+
+
+### Command API
+
+There are two levels of the functionality exposed to plugins. The first is simply based around
+chaining builtin commands, as if you're a lightning fast human typing commands very quickly. The other level
+is a bit lower, and deals directly with the component API that helix uses to draw the text editor and various
+popups, like the file picker or buffer selection.
+
+To understand the first level, which is accessing typed commands and static commands, i.e. commands that you
+typically type via `:`, or static commands, commands which are bound to keybindings, you can look at the modules:
+
+* helix/commands.scm
+* helix/static.scm
+
+Every function here implicitly has access to a context, the helix context. This assumes that you're focused onto
+some buffer, and any actions are assumed to be done within that context. For example, calling `vsplit` will
+split the currently focused into a second, and move your focus to that window. Keeping track of that is important
+to understand where your focus is.
+
+In general, these functions do not return anything, given that they're purely for side effects. There are some functions
+that do, and they should be documented as such. The API will need to be improved to return useful things where relevant.
+
+### The UI
+
+A good rule of thumb is to not block the UI. During the execution of a steel function, the helix context is exclusively
+available to that executing function. As a result, you should not have long running functions there (note - if you end
+up having an infinite loop of some kind, `ctrl-c` should break you out).
+
+Luckily, there are a handful of ways we can accomplish more sophisticated plugins:
+
+* Futures
+* Threads
+
+There are a handful of primitives that accept a future + a callback, where the callback will get executed once the future
+is complete. The future will get scheduled on to the helix event loop, so the UI won't be blocked. (TODO: Document this more!)
+
+Another way we can accomplish this is with native threads. Steel supports native threads, which means we can spawn a function
+off on to another thread to run some code. Consider the following example which won't work:
+
+
+```scheme
+(spawn-native-thread (lambda () (time/sleep-ms 1000) (theme "focus_nova"))) ;; Note, this won't work!
+```
+
+This appears to spawn a thread, sleep for 1 second, and then change the theme. The issue here is that this thread does not
+have control over the helix context. So what we'll have to do instead, is schedule a function to be run on the main thread:
+
+
+```scheme
+(require "helix/ext.scm")
+(require-builtin steel/time)
+
+(spawn-native-thread
+  (lambda ()
+    (hx.block-on-task
+      (lambda ()
+        (time/sleep-ms 1000)
+        (theme "focus_nova")))))
+```
+
+`hx.block-on-task` will check if we're running on the main thread. If we are already, it doesn't do anything - but otherwise,
+it enqueues a callback that schedules itself onto the main thread, and waits till it can acquire the helix context. The function
+is then run, and the value returned back to this thread of control.
+
+
+There is also `hx.with-context` which does a similar thing, except it does _not_ block the current thread.
+
+### Components
+
+Coming soon!

STEEL.md

@@ -14,6 +14,7 @@ homepage.workspace = true
 [features]
 unicode-lines = ["ropey/unicode_lines"]
 integration = []
+steel = ["dep:steel-core"]
 
 [dependencies]
 helix-stdx = { path = "../helix-stdx" }
@@ -53,6 +54,7 @@ chrono = { version = "0.4", default-features = false, features = ["alloc", "std"
 
 textwrap = "0.16.2"
 
+steel-core = { workspace = true, optional = true }
 nucleo.workspace = true
 parking_lot.workspace = true
 globset = "0.4.16"

helix-core/Cargo.toml

@@ -766,6 +766,13 @@ impl<'a> Args<'a> {
         }
     }
 
+    pub fn raw(positionals: Vec<Cow<'a, str>>) -> Self {
+        Self {
+            positionals,
+            ..Self::default()
+        }
+    }
+
     /// Reads the next token out of the given parser.
     ///
     /// If the command's signature sets a maximum number of positionals (via `raw_after`) then
@@ -872,7 +879,7 @@ impl<'a> Args<'a> {
 
     /// Performs any validations that must be done after the input args are finished being pushed
     /// with `Self::push`.
-    fn finish(&self) -> Result<(), ParseArgsError<'a>> {
+    pub fn finish(&self) -> Result<(), ParseArgsError<'a>> {
         if !self.validate {
             return Ok(());
         };
@@ -1123,7 +1130,7 @@ mod test {
         assert_incomplete_tokens(r#"echo %{hello {{} world}"#, &["echo", "hello {{} world}"]);
     }
 
-    fn parse_signature<'a>(
+    pub fn parse_signature<'a>(
         input: &'a str,
         signature: Signature,
     ) -> Result<Args<'a>, Box<dyn std::error::Error + 'a>> {