231 lines
7.9 KiB
Markdown
231 lines
7.9 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
pebrel config check
|
|
pebrel config check --config-file D:/configs/pebrel.lua
|
|
```
|
|
|
|
## Basic Configuration
|
|
|
|
```lua
|
|
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:
|
|
|
|
```lua
|
|
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:
|
|
|
|
```lua
|
|
-- theme.lua
|
|
return {
|
|
primary = {
|
|
foreground = '#d8dee9',
|
|
background = '#16181d',
|
|
},
|
|
}
|
|
```
|
|
|
|
```lua
|
|
-- 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:
|
|
|
|
```toml
|
|
[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:
|
|
|
|
```lua
|
|
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](../INSTALL.md). 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 排序。首次迁移会非覆盖复制旧数据，
|
|
保留旧目录与文件供恢复及绝对路径导入使用，不删除来源，也不覆盖已有的新配置。
|