Skip to content

lua-configuration.md

Latest commit

 

History

History
230 lines (175 loc) · 7.85 KB

lua-configuration.md

File metadata and controls

230 lines (175 loc) · 7.85 KB
Raw

Pebrel Lua Configuration

Pebrel uses vendored Lua 5.4 for programmable configuration. Load its API with require 'pebrel' and generate a configuration with pebrel config init. Existing require 'nebula' calls resolve to the same API table, so old Lua configurations continue to work.

Lua configuration is executable local code. Only use configuration files and modules that you trust. Pebrel does not download or execute remote configuration during discovery.

Quick Start

Create a localized, annotated configuration:

pebrel config init --language system
pebrel config init --language zh-CN
pebrel config init --language en-US

Pebrel refuses to overwrite an existing file. --force first creates a timestamped backup and only then atomically replaces the target.

Validate a configuration without opening a window:

pebrel config check
pebrel config check --config-file D:/configs/pebrel.lua

Basic Configuration

local pebrel = require 'pebrel'
local config = pebrel.config_builder()

config.window = {
    opacity = 0.96,
    decorations = 'Full',
}

config.font = {
    normal = { family = 'Maple Mono NF CN', style = 'Regular' },
    size = 13.0,
}

config.scrolling = {
    history = 10000,
}

config.env = {
    EDITOR = 'nvim',
}

return config

Returning a plain table is also supported, but config_builder() is recommended because it validates top-level assignments as they are made. Unknown fields and invalid values are errors by default.

Arrays And Modules

Lua's {} does not distinguish an empty array from an empty object. Pebrel treats an ordinary empty table as an object; use pebrel.array() for an empty array:

config.profiles = pebrel.array()

config.profiles = pebrel.array {
    {
        name = 'Production SSH',
        command = 'ssh',
        args = { 'user@server' },
    },
}

Non-empty tables with consecutive integer keys are arrays automatically. Sparse arrays and tables mixing integer and string keys are rejected.

Split large configurations into sibling modules:

-- theme.lua
return {
    primary = {
        foreground = '#d8dee9',
        background = '#16181d',
    },
}
-- pebrel.lua
local pebrel = require 'pebrel'
local config = pebrel.config_builder()
config.colors = require 'theme'
return config

Files successfully loaded through require are added to the live-reload watch list. Extra local files can be registered with pebrel.add_to_config_reload_watch_list(path).

Terminal Selection Colors (TOML Compatibility)

For a legacy pebrel.toml configuration, the GPUI terminal accepts explicit selection foreground and background colors in #rrggbb or 0xrrggbb form:

[colors.selection]
foreground = "#102030"
background = "#e5e9f0"

Previously the GPUI adapter loaded the selection background but ignored the foreground, which could leave selected text unreadable against a custom background. It also cleared a custom foreground when applying a theme such as Paper that does not declare selection colors. Both values now survive loading and themes that do not override them. A theme that explicitly declares selection colors, such as Nord, retains its existing precedence.

Missing or invalid foreground colors keep the existing fallback. Relative CellForeground / CellBackground values are not added by this change. The regression tests cover parsing and theme precedence; this does not change the answer reader's selection overlay, formula selection layout, or the default selection contrast. No new setting, dependency, or per-frame work is introduced.

Platform Values

The module exposes stable runtime paths and platform data:

local pebrel = require 'pebrel'

if pebrel.platform.os == 'linux' then
    -- display_server is 'wayland', 'x11', or 'unknown'.
    pebrel.log_info('Linux display: ' .. pebrel.platform.display_server)
end

-- pebrel.config_file, pebrel.config_dir, pebrel.home_dir
-- pebrel.executable_dir, pebrel.version, pebrel.target_triple

Discovery Order

An explicit --config-file wins, followed by PEBREL_CONFIG_FILE and then the legacy NEBULA_CONFIG_FILE alias. Empty environment values are ignored. Explicit paths must end in .lua, .toml, .yml, or .yaml.

Without an explicit path, Pebrel searches its own filenames before legacy nebula.* names. Within each name, the format order is Lua, TOML, YML, then YAML. For example, pebrel.toml takes precedence over nebula.lua. An existing but invalid chosen file reports an error; Pebrel does not silently load another file.

The default data directories are:

Platform Directory
Windows %APPDATA%/Pebrel
macOS $HOME/Library/Application Support/Pebrel
Linux ${XDG_CONFIG_HOME:-$HOME/.config}/pebrel

PEBREL_CONFIG_DIR overrides the data directory, with NEBULA_CONFIG_DIR as a fallback alias. When either nonempty override is set, automatic discovery stays inside that directory; it does not read configuration from the executable, home, or system directories. pebrel config init writes pebrel.lua into the active data directory.

Windows Lua locations:

  1. pebrel.lua beside pebrel.exe for portable installations.
  2. %APPDATA%/Pebrel/pebrel.lua.
  3. %USERPROFILE%/.pebrel.lua.

Linux Lua locations:

  1. $XDG_CONFIG_HOME/pebrel/pebrel.lua.
  2. $XDG_CONFIG_HOME/pebrel.lua.
  3. $HOME/.config/pebrel/pebrel.lua.
  4. $HOME/.pebrel.lua.
  5. /etc/pebrel/pebrel.lua.

On macOS, the data-directory location is checked before the Linux-style XDG, home, and system locations listed above. The same location order applies to .toml, .yml, and .yaml, followed by legacy nebula.* names and locations. Existing TOML configurations remain supported; YAML is a deprecated transition format.

Existing Nebula Data

On first startup, Pebrel copies legacy data into its data directory without overwriting existing Pebrel files. Preferences use pebrel_settings.txt; new main configuration files use pebrel.lua, pebrel.toml, pebrel.yml, or pebrel.yaml. Session, SSH, and other files whose names do not contain the old brand retain their names.

The source directory and old configuration names remain available for recovery and for modules that import an absolute legacy path. The migration records completion only after all copies succeed, and can retry after an error. Once complete, later launches do not copy old data back over deliberately removed files. Existing newer files remain authoritative throughout the migration.

Transactional Reload

Configuration parsing and Lua execution run on one serial worker. Rapid file saves are coalesced, and only the latest successful generation is published. If Lua syntax, module loading, conversion, or validation fails, Pebrel keeps the last-known-good UiConfig and Lua VM alive. Fixing and saving the file causes the next valid generation to replace them together.

Linux and macOS package targets and native acceptance requirements are listed in the installation guide. Configuration support alone is not evidence that a native package has passed its runtime checks.

中文说明

pebrel config init --language zh-CN 会生成活动代码与英文模板完全一致、 但说明全部为简体中文的 UTF-8 配置。切换 Pebrel 界面语言不会改写已经存在的 Lua 文件。普通空表 {} 表示对象；空数组必须写成 pebrel.array()。保存配置 后若出现语法或字段错误，Pebrel 会保留上一份可用配置，修正并再次保存即可恢复 自动重载。

旧的 require 'nebula' 与新的 require 'pebrel' 指向同一 API。显式配置文件优先， 其次为 PEBREL_CONFIG_FILE、兼容的 NEBULA_CONFIG_FILE，然后依次查找 Pebrel 与 Nebula 文件；每种名称内按 Lua、TOML、YML、YAML 排序。首次迁移会非覆盖复制旧数据， 保留旧目录与文件供恢复及绝对路径导入使用，不删除来源，也不覆盖已有的新配置。