# Customizing paperOS
paperOS is customized entirely through Lua. On startup the editor loads
`init.lua` from your config directory:
- `$PAPEROS_CONFIG/init.lua` (if the env var is set)
- otherwise `~/.config/paperos/init.lua`
Everything in the `paper.*` namespace is available in that file. User Lua
modules colocated with `init.lua` are loadable via `require` (the config
dir is prepended to `package.path`).
## Quick start
```lua
-- ~/.config/paperos/init.lua
paper.config.set("ui.line_numbers", "false")
paper.config.set("statusline.format", " %m :: %f ")
paper.theme.set("cursor-normal", "magenta")
paper.theme.set("border", "blue")
paper.keys.map("normal", "U", "upper-word")
```
## Reference
### paper.config
Typed settings, stored as strings.
- `paper.config.set(key, value)` — set at config time
- `paper.config.get(key)` — read back
| `ui.line_numbers` | `"true"` / `"false"` | `"true"` | Line-number gutter |
| `statusline.format` | template | `" %m %f %l:%c %("` | Statusline layout |
Statusline tokens: `%m` mode, `%f` file name, `%l` line, `%c` column,
`%(` modified marker (shows `[+]` when the buffer is modified, else empty).
### paper.theme
`paper.theme.set(name, color)` — any of: `black red green yellow blue
magenta cyan gray darkgray white reset`, or `#rrggbb`.
| `cursor-normal` | `yellow` | Cursor block in Normal/Visual |
| `cursor-insert` | `white` | Cursor block in Insert |
| `cursor-visual` | `yellow` | Cursor in Visual |
| `border` | `cyan` | Editor panel border |
| `line-number-fg` | `darkgray` | Gutter numbers |
| `statusbar-fg` / `statusbar-bg` | `black` / `cyan` | Statusline colors |
| `candidate-fg` / `candidate-bg` | `black` / `white` | Minibuffer input |
| `candidate-sel-bg` | `darkgray` | Candidate list / echo bg |
| `echo-fg` | `white` | Echo line text |
### paper.commands
```lua
paper.commands.register("greet", function(args)
return "hello " .. (args[1] or "world")
end, "Greet the user")
```
Registered commands are real editor commands: they appear in `M-x`
completion and can be bound with `paper.keys.map`.
### paper.events
```lua
paper.events.on("file.saved", function(payload)
-- payload is a table: { path = "...", bytes = 123 }
paper.cmd("message saved: " .. payload.path)
end)
```
Built-in events:
| `file.saved` | `{ path, bytes }` |
| `buffer.changed` | `{ command, buffer }` |
`paper.events.publish(name, payload_table)` queues a custom event; Lua
handlers run when the event loop drains it.
### paper.keys
```lua
paper.keys.map(mode, key, command)
```
- `mode`: `"normal"`, `"insert"`, `"visual"`, or `"*"` (all modes)
- `key`: e.g. `"U"`, `"<C-t>"`, `"gg"`
- `command`: any registered command name (built-in or `paper.commands.register`)
Keymaps resolve on mode only — there is no buffer-kind concept.
### paper.buffer
Direct access to the document buffer:
- `paper.buffer.content()` — full text
- `paper.buffer.set_content(text)`
- `paper.buffer.insert_text(text)` — at cursor
- `paper.buffer.cursor()` — `{ row, col }` (1-based)
- `paper.buffer.move_to(row)` — move cursor to row
### paper.cmd / paper.open / paper.save
Queue an editor command for the event loop:
```lua
paper.cmd("down") -- any M-x command
paper.open("/path/to/file") -- sugar for paper.cmd("open ...")
paper.save() -- sugar for paper.cmd("save")
```
Commands run through the real command registry; errors are echoed.
### paper.after
```lua
paper.after(500, function()
paper.cmd("message half a second passed")
end)
```
Schedules a Lua callback after `ms` milliseconds. Timers fire on the
editor's event loop (same tick as their queued side effects) — no
threads, no busy waiting.
### paper.terminal
```lua
paper.terminal.open() -- focus the terminal panel (Terminal mode)
paper.terminal.send("ls -la") -- write text to the terminal's shell
```
The terminal panel is a real buffer (named "terminal"): switch to it,
search it, yank from it. Its lines always mirror what is on screen —
the styled cell grid lives in the terminal extension, which claims the
panel's rendering.
The terminal scrolls: PageUp/PageDown page through history (10,000
rows), the mouse wheel scrolls it too, and any keypress snaps back to
the live output.
Escape hatches (usable inside Terminal mode):
- `M-x` — command prompt (minibuffer)
- `M-n` / `M-p` — next / previous buffer
- `Esc` — leave Terminal mode, back to Normal
- `Ctrl-q` — quit
Esc exits Terminal mode back to Normal. Ctrl-q still quits from anywhere.
### paper.panels
Panels are named buffers — same mechanism as the built-in `statusbar`
and `echo` panels:
```lua
paper.panels.create("notes")
paper.panel.write("notes", "hello from lua")
```
`paper.panel.write` calls made during config load are queued and flushed
once the panels exist; later writes deliver on the next event-loop tick.
### paper.extensions
`paper.extensions.list()` — names of active extensions.
## Extensions
Installable extensions live in `~/.config/paperos/extensions/<name>/`
with a `manifest.json`:
```json
{
"name": "hello",
"version": "0.1.0",
"description": "Greets",
"author": "you",
"depends": [],
"provides": []
}
```
Enable by symlinking into `extensions-active/`:
```bash
ln -s ~/.config/paperos/extensions/hello ~/.config/paperos/extensions-active/hello
```
Active extensions' `init.lua` files execute at startup in dependency
order (topological sort of `depends`).
## User modules
Any `.lua` file next to `init.lua` is requireable:
```lua
-- mymod.lua
return { setup = function() paper.config.set("ui.line_numbers", "false") end }
-- init.lua
require("mymod").setup()
```