Module core_options

Expand description

Renderer-agnostic options. M.2.0b migrates these from the pre-typed-keys imperative Option::builder() form to the macro-driven declarative form (Design B + D from the mode-architecture.md discussion).

Each option is a unique Rust type emitted by crate::options!. The macro generates the crate::OptionDecl / crate::HasGroup impls, a build_spec() helper that constructs the runtime Option<T> via the existing builder, and a linkme self-registration thunk submitted to crate::OPTION_DECLS. At App boot the registry’s crate::ConfigRegistry::init_from_linkme walks the slice and registers every option without a central register_core_options body.

For backwards compatibility during the transitional M.2.0b/c window, register_core_options runs init_from_linkme and returns a CoreOptions struct populated with the typed handles. Existing callers (config.get(core.tabstop)) continue to work unchanged. M.2.0c migrates the callers to config.get_typed::<Tabstop>() and retires CoreOptions.

Structs§

AiLog: Enables capture of AI-agent output into the per-process log rings. :set ai.log=false disables capture.
AiLogLevel: Default minimum log level for AI-agent log records. Accepted values: error / warn / info / debug / trace.
AutoWrapOption: Whether typing past textwidth breaks the line: off, comments (the default – a long comment wraps, a long string literal does not), or all.
Autoread: When true (the default), a file-backed buffer refreshes when its on-disk content changes out from under the editor (vim’s autoread): an unmodified buffer reloads silently; a buffer with unsaved edits opens a diff resolver rather than clobbering either side. false disables external-change watching for the buffer. Non-file buffers (oil, help, synthetic) are never watched regardless. See docs/dev/architecture/autoread.md.
ClipboardEnabled: When true (default), an explicit yank (y, yy, Visual y) also copies to the system clipboard, and paste of the unnamed register reads it — the clipboard is the default yank target. Delete / change / x stay in registers and never touch the clipboard (the yank-only rule — no incidental clobber). false = pure registers; only the explicit "+ / "* registers reach the clipboard.
CommandLineExpandHeight: MB.2e: how tall the : command line grows when expanded into its full-modal mini-buffer band (<C-x><C-e>). half (default) claims half the frame; full grows as tall as the frame allows (one pane row kept); a bare integer pins a fixed row count. Pure render policy — both peers resolve it against the live frame height via ExpandHeight::rows.
CompletionAutoInsertSingle: When the completion pipeline returns exactly one candidate at popup-open time, insert it directly instead of showing a one-row popup. Only fires at popup-open; narrowing an already-open popup to one candidate while typing does not auto-insert. Disable with :set nocompletion.auto_insert_single to always require an explicit confirm.
CompletionExtraCommitChars: Editor-side commit characters unioned with each LSP server’s per-item commitCharacters. When the insert-completion popup is open and the user types one of these characters, the focused candidate is accepted before the character is inserted. Default empty – only LSP-supplied commit chars fire. Set to e.g. ".,;" to accept on any of those keys globally.
CompletionGhostText: Render the top-ranked candidate’s suffix as a dimmed inline overlay after the cursor while the popup is open (Phase 4.2.g.7 polish). Off by default to keep the live buffer visually quiet; turn on for a vscode-style preview of the most likely completion. Only fires when the cursor sits at end-of-line and the top candidate is a case-insensitive prefix of the typed query.
CompletionSourceBufferWordsPriority: Priority bucket for the gen:buffer-words insert-mode source. Default 100 – baseline; LSP and snippets both outrank it at tied matcher score.
CompletionSourceLspPriority: Priority bucket for the gen:lsp-completion insert-mode completion source. Higher numbers float that source’s items above ties from lower-priority sources (docs/dev/architecture/insert-completion.md §3.4 / §3.6). Default 200; LSP-driven IDE completions usually want to win against local buffer words and snippets at tied score.
CompletionSourcePathPriority: Priority bucket for the gen:path insert-mode source – filesystem entries surfaced when the cursor sits inside a string literal. Default 90 per spec §3.4: below buffer-words 100 (which often matches partial paths too) and above tree-sitter 80.
CompletionSourceSnippetPriority: Priority bucket for the gen:snippet insert-mode source. Default COMPLETION_SOURCE_SNIPPET_DEFAULT_PRIORITY (150) – above buffer-words, below LSP. Per-language overrides land in 4.2.g.5 (3/3); today the value is global.
CompletionSourceTreeSitterPriority: Priority bucket for the gen:tree-sitter-symbol insert-mode source – definition-position identifiers pulled from the buffer’s syntax tree. Default 80, below buffer-words: when LSP is attached for the language, the LSP source has the same names with richer metadata.
CursorLine: Highlight the cursor’s current line with a different background style. Vim’s :set cursorline. Backing option for current-line-highlight-mode (M.7.2). The renderer’s current-line-highlight pipeline lands in M.7.3.
DiagnosticsInlineOption: Where the inline (end-of-line virtual-text) diagnostic summary renders: off, cursor-line (the default — cursor line only, idle-gated, Insert-suppressed), or all (every viewport line).
DiagnosticsMinSeverityOption: Least-severe diagnostic level included in the inline summary: error, warning, info, or hint (the default — include everything). A diagnostic shows when it is as-or-more severe.
ElectricIndent: Re-indent the current line when a closing token is typed (}, ), end, else). Honoured from IN.6.
EmacsKeys: Enable the emacs-keys <C-x> leader tribute. Default on. :set noemacs-keys rebuilds the leader layer empty (live), reclaiming <C-x> for vanilla Normal-mode resolution. See docs/dev/architecture/emacs-keys.md.
EmacsKeysPrefix: The emacs-keys leader prefix — the chord that opens the <C-x> tribute map (docs/dev/architecture/emacs-keys.md). Default <C-x>. Each binding is prefix + suffix, parsed via parse_chord_sequence; a malformed value degrades to an empty tribute (warn, no panic). Live: :set emacs-keys-prefix=… re-pushes the layer.
ExpandTab: Render indentation as spaces rather than tab bytes.
FoldEnable: When false (:set nofoldenable, zi), every fold renders as open regardless of its closed flag. Closed-state is preserved – toggling back restores the previous distribution.
FoldLevel: Folds nested deeper than this level are closed; the rest are open. The outermost fold is level 1, so foldlevel=0 closes everything and foldlevel=1 shows only the top level’s structure. In a multibuffer view that means 0 gives one row per file and 1 gives one row per excerpt.
FoldMethodOption: How folds are produced: manual (zf only), indent (auto from indentation), markdown (ATX heading nesting), or syntax (tree-sitter cascade – markdown for .md, indent otherwise).
FormatIndentChain: Who reindents a range for = – an ordered chain, first available rung wins. Defaults to the tree-sitter engine.
FormatOnSave: Run the :format cascade before :w. A formatter that fails, exits non-zero, or times out never blocks the write – the buffer is saved unformatted. Honoured from IN.9.
FormatPrg: External formatter for :format (vim’s formatprg). Empty (the default) falls back to the built-in per-language table. Honoured from IN.9.
FormatReflowChain: Who reflows a range for gq / gw. Defaults to the built-in textwidth engine.
FormatReformatChain: Who reformats a range for :format, g= and format-on-save. Defaults to the attached language server, then the built-in per-language formatter table – the exact cascade :format carried in Rust before RF.5, now as data.
HelpAproposDisplay: Where :apropos <pattern> opens.
HelpDescribeDisplay: Where :describe-command / :describe-buffer / :describe-key / :describe-option / :describe-event open.
HelpListDisplay: Where state-listing help views open (:ls, :keymap, :options, :describe-events, …).
HelpTopicDisplay: Where :help <topic> opens.
HoverDisplay: Where the hover popup (K) renders. Default floating-cursor (popup floats on the doc; the doc keeps focus); user can flip to popup-cursor (focused popup) or active-pane.
IgnoreCase: Ignore case in search patterns.
IndentGuides: Draw a vertical rule at each level of indentation.
IndentGuidesActive: Draw the block enclosing the cursor in the indent.guide.active style rather than indent.guide. Off leaves every guide uniform.
IndentGuidesChar: Glyph the TUI substitutes into the guide column. The GPU peer paints a one-pixel rule instead and ignores this – a terminal cell cannot hold a hairline, so the two peers approximate the same rule with the means they have. Empty string ⇒ no guides in the TUI.
IndentMethodOption: Where a newly created line’s indent comes from: none (column 0), keep (copy the previous line – vim’s autoindent), or syntax (tree-sitter indents.scm, falling back to keep). A cascade with a named floor, so a language with no query degrades to documented vim behaviour rather than to a silent wrong answer.
KeymapLeader: OM.2b: what <leader> expands to in a binding string. Default <Space> — vim’s historical \\ is an artifact of which keys happened to be free in 1991, and the modern vim world maps leader to space (nvim-orgmode’s documented bindings assume it).
LspDiagnosticsToErrorList: EP.4 (2026-08-10): does the language server feed the core error list?
LspLogCapacity: Per-server log ring capacity at boot. Each LSP server gets its own bounded ring; smaller values shed older records sooner. 0 is allowed (drops every record at the ring boundary – useful for tests / sandboxed runs) but typically users keep the 10k default.
LspLogDisplay: Where :lsp-log / :lsp-trace-log open. Default active-pane (live-tailed log buffers want to live in a real pane).
LspLogLevel: Default LSP log-record minimum level at startup. Accepted values: error / warn / info / debug / trace. The runtime :lsp-log-level command adjusts this live; this option sets the boot value.
LspReferencesToErrorList: EP.6 (2026-08-11): do references queries also populate the core error list?
LspStatusDisplay: Where :lsp-status opens.
MessagesDisplay: Where :messages opens. Default active-pane (a transcript that streams new entries lives best in a pane the user can split / scroll independently).
MessagesFilter: tracing-subscriber::EnvFilter directive controlling which tracing::* events the boot-installed MessagesLayer captures into *messages*. Accepts:
ModelineCenter: Center-zone element layout (centered in the gap between Left and Right). auto (default) is descriptor-driven; built-ins place nothing here, so the effective default is empty. Custom / plugin elements live here.
ModelineLeft: Left-zone element layout — ordered element ids assigned to the left (flush-left) zone, e.g. ["core.mode", "core.path"]. auto (the default) uses each registered element’s own descriptor placement. An explicit list shows exactly those ids, in order; unknown ids are skipped + logged. An empty list ([]) is an explicitly-blank zone.
ModelinePadding: Columns of blank margin at the start (before the Left zone) and end (after the Right zone) of the modeline row — the row’s left/right breathing room. Default 1; 0 flushes content to the pane edges.
ModelineRight: Right-zone element layout (the block is right-aligned, ids in left→right order), e.g. ["lsp", "core.position", "core.lang"]. auto (default) is descriptor-driven.
ModelineSeparator: Separator inserted between elements within a zone. A non-blank value is auto-padded with a space on each side at render time (so :set ui.modeline.separator=| shows | — you give the glyph, the renderer owns the spacing). Blank (the default) ⇒ a single space between elements.
MouseEnabled: Whether the editor captures mouse events from the terminal.
NoFile: Whether the buffer is NOT backed by an on-disk file the editor can save and should track for unsaved changes. false (the default) means :q warns on dirty, :w writes to disk, and the modeline shows [+] for modified state. true (vim’s &buftype = nofile) means the buffer is a transcript / log / overlay whose content is owned by a subsystem; the dirty guard skips it and :w is a no-op. customizable = false — modes contribute the override (messages-mode, lsp-log-mode, help-mode, terminal-mode set NoFile = true); users don’t :set it directly.
Number: Show absolute line numbers in the gutter.
PathRelative: Show buffer-relative paths (modeline, LSP references, etc.) instead of absolute paths. Requires :cd to set the base directory; falls back to absolute when no base is set.
PickerDisplay: Where the picker UI is drawn. "minibuffer" renders vertico-style: prompt sits on the cmdline row and the candidate list fans above it (TUI) / above the status line (GPUI), keeping the buffer fully visible. "popup" renders a centred overlay floating over the buffer area (terminal-friendly when narrow, common in IDE-style editors). Behaviour is identical between the TUI and GPUI peers so users carry the same muscle memory across them. Future variants ("split", "sidebar") may be added without breaking this key.
PickerGrepBackend: Backend binary :picker grep shells out to. "auto" picks the first available of rg, ag, grep in PATH at invocation time. Explicit names ("rg", "ag", "grep") force a specific binary and surface an error if it’s not on PATH. Future plugin-shipped backends can register additional names; the matching logic lives in lattice_picker::picker_sources::grep.
PickerGrepMaxHits: Maximum number of grep hits to surface in one :picker grep invocation. Bounds memory + render time on huge codebases; users hit this rarely (typical pattern matches hundreds of lines, not thousands).
PickerMruCapPerNamespace: Maximum number of MRU entries per (source_id) namespace. On insert past this cap the lowest-frecency entry in the namespace is evicted (prescient-style). Larger values keep long-tail usage history; smaller values keep the cache lean.
PickerMruEnabled: Whether picker MRU (frecency) scoring fires at all. false disables both the bonus snapshot on picker-open and the record-on-accept path – pickers rank by pure match score, ignore prior usage. Persistence keeps working independently (picker.mru.persist); flipping enabled back on resumes ranking using whatever’s still in the cache.
PickerMruPersist: Whether the MRU index persists to disk between runs. false keeps MRU in-memory only; helpful for ephemeral sessions or for users who deliberately want a clean slate each launch. Default true preserves vertico- style “yesterday’s picks still float.”
PickerMruRecencyHalfLifeDays: Recency half-life for the frecency formula, in days. Stored as i64 so :set picker.mru.recency-half-life-days=14 Just Works through the parse-int path; the picker’s Duration machinery converts. Smaller values bias strongly toward “today’s choices”; larger values keep historical usage relevant.
PickerOrderless: Whether a picker query is read as a set of whitespace- separated components (true, the default) or as one literal token (false, the pre-orderless behaviour).
PickerResultDisplay: Where the selected buffer / location lands after a picker accept (:diagnostics, :references, :symbol, :Files, :buffers, :lsp-server-log). Default active-pane; split-h / split-v open the pick in a new sibling pane.
PickerSendOpensProblems: Whether sending a picker’s filtered rows to the error list with <C-q> also opens the *problems* view over the result.
ProjectRootMarkers: Filenames or directory names whose presence marks a project root, in priority order. The walk starts at the buffer’s own directory and stops at the first directory containing any of these, so a crate inside a Cargo workspace is its own project.
ReadOnly: Whether the buffer is read-only (mutating operators reject; :w still permits explicit writes if a path exists). customizable = false because this is mode-driven, not a user-typed config: major modes like help-mode, file-tree-mode, and the LSP log modes contribute ReadOnly = true via Mode::options() (per mode-architecture.md §6.5.3 read-only-mode pattern). Users who want to flip it on / off for a particular buffer use :enable read-only-mode, not :set read-only=true. That minor exists — it is declared in lattice_mode::modes::display and registered with the other foundation modes; the parenthetical here used to read “when that minor mode lands in M.7” long after it had, which is enough to send a reader off to build a second one.
RelativeNumber: Gutter shows distance from the cursor; the cursor’s line shows its absolute number.
Scroll: Lines <C-d> / <C-u> scroll. 0 (vim’s default) means half the window, recomputed as the window resizes.
Scrollbind: Synchronise scrolling across all panes that have scrollbind=true. The option-change handler rebuilds the singleton identity-mapper PaneGroup to contain exactly the current panes with scrollbind=true. Vim’s :set scrollbind / scb. D.0b.
Scrolloff: Minimum visual lines kept above and below the cursor when scrolling.
Shiftwidth: Columns added or removed per indent level – by > / <, <C-t> / <C-d>, =, and auto-indent. Distinct from tabstop, which is the display width of a literal tab byte: conflating them makes “change my indent size” silently reflow every file containing a hard tab.
Sidescroll: Columns to scroll horizontally when the cursor moves off the edge with wrap off. 0 (vim default) jumps so the cursor lands in the middle of the window; a positive value scrolls that many columns at a time. No effect when wrap is on.
Sidescrolloff: Minimum columns kept to the left and right of the cursor when the view scrolls horizontally (wrap off). Horizontal analog of scrolloff. Clamped to half the body width at use.
SignColumnOption: Whether the renderer reserves the gutter sign columns (diagnostics severity + diff sign). yes (default) always reserves them so layout never shifts when a sign appears; no hides them. Help / synthetic buffers set no for clean gutterless rendering — the renderer derives the column layout from this option alone, never from buffer kind / popup / pane.
SignatureDisplay: Where signature help renders. Same default-shape as hover (cursor-anchored floating).
StartOfLine: Whether H / M / L land on the first non-blank of their line (vim’s default) or keep the cursor’s column (nostartofline).
TablineShowOption: When to paint the tabline at the top of the screen.
Tabstop: Number of columns a hard tab character renders as. The cells builder expands each \t to the next multiple of this width (W.4.t). Default 4 (Lattice’s house style; vim’s historical default is 8).
TerminalEscExits: When true, pressing <Esc> inside Terminal-Insert exits back to Normal-in-terminal (so :q, motions, and the rest of the vim grammar are reachable without the <C-\><C-n> chord). When false, <Esc> encodes to \x1b and goes to the PTY — nested programs (vim, htop, less) keep their own Esc semantics.
TerminalScrollbackLines: Maximum scrollback ring size (lines). Set to 0 to disable scrollback entirely (saves RAM on long-running terminals with chatty output). Default 10000 matches the user-facing docs/user/terminal-mode.md table and what most modern terminal emulators ship with.
TextWidth: Target column for reflow (gq / gw) and for wrapping while typing. One measure for both, so the two can never disagree about where the margin is.
TransientMaxRows: MG.41b: how many rows a transient menu may claim before it scrolls.
Whitespace: Show whitespace glyphs (trailing spaces, tabs, leading indentation) as visible markers. Vim’s :set list. Backing option for whitespace-show-mode (M.7.2). The renderer’s whitespace-painting plumbing lands in M.7.3 – today this option is read by the cascade and the mode machinery, but the renderer doesn’t yet emit decorations.
WhitespaceEol: Glyph at end-of-line (vim’s eol listchar). Default empty; ¬ is the conventional choice.
WhitespaceLeading: Glyph for leading whitespace – non-tab indentation at the start of a line. Mirrors emacs whitespace-mode’s indentation highlight. Default ·.
WhitespaceSpace: Glyph for plain spaces in the middle of text (between non-whitespace characters). Most users find this loud; default empty. Set to · to mirror emacs’s space-mark.
WhitespaceTab: Glyph rendered in place of the tab character when whitespace decoration is active. Followed by a space-pad to the next tabstop column. Empty string ⇒ tabs render bare. Default →.
WhitespaceTrailing: Glyph for trailing whitespace (spaces or tabs at end-of-line). Rendered with a trailing style (red by default; theme-driven). Empty ⇒ no decoration. Default ·.
Wrap: Wrap long lines visually instead of horizontal scrolling.
YankRingSize: How many entries the yank ring holds. Every yank and every delete pushes one.

Constants§

COMPLETION_SOURCE_SNIPPET_DEFAULT_PRIORITY: SN.3g: single source for the gen:snippet source default priority, shared by completion.source.snippet.priority’s default (below) and lattice-snippet’s SnippetCompletionMode contribution, so the two can’t drift. Above buffer-words, below LSP.