lua: Add wezterm.action_callback to help define key callbacks

config/src/lua.rs

@@ -13,6 +13,8 @@ use termwiz::input::Modifiers;
 use termwiz::surface::change::Change;
 use unicode_segmentation::UnicodeSegmentation;
 
+static LUA_REGISTRY_USER_CALLBACK_COUNT: &str = "wezterm-user-callback-count";
+
 /// Set up a lua context for executing some code.
 /// The path to the directory containing the configuration is
 /// passed in and is used to pre-set some global values in
@@ -235,6 +237,8 @@ pub fn make_lua_context(config_file: &Path) -> anyhow::Result<Lua> {
         )?;
         wezterm_mod.set("hostname", lua.create_function(hostname)?)?;
         wezterm_mod.set("action", lua.create_function(action)?)?;
+        lua.set_named_registry_value(LUA_REGISTRY_USER_CALLBACK_COUNT, 0)?;
+        wezterm_mod.set("action_callback", lua.create_function(action_callback)?)?;
         wezterm_mod.set("permute_any_mods", lua.create_function(permute_any_mods)?)?;
         wezterm_mod.set(
             "permute_any_or_no_mods",
@@ -590,6 +594,17 @@ fn action<'lua>(
     Ok(from_lua_value(Value::Table(action))?)
 }
 
+fn action_callback<'lua>(
+    lua: &'lua Lua,
+    callback: mlua::Function,
+) -> mlua::Result<crate::keyassignment::KeyAssignment> {
+    let callback_count: i32 = lua.named_registry_value(LUA_REGISTRY_USER_CALLBACK_COUNT)?;
+    let user_event_id = format!("user-defined-{}", callback_count);
+    lua.set_named_registry_value(LUA_REGISTRY_USER_CALLBACK_COUNT, callback_count + 1)?;
+    register_event(lua, (user_event_id.clone(), callback))?;
+    return Ok(crate::KeyAssignment::EmitEvent(user_event_id));
+}
+
 async fn read_dir<'lua>(_: &'lua Lua, path: String) -> mlua::Result<Vec<String>> {
     let mut dir = smol::fs::read_dir(path)
         .await

docs/config/lua/wezterm/action_callback.md

@@ -0,0 +1,39 @@
+# `wezterm.action_callback(callback)`
+
+*Since: nightly*
+
+This function is a helper to register a custom event and return an action triggering it.
+
+It is helpful to write custom key bindings directly, without having to declare
+the event and use it in a different place.
+
+The implementation is essentially the same as:
+```lua
+function wezterm.action_callback(callback)
+  local event_id = "..." -- the function generates a unique event id
+  wezterm.on(event_id, callback)
+  return wezterm.action{EmitEvent=event_id}
+end
+```
+
+See [wezterm.on](./on.md) and [wezterm.action](./action.md) for more info on what you can do with these.
+
+
+## Usage
+
+```lua
+local wezterm = require 'wezterm';
+
+return {
+  keys = {
+    {
+      mods = "CTRL|SHIFT",
+      key = "i",
+      action = wezterm.action_callback(function(win, pane)
+        wezterm.log_info("Hello from callback!")
+        wezterm.log_info("WindowID:", win:window_id(), "PaneID:", pane:pane_id())
+      end)
+    },
+  }
+}
+```

docs/config/lua/wezterm/on.md

@@ -22,6 +22,8 @@ There is no way to de-register an event handler.  However, since the Lua
 state is built from scratch when the configuration is reloaded, simply
 reloading the configuration will clear any existing event handlers.
 
+See [wezterm.action_callback](./action_callback.md) for a helper to define a custom action callback.
+
 ## Predefined Events
 
 See [Window Events](../window-events/index.md) for a list of pre-defined