Lua Scripting Guide

Paneru embeds a Lua runtime, letting a script declare the entire configuration via paneru.setup{...}, hook into window-manager events (paneru.on), bind keys to Lua callbacks or command strings (paneru.bind), query state, persist data across reloads, and programmatically manipulate window sets.

1. Getting Started

Script Locations

By default, Paneru looks for a Lua script in the following locations (in order):

1. $PANERU_LUA (environment variable)
2. $HOME/.paneru.lua
3. $XDG_CONFIG_HOME/paneru/init.lua

TOML Replacement

A script replaces the TOML. When any of those files exist, the TOML path is switched off completely: no paneru.toml is read, created, or watched, and anything the script does not set takes its built-in default. Two authoritative configs cannot coexist, so a leftover TOML never quietly overrides the script. Conversely, no init.lua is created for you when a paneru.toml already exists — TOML setups keep working untouched until you write a script yourself.

Like the TOML config, the script is automatically reloaded when the file is saved.

Paneru provides the paneru table as a global in init.lua. You can also write local paneru = require("paneru") there; it returns the same embedded API and does not need a separate paneru.so file. The loadable paneru.so client module is only for Lua scripts run outside Paneru. Installing the Paneru executable with cargo install does not install that separate module.

2. Configuration from Lua (paneru.setup)

paneru.setup{...} declares the whole configuration from Lua, so init.lua can replace paneru.toml entirely. The table mirrors the TOML sections one-for-one — options, padding, swipe, decorations, restore, windows, and top-level default_workspaces.

Keybindings

Two equivalent ways to bind keys, both accepting the exact chord syntax of the TOML [bindings] table:

• paneru.bind(chord, handler) — the handler is a command string or a Lua function (function handlers receive a state snapshot; only paneru.bind supports them).
• a bindings sub-table inside setup, keyed by command with the chord as the value — a shorthand that desugars onto the same path as paneru.bind:

Reading the Active Configuration (paneru.config)

The active configuration is exposed on paneru.config, mirroring the paneru.setup schema (paneru.config.options, paneru.config.padding, paneru.config.swipe, paneru.config.decorations, paneru.config.restore, paneru.config.windows, and paneru.config.default_workspaces).

• Pre-populated with defaults: Even before (or without) calling paneru.setup, paneru.config is populated with Paneru's built-in defaults (e.g., paneru.config.options.sliver_width == 5, paneru.config.options.preset_column_widths, etc.).
• Merged on paneru.setup: Calling paneru.setup{...} merges your configuration table over the resolved defaults (and preserves any extra custom keys you include in the table).
• Read-only snapshot semantics: paneru.config is a plain Lua table for inspection by snippets and callbacks. Mutating fields on paneru.config directly does not change the running window manager's settings unless you pass the modified table back to paneru.setup(paneru.config).

Precedence & Reloading

An init.lua disables the TOML entirely, whether or not it calls paneru.setup. With setup, that table is the configuration; without it, the built-in defaults are used — never a paneru.toml sitting next to the script. To keep using TOML, do not create a script.

Editing and saving init.lua hot-reloads the whole configuration (including menubar and passthrough updates), just like editing the TOML file.

Notes:

• Float-valued options (animation_speed, border width/opacity, window width, …) should be written with a decimal point (12.0, not 12).
• A reload that removes a previous paneru.setup call keeps the last config it produced rather than reverting to TOML.
• With Nix modules, set services.paneru.config to this init.lua (Lua source or a path). See nix/README.md.

3. Event Handling (paneru.on)

paneru.on registers callback functions that execute when window-manager events occur.

Registration Syntax

paneru.on accepts 2 or 3 arguments:

• event_name (string): The event to listen for.
• filter (optional table or function): Filter criteria. Only events matching the filter will trigger the handler. Non-matching events avoid cross-thread state queries and Lua execution.
• handler (function): The callback function, receiving (event, workspace).

Supported Events

4. Querying State

Inside a paneru.on handler or a paneru.bind callback, the script can read the same state documents paneru query … returns — no round trip, no io.popen:

These are spelled exactly as in the loadable client module (require("paneru"), implemented in src/lua/client.rs), so a helper that reads state works unchanged in either host. The payloads are documented in QUERY_AND_SUBSCRIBE_FORMAT.md.

To build the standalone loadable paneru.so shared library for an external Lua interpreter (e.g. Lua 5.4 or LuaJIT):

State is gathered on demand and at most once per callback, so handlers that never query cost nothing extra. Outside a callback there is no window-manager state to read, so calling one of these at script top level raises an error; call them inside a handler or keybinding callback.

5. Persistent State (paneru.state)

A handler that wants to remember something — which window is the scratchpad, what was focused a moment ago, how many times something has happened — cannot keep it in a Lua global. Saving init.lua rebuilds the interpreter, and every global goes with it. paneru.state is the store that survives reloads and daemon restarts.

Reach for mutate whenever the new value depends on the old one. It reads, runs your function, and stores the result only if the value is still what it read; if something else modified it first, mutate re-runs your function against the new value.

Keys are plain strings; values can be strings, numbers, booleans, or JSON-shaped tables. The store is saved in $XDG_STATE_HOME/paneru/script-state.json.

6. Programmatic Window Management

Handlers are given a window set (ws): the whole layout — displays, workspaces, columns, and the windows in them — as a value you can transform. It is modeled on xmonad's StackSet, and it is pure: every operation returns a new window set rather than changing the one you were given, and nothing touches a real window until you return it.

Because the window set is pure:

A handler that raises partway through changes nothing either, because it never returned anything. You can branch, compute candidate layouts, and return the chosen one.

paneru.windows(fn) is the same contract for use partway through a handler: it hands fn the window set and commits what it gives back.

Reading Layout State

A window record contains id, app_name, bundle_id, title, role, subrole, frame, floating, managed, visible and focused.

paneru.match{ app = …, bundle = …, title = …, role = …, subrole = …, floating = …, managed = … } builds a compiled predicate; app, bundle and title are regular expressions, while role and subrole match exact strings.

Transforming Layout State

Each method returns a new window set:

• ws:focus(id)
• ws:swap(a, b)
• ws:shift(id, workspace[, follow])
• ws:view(workspace)
• ws:float(id[, rect])
• ws:sink(id)
• ws:manage(id)
• ws:unmanage(id)
• ws:width(id, ratio)
• ws:stack(id, onto)
• ws:tab(id, onto)
• ws:unstack(id)

ws:float(id) takes a window out of the tiling layout and leaves it where it is. ws:float(id, rect) places it relative to display fractions:

7. Example: Named Scratchpads

A worked port of xmonad's NamedScratchpad. A scratchpad is a window you toggle in and out of view; when not wanted, it is parked on a workspace you never look at (stash = 9).