nx.buf

nx.buf.name(bufnr)

nx.buf.name(bufnr) -> string [alias nvim_buf_get_name / vim.fn.bufname]: the full name (path) of buffer bufnr; 0 / nil means the current buffer. Returns “” for an unnamed or unknown buffer. Read from the buffer mirror, so it can name any open buffer — e.g. a custom ‘tabline’ labelling a buffer shown in another tab.

_{Defined in api.lua.}

nx.buf.current()

The buffer / window / cursor getters read the nx._bufs / nx._cur_* mirror the server refreshes before each Lua entry, so they return live state as of the start of this chunk. There is deliberately no buffer mutation surface here (no nx.buf.set_lines): plugins supply data through the higher-level surfaces, per this file’s header. Throughout, a bufnr of 0 / nil means the current buffer.

nx.buf.current() -> bufnr [alias nvim_get_current_buf]: the current buffer’s number (0 if there is none).

_{Defined in api.lua.}

nx.buf.call(buf, fn)

nx.buf.call(buf, fn) -> any [alias nvim_buf_call]: run fn with buf (0/nil = current) installed as the current-buffer context, then restore the previous context and return whatever fn returned. Use it so buffer-relative lookups inside fn (name, options) resolve against buf. An error in fn propagates.

_{Defined in api.lua.}

nx.buf.is_loaded(bufnr)

nx.buf.is_loaded(bufnr) -> bool [alias nvim_buf_is_loaded]: whether bufnr (0/nil = current) names a buffer that is loaded into memory. Backed by the buffer mirror, which carries every loaded buffer.

_{Defined in api.lua.}

nx.buf.is_valid(bufnr)

nx.buf.is_valid(bufnr) -> bool [alias nvim_buf_is_valid]: whether bufnr (0/nil = current) names a buffer nxvim knows about. There is no separate “valid but unloaded” state in the mirror yet, so this currently matches nx.buf.is_loaded.

_{Defined in api.lua.}

nx.buf.line_count(bufnr)

nx.buf.line_count(bufnr) -> integer [alias nvim_buf_line_count]: the number of lines in bufnr (0/nil = current); 0 for an unknown buffer.

_{Defined in api.lua.}

nx.buf.offset(bufnr, index)

nx.buf.offset(bufnr, index) -> integer [alias nvim_buf_get_offset]: the byte offset at which 0-based line index starts — the sum of every preceding line’s bytes plus its newline. index == line_count gives the buffer’s total byte length. Returns -1 for an unknown buffer.

_{Defined in api.lua.}

nx.buf.text(bufnr, start_row, start_col, end_row, end_col, _opts)

nx.buf.text(bufnr, start_row, start_col, end_row, end_col[, opts]) -> lines [alias nvim_buf_get_text]: the text of bufnr spanning (start_row, start_col) up to (end_row, end_col), returned as a list of lines (the span split on newlines). Rows are 0-based; columns are 0-based byte indices into their line; the end position is exclusive. Use this for a sub-line span — use nx.buf.lines for whole lines.

_{Defined in api.lua.}

nx.buf.lines(bufnr, start, end_, strict)

nx.buf.lines(bufnr, start, end_[, strict]) -> lines [alias nvim_buf_get_lines]: the lines of bufnr (0/nil = current) in the 0-based, end-EXCLUSIVE range [start, end_). Negative indices count back from the end (-1 is one past the last line), so (0, -1) is the whole buffer. With strict true an out-of-range index errors; otherwise indices clamp into range. Returns a list of strings, each without its trailing newline.

_{Defined in api.lua.}

nx.buf.set_lines(bufnr, start, end_, strict, replacement)

nx.buf.set_lines(bufnr, start, end_, strict, replacement) -> promise [alias nvim_buf_set_lines]: replace lines [start, end_) of bufnr (0/nil = current) with replacement (a list of whole-line strings), 0-based and end-EXCLUSIVE. Negative indices count back from the end (-1 is one past the last line), so (0, -1, …) replaces the WHOLE buffer and (n, n, …, { "x" }) appends. With strict true an out-of-range index errors; otherwise indices clamp.

This is the editor’s ONE buffer-text mutation, and it is ASYNCHRONOUS: the Lua VM cannot touch the live buffer mid-chunk, so the edit is QUEUED and applied right after this chunk. The returned promise fulfils (with nil) on the next tick — once the edit has landed and the buffer mirror reflects it — so nx.await(nx.buf.set_lines(…)) is the point at which a following nx.buf.lines read sees the new content. The shape and the buffer’s modifiability are validated SYNCHRONOUSLY and raise (fail loud) before anything is queued: a non-table replacement, a non-string / newline-bearing line, an unknown buffer, a nomodifiable buffer, or (under strict) an out-of-range index. A read-only buffer KIND (terminal / nx.view / quickfix) is refused loudly server-side.

_{Defined in api.lua.}

nx.buf.search(bufnr, pattern, opts)

nx.buf.search(bufnr, pattern, opts) -> match | nil: find pattern in bufnr (0/nil = current) over the buffer mirror, line by line. The native counterpart to scanning lines in Lua — it runs the match in Rust (the regex crate or the vim engine) so a plugin can jump straight to a section (a conflict marker, a heading).

opts (all optional): plain = false – literal substring (ignores engine) engine = “pcre” | “vim” – regex dialect (default “pcre”) from = { line=1, col=0 } – start position: 1-based line, 0-based byte col backward = false – search upward from from instead of down ignorecase = false – case-insensitive match

Returns nil when there is no match, else: { line, col, end_line, end_col, text, captures } with line/end_line 1-based, col/end_col 0-based byte offsets (end exclusive), text the matched substring, and captures the submatch strings (\1.., “” for a group that didn’t participate). Matching is line-by-line, so a multi-line (\n-spanning) pattern is not supported.

_{Defined in api.lua.}

nx.buf.set_extmark(buffer, ns, line, col, opts)

nx.buf.set_extmark(buffer, ns, line, col[, opts]) -> id [alias nvim_buf_set_extmark]: place (or update, via opts.id) an extmark in buffer under namespace ns (see nx.ns.create) at 0-based line / col (col a byte offset). opts carries the highlight-relevant attrs — end_row / end_col for a ranged mark, hl_group, priority, … — and an unsupported decoration key fails loud rather than being ignored. Returns the mark id. The mutation is queued for the server, but the mirror is written through, so a read later in this chunk sees it.

_{Defined in api.lua.}

nx.buf.del_extmark(buffer, ns, id)

nx.buf.del_extmark(buffer, ns, id) -> bool [alias nvim_buf_del_extmark]: remove mark id of namespace ns from buffer. Returns whether the mark existed.

_{Defined in api.lua.}

nx.buf.clear_namespace(buffer, ns, line_start, line_end)

nx.buf.clear_namespace(buffer, ns, line_start, line_end) [alias nvim_buf_clear_namespace]: drop namespace ns’s extmarks in buffer whose line is in the 0-based range [line_start, line_end) — line_end == -1 means to the end of the buffer. ns == -1 clears every namespace.

_{Defined in api.lua.}

nx.buf.extmarks(buffer, ns, start, end_, opts)

nx.buf.extmarks(buffer, ns, start, end_[, opts]) -> list [alias nvim_buf_get_extmarks]: the extmarks of namespace ns in buffer within the position range start..end_ — each bound is 0 (buffer start), -1 (buffer end), or a {row, col} pair. Entries come in (row, col, id) order, each {id, row, col} (or {id, row, col, details} with opts.details). ns == -1 returns marks from every namespace. Reads the mirror, so it reflects marks set earlier in this chunk; positions are current as of chunk start.

_{Defined in api.lua.}

nx.buf.set_option(buf, name, value)

nx.buf.set_option(buf, name, value) [alias nvim_buf_set_option]: set buffer-local option name to value on buf (0/nil = current). A pre-0.10 accessor kept because plugins call it pervasively (bufhidden / modifiable / filetype / buftype on scratch buffers); in new code prefer nx.option.set(name, value, { buf = buf }), which this wraps.

_{Defined in api.lua.}

nx.buf.get_option(buf, name)

nx.buf.get_option(buf, name) -> value [alias nvim_buf_get_option]: read buffer- local option name from buf (0/nil = current) — the read counterpart of nx.buf.set_option. In new code prefer nx.option.get(name, { buf = buf }).

_{Defined in api.lua.}

nx.buf.list(opts)

nx.buf.list([opts]) -> list of bufnr [alias nvim_list_bufs, which always lists all]: the buffer handles the mirror knows, ascending. By default every buffer across every layer (main area + all docks). Pass { focused = true } to list only the focused layer’s buffers — the per-region list (:ls is scoped the same way), so a dock reports just its own buffers and the main area just its own.

_{Defined in api.lua.}

nx.buf.getline(buf, lnum, lend)

nx.buf.getline(buf, lnum[, end]) [alias vim.fn.getbufline]: lines lnum..end (1-based inclusive) of a buffer, or just lnum when end is omitted. Wraps nx.buf.lines (0-based, end-exclusive). An out-of-range request yields {} (vim).

_{Defined in api.lua.}

nx.buf.nr(expr)

nx.buf.nr(expr) [alias vim.fn.bufnr]: the buffer number for expr. “” / “%” / nil / 0 -> current buffer; “$” -> the last (largest) buffer number; a string -> the loaded buffer whose name matches (exact, else suffix), -1 when none. Backed by the Phase-6 nx._bufs mirror.

_{Defined in api.lua.}