Scripting

The imperative globals that are neither UI nor processes: keep settings on disk, schedule work, answer keybinds, and a few utilities. Reach for them from event handlers (on_click, on_change, callbacks) or a module’s top level. Running other programs is on processes; everything that renders goes through signals and nodes instead.

Terms used below (Supervisor, Renderer, generation, push) are in the glossary.

Which one do I use

What each one keeps across a reload, a crash and a restart: runtime.

persistent_table

A JSON object on disk, read as one signal per key and written one key at a time.

local settings = persistent_table {
    path = "~/.local/state/myshell/settings.json",
    defaults = { clock_24h = true, recorder = { fps = 60, audio = "desktop" } },
}

-- Reads its declared default before the first push.
local clock_24h = settings.clock_24h

return panel {
    id = "clock", layer = "top", anchor = { top = true },
    child = rect {
        on_click = function() settings:set("clock_24h", not clock_24h:get()) end,
        children = {
            text { content = clock_24h:map(function(on) return on and "24h" or "12h" end) },
        },
    },
}

On disk:

timer

Runs a function once after a delay. To repeat at a fixed rate, use interval.

local status = state("status", "checking")
local BACKOFF_MS = { 2000, 4000, 8000 }

local function check(attempt)
    attempt = attempt or 1
    process.run("ping", { "-c", "1", "-W", "2", "1.1.1.1" }, function() end, function(code)
        if code == 0 then
            status:set("online")
        elseif BACKOFF_MS[attempt] then
            status:set("retrying")
            timer(BACKOFF_MS[attempt], function() check(attempt + 1) end)
        else
            status:set("offline")
        end
    end)
end
check()

-- Re-arming from the callback repeats on a varying delay, here aligned to the minute.
local clock = state("clock", "")
local function tick()
    clock:set(os.date("%H:%M"))
    timer(60000 - (os.time() % 60) * 1000, tick)
end
tick()

For a delayed or blinking value, delay and pulse (signals) need no callback.

When to use a timer

Each time a timer sets a signal, every :map reading it runs again. Once a minute is free; every 33 ms is 30 times a second, forever. Arm a timer as often as the data changes, never per frame.

interval

interval(ms, fn) → handle. Runs fn every ms until handle:cancel(), with timer’s range, budget, order and lifetime. Turns stay on the original schedule; one that comes late runs once and the next is ms after it, so missed runs never queue. A raise is logged and the next run still happens. Cancelling from inside fn stops it.

local load = state("load", "")
interval(5000, function()
    process.run("cat", { "/proc/loadavg" }, function(line) load:set(line:match("^%S+")) end, function() end)
end)

action

Names a function that mantle call <name> [args...] runs, usually from a compositor keybind. Write a state when the shell should look different; call an action when it should do something.

-- Keybind: mantle call volume.up 10
action("volume.up", function(step)
    local audio = mantle.audio:get()
    for _, sink in ipairs(audio and audio.sinks or {}) do
        if sink.active and sink.volume then
            local volume = math.max(0, math.min(150, sink.volume + (tonumber(step) or 5)))
            mantle.audio:set_volume(sink.id, volume)
            return string.format("%d%%", math.floor(volume + 0.5))
        end
    end
    return "no output device"
end)

CLI flags such as --pid: cli.

json.decode

json.decode(text) → value, or nil, message. It never raises on bad input.

json.encode

json.encode(value) → string: compact JSON, object keys sorted. It raises on a value JSON cannot hold, since that is a config mistake rather than bad input.

local body = json.encode({ title = "Backup", done = true }) -- {"done":true,"title":"Backup"}
process.detach("curl", { "-s", "-H", "Content-Type: application/json", "-d", body, "http://localhost:8080/events" })

log

log.error(...), log.warn(...), log.info(...), log.debug(...). Arguments join with tabs like print, and the line is stamped with time, level and the config subsystem. All levels print by default. Filter with MANTLE_LOG=config=warn (or config=off); read with mantle log.

fuzzy

fzf’s scorer for one candidate. Iterating, sorting and tiebreaking stay in Lua.

local APPS = { "Firefox", "Files", "GIMP", "Terminal", "System Monitor" }
local query = state("query", "")

local results = query:map(function(needle)
    local scored = {}
    for _, name in ipairs(APPS) do
        local score, start = fuzzy(name, needle)
        if score then
            scored[#scored + 1] = { name = name, score = score, start = start }
        end
    end
    table.sort(scored, function(left, right)
        if left.score ~= right.score then return left.score > right.score end
        if left.start ~= right.start then return left.start < right.start end
        return left.name < right.name
    end)
    local names = {}
    for index, entry in ipairs(scored) do names[index] = entry.name end
    return names
end)

return panel {
    id = "launcher", layer = "overlay", keyboard_interactivity = "on_demand",
    child = column {
        width = 320, padding = 12, spacing = 6, background = "#1E1E2E",
        children = {
            textfield { autofocus = true, placeholder = "Search", on_change = function(text) query:set(text) end },
            list { items = results, each = function(name) return text { content = name } end },
        },
    },
}

Tie order is the caller’s: table.sort is unstable, so end the comparator on a unique key.

palette.quantize

Dominant colours of an image by Material’s quantizers, computed on a background thread. Put a raster image at wallpaper.png in your config directory, or change the path below to an existing image. The book checks this file-dependent snippet’s syntax; the callback runs only in a live Renderer.

local swatches = state("swatches", {})

palette.quantize(mantle.config_dir .. "/wallpaper.png", { depth = 3 }, function(found)
    swatches:set(found or {})
end)

return panel {
    id = "palette", layer = "top", anchor = { bottom = true },
    child = row {
        children = swatches:map(function(list)
            local chips = {}
            for index, swatch in ipairs(list) do
                chips[index] = rect { width = math.max(4, 200 * swatch.share), height = 16, background = swatch.color }
            end
            return chips
        end),
    },
}

palette.scheme

Material 3 colour roles from one seed colour (to write them into other programs’ configs: Colour your apps), built by Material Color Utilities at spec 2021 on the phone platform. Synchronous: one scheme takes about 0.5 ms.

local roles = palette.scheme("#6750A4", { dark = true, variant = "tonal_spot" })

return rect {
    background = roles.surface_container, padding = 12,
    children = { text { content = "Material", foreground = roles.on_surface } },
}

palette.score

Ranks palette.quantize swatches as Material 3 picks a wallpaper’s seed: chromatic colours that cover more of the image, spread across hues. Quantize at depth 6 or 7, so Score has enough colours to choose from.

local roles = state("roles", palette.scheme("#6750A4"))

palette.quantize(mantle.config_dir .. "/wallpaper.png", { depth = 7 }, function(found)
    if found then roles:set(palette.scheme(palette.score(found)[1], { dark = true })) end
end)

palette.hct

A colour’s hue, chroma and tone in HCT, Material’s colour space, which Score and every scheme work in. A config can rank or filter swatches by its own rule: tonal spot’s primary palette uses chroma 36, so a seed far below that comes out muted.

local seed = "#6750A4"
local hct = palette.hct(seed) -- hue ≈ 299, chroma ≈ 48, tone ≈ 40

return text { content = hct.chroma >= 36 and "vivid" or "muted" }

palette.from_hct

palette.hct’s inverse: palette.from_hct{ hue, chroma, tone } → "#RRGGBB". hue wraps, chroma is 0 or more, tone 0 to 100, all numbers; anything else raises. A chroma sRGB cannot show at that hue and tone is reduced to what fits.

local hct = palette.hct("#6750A4")
return text { content = palette.from_hct { hue = hct.hue, chroma = hct.chroma, tone = 90 } }

palette.harmonize

palette.harmonize(color, source) → "#RRGGBB". Moves color’s hue toward source’s by half the gap, at most 15°, keeping chroma and tone: Material’s way to seat a fixed colour, such as an error red, beside a seed.

return text { content = palette.harmonize("#FF0000", "#6750A4"), foreground = "#FFFFFF" }

file

Whole-file read and write on a background thread. The config VM has no blocking IO: results arrive in a callback, like palette.quantize. Worked example: Colour your apps.

fonts

fonts { family, ... } sets the fallback chain every text node uses. Each glyph takes the first family that covers it.

fonts { "Inter", "Symbols Nerd Font", "Noto Color Emoji" }

How do I…

Gotchas

See also: processes, runtime (reloads, budgets, logging), signals (state, delay), storage capability (mantle.storage), cli (mantle call, mantle log).

Source: store, storage controller, timer, action, json, log, fuzzy, palette, file, scheme, fonts.