Dynamically select pre-defined configuration snippets

[pkazmier]

You can find the precursor of this discussion in #5369.

Have you ever wanted to easily tweak one or two settings of your wezterm config dynamically? Maybe you want to quickly switch fonts, font size, leading (line spacing), or color schemes? If you have, you might be interested in my config-selector, which allows you to define a list of items and a pre-defined config override to execute upon selection. For example:

Screen.Recording.2024-05-17.at.6.53.42.AM.mov

For example, in my wezterm config, I define several selectors:

local wezterm  = require("wezterm")
local selector = require("config-selector")
local act      = wezterm.action
local config   = wezterm.config_builder()

-- My dynamic configuration selectors
local fonts    = selector.new({ title = "Font Selector",          subdir = "fonts" })
local inactive = selector.new({ title = "Inactive Pane Selector", subdir = "inactivepanes" })
local leading  = selector.new({ title = "Font Leading Selector",  subdir = "leadings" })
local schemes  = selector.new({ title = "Color Scheme Selector",  subdir = "colorschemes" })
local sizes    = selector.new({ title = "Font Size Selector",     subdir = "sizes" })

-- Select my default choices
fonts:select(config, "Berkeley Mono")
schemes:select(config, "MiniHues Teal")

-- Bind the selector to keys for quick access
config.keys = {
  { key = "c",      mods = "LEADER", action = schemes:selector_action() },
  { key = "f",      mods = "LEADER", action = fonts:selector_action() },
  { key = "i",      mods = "LEADER", action = inactive:selector_action() },
  { key = "l",      mods = "LEADER", action = leading:selector_action() },
  { key = "s",      mods = "LEADER", action = sizes:selector_action() },
}

The subdir option passed to selector.new is a subdirectory within your wezterm configuration directory that should contain one or more lua modules. Each module represents one or more items to appear in the menu and the action to take when selected. The name of the module is irrelevant as it is not used. It must be a valid lua module name of course. For example, here are the contents of my wezterm directory:

.
├── colorschemes
│   ├── builtin-colorschemes.lua
│   ├── minihues-cyan.lua
│   ├── minihues-green.lua
│   ├── minihues-nightowl.lua
│   ├── minihues-purple.lua
│   ├── minihues-slate.lua
│   └── minihues-teal.lua
├── fonts
│   ├── berkeley.lua
│   ├── jetbrains.lua
│   ├── menlo.lua
│   ├── monaspace-argon.lua
│   ├── monaspace-krypton.lua
│   ├── monaspace-neon.lua
│   ├── monaspace-radon.lua
│   ├── monaspace-xenon.lua
│   ├── operator.lua
│   ├── pragmata.lua
│   ├── roboto.lua
│   ├── scp.lua
│   ├── sf.lua
│   ├── sudo.lua
│   ├── ubuntu.lua
│   └── victor.lua
├── inactivepanes
│   └── variants.lua
├── leadings
│   └── leadings.lua
├── sizes
│   └── sizes.lua
├── config-selector.lua
├── stylua.toml
└── wezterm.lua

6 directories, 29 files

The lua module in a subdirectory must export two functions: init and activate. The init function will receive no arguments. It must return one of the following:

1. "item name": a string that is used as the name of the item in the selector
2. { label = "item name" }: a table with a label key that is used as the name of the item in the selector.
3. { label = "item name", value = 10 }: a table that also includes a value key that will be passed to the activate function when the item is selected.
4. { "item1", "item2" } or {{ label = "item1", value = 10 }, { label = "item2", value = 20 }}: a list of any of the above if you want to define more than one item per lua module.

The activate function will receive three arguments:

1. config: a wezterm config overrides table that you will use to override configuration items.
2. name: the name of the item that was selected as defined by the init function. This is useful to distinguish between items if your init returned more than one item.
3. value: the value of the item that was selected as defined by the init function or nil if not defined. This is useful to distinguish between items if your init returned more than one item.

For example, let's look at menlo.lua in my fonts directory. The init function returns a single string. Because this lua module only defines one item, I don't use the additional arguments (name and value) passed to activate because I don't have to distinguish between items selected—there is only one defined in the module!

local wezterm = require("wezterm")
local M = {}
local name = "Menlo"

M.init = function()
  return name
end

M.activate = function(config)
  config.font = wezterm.font(name)
  config.font_size = 14.0
  config.line_height = 1.4
end

return M

Let's look at my colorschemes directory, which has a mix of lua modules that define single items (all the minihues-* files look similar to the example above), but it also includes one module called builtin-colorschemes.lua that defines several items to be added to the menu. In this file, you can see that the init function returns a table of items. Each table includes a label, which is used as the item name in the menu, but also a value that is used in activate if the item is selected. In this case, the value is the official name of the scheme, but I want the display name to be prettier, so I define a separate label and value.

local M = {}

local colorschemes = {
  { label = "Ayu Dark",         value = "Ayu Dark (Gogh)" },
  { label = "Tokyo Night Moon", value = "Tokyo Night Moon"},
  { label = "Catppuccin Mocha", value = "Catppuccin Mocha"},
  { label = "Oxocarbon Dark",   value = "Oxocarbon Dark (Gogh)" },
  { label = "Matrix",           value = "matrix" },
}

M.init = function()
  return colorschemes
end

M.activate = function(config, _, value)
  config.color_scheme = value
end

return M

If I did not care about having a prettier item name, then I could simplify the above to the following by just using the official scheme name as the menu items. And if selected, use the 2nd argument to activate, which will be the name of the scheme:

local M = {}

local colorschemes = {
  "Ayu Dark (Gogh)",
  "Tokyo Night Moon",
  "Catppuccin Mocha",
  "Oxocarbon Dark (Gogh)",
  "matrix",
}

M.init = function()
  return colorschemes
end

M.activate = function(config, name)
  config.color_scheme = name
end

return M

Finally, as a last example, let's look at my sizes directory where I have a single lua module defined in a file called sizes.lua (again, name of the file is irrelevant). In this case, I didn't want to define a single lua module for each possible font size. I could, but it would be tedious, so I instead return a table of items, each with a label and value key. This allows me to populate the menu with 8pt to 30pt items in a single file. Because I want a prettier item name, I append "pt" to the label. And since we've defined more than one item in this module, I distinguish which one was selected in my activate function via the value argument.

local M = {}

M.init = function()
  local sizes = { "Default" }
  for i = 8, 30 do
    table.insert(sizes, { label = string.format("%2dpt", i), value = i })
  end
  return sizes
end

M.activate = function(config, _, value)
  config.font_size = value
end

return M

In the above example, you might have noticed that I also included a single string "Default" in the sizes table. This is allowed as mentioned above when I talk about the possible return values from init. Because "Default" is not a table with a value associated with it, when it is selected by a user, the value argument in activate is nil. This is convenient as we use that to remove any existing overrides set in config.font_size. It allows us to revert back to whatever your default was in your main configuration.

I hope you find this useful. It's been a game changer for me!

[Zethtren]

Thank you for sharing!

This is exactly the configuration I wanted to set up a “workspace/project navigator”. I haven’t learned lua that much yet but, I think the only difference would be using a file to store them so I can add / remove projects.

[akthe-at]

@Zethtren you might like combining some of the selector logic from @pkazmier with some of the sessionizer logic found here

[Zethtren]

@akthe-at

Thanks! You're absolutely right!