btv.qf

btv.qf.actions.jump()

btv.qf.actions.jump(): the default <CR> action in the quickfix window — jump to the entry on the cursor’s line. Bound buffer-locally as a default map by the FileType qf autocmd, so a user <CR> map overrides it (the rebindable panel-action pattern; cf. btv.buffers.actions.open).

_{Defined in keymap.lua.}

btv.qf.getqflist(what)

btv.qf.getqflist([what]) -> list | dict [aliases btv.getqflist / vim.fn.getqflist]: the quickfix list. With no argument (or a non-table), returns the array of entry dicts (a shallow copy of the btv._qflist mirror the server pushes). With a what dict, returns a dict carrying only the requested keys (title / items / size).

_{Defined in vimfn.lua.}

btv.qf.setqflist(list, action, what)

btv.qf.setqflist(list[, action[, what]]) -> 0 [aliases btv.setqflist / vim.fn.setqflist]: populate the quickfix list. list is an array of entry dicts; action is " " (new / the default), "a" (append), or "r" (replace current). what may instead carry lines (raw output parsed against efm), items, title, or efm. The work happens server-side (a queued op), so the parsed result is visible to btv.qf.getqflist() only after the server drains the op — read it on a later tick.

_{Defined in vimfn.lua.}

btv.qf.getloclist(winnr, what)

btv.qf.getloclist(winnr[, what]) -> list | dict [aliases btv.getloclist / vim.fn.getloclist]: the location list of window winnr (0 = current window; otherwise an bemtvi window id, NOT vim’s 1-based window number). Same return shape as btv.qf.getqflist; an empty list when the window has none.

_{Defined in vimfn.lua.}

btv.qf.setloclist(winnr, list, action, what)

btv.qf.setloclist(winnr, list[, action[, what]]) -> 0 [aliases btv.setloclist / vim.fn.setloclist]: populate the location list of window winnr (0 = current window; otherwise an bemtvi window id). Same list/action/what semantics as btv.qf.setqflist, only scoped to a window. Queued server-side like setqflist.

_{Defined in vimfn.lua.}

btv.qf.send_to_loclist(list, opts)

send_to_loclist: results -> a (new) location list. add_to_loclist: append.

_{Defined in vimfn.lua.}

btv.qf.add_to_loclist(list, opts)

No documentation comment in the prelude.

_{Defined in vimfn.lua.}

btv.qf.send_to_qflist(list, opts)

send_to_qflist: results -> the global quickfix list. add_to_qflist: append.

_{Defined in vimfn.lua.}

btv.qf.add_to_qflist(list, opts)

No documentation comment in the prelude.

_{Defined in vimfn.lua.}

btv.qf.list(name, items, opts)

btv.qf.list(name, items[, opts]): create or replace the named list name from items (an array of entry dicts, the same shape setqflist takes), repainting its tab if open. Does NOT open or focus the tab — call btv.qf.show(name) for that.

• opts.title (string) — the list title shown in the dock tab (defaults to name).
• opts.action (string) — "r" (default, replace in place) / " " (push a new list onto the stack) / "a" (append to the current list).

Returns the name.

_{Defined in vimfn.lua.}

btv.qf.show(name)

btv.qf.show(name): open or focus the named list name’s bottom-dock tab — the clean, window-independent reopen (no set_current / on_next_tick dance; the open is sequenced server-side after any btv.qf.list queued in the same tick). Showing a name with no items yet opens an empty tab. Returns the name.

_{Defined in vimfn.lua.}

btv.qf.drop(name)

btv.qf.drop(name): forget the named list name — close its dock tab if open and remove its contents from the editor. A no-op for a name that was never used.

_{Defined in vimfn.lua.}

btv.qf.open(height)

btv.qf.open([height]) [wraps :copen]: open the quickfix window, optionally height rows tall.

_{Defined in vimfn.lua.}

btv.qf.close()

btv.qf.close() [wraps :cclose]: close the quickfix window.

_{Defined in vimfn.lua.}

btv.qf.next()

btv.qf.next() [wraps :cnext]: jump to the next entry in the quickfix list.

_{Defined in vimfn.lua.}

btv.qf.prev()

btv.qf.prev() [wraps :cprev]: jump to the previous entry in the quickfix list.

_{Defined in vimfn.lua.}

btv.qf.older(count)

btv.qf.older([count]) [wraps :colder]: go to an older quickfix list in the stack (count lists back, default 1).

_{Defined in vimfn.lua.}

btv.qf.newer(count)

btv.qf.newer([count]) [wraps :cnewer]: go to a newer quickfix list in the stack (count lists forward, default 1).

_{Defined in vimfn.lua.}

btv.qf.lopen(height)

The location-list counterparts of the quickfix window / navigation wrappers above — thin wrappers over the :l* ex-commands, acting on the CURRENT window’s location list rather than the global quickfix list. btv.qf.lopen([height]) [wraps :lopen]: open the location-list window, optionally height rows tall.

_{Defined in vimfn.lua.}

btv.qf.lclose()

btv.qf.lclose() [wraps :lclose]: close the location-list window.

_{Defined in vimfn.lua.}

btv.qf.lnext()

btv.qf.lnext() [wraps :lnext]: jump to the next entry in the location list.

_{Defined in vimfn.lua.}

btv.qf.lprev()

btv.qf.lprev() [wraps :lprev]: jump to the previous entry in the location list.

_{Defined in vimfn.lua.}

btv.qf.lolder(count)

btv.qf.lolder([count]) [wraps :lolder]: go to an older location list in the window’s stack (count lists back, default 1).

_{Defined in vimfn.lua.}

btv.qf.lnewer(count)

btv.qf.lnewer([count]) [wraps :lnewer]: go to a newer location list in the window’s stack (count lists forward, default 1).

_{Defined in vimfn.lua.}

btv.qf.text(src)

btv.qf.text(src): install a custom rendering for the rows of the quickfix window, or restore the built-in one with nil. vim spells this 'quickfixtextfunc'.

src is a string of Lua source — an expression, not a function value — because it runs in the bounded compute sandbox: a second, pure VM with a wall-clock deadline, no editor state and no btv.*. A closure cannot cross between VMs, so the source crosses instead and is compiled there.

Two names are in scope, and the expression returns the row’s text:

item    the entry, as a table (the keys `btv.qf.getqflist()` returns)
idx     its 1-based position in the list

item carries filename, bufnr, module, lnum, end_lnum, col, end_col, vcol, nr, pattern, text, type and valid. The built-in rendering is vim’s file|lnum col N| message:

-- the message first, the location trailing
btv.qf.text([[ item.text .. "  (" .. item.filename .. ":" .. item.lnum .. ")" ]])

-- number the rows, and lead with the severity letter
btv.qf.text([[ idx .. ". [" .. (item.type ~= "" and item.type or "-") .. "] " .. item.text ]])

btv.qf.text(nil)   -- back to the default rendering

One row per entry is a hard rule — the row index is the entry index for <CR>, :cc and the severity colouring — so a newline inside a rendered row is flattened to a space, exactly as the default flattens a multi-line message.

It applies to the quickfix list, every named list (btv.qf.list) and every window’s location list, and installing or clearing it re-renders the ones that are open. The severity colouring (a row tinted by its type) is unaffected: it paints whole rows, whatever text they hold.

The sandbox is stateless: nothing carries from one call to the next, and assigning a global raises. An expression that errors, exceeds its deadline, or returns a non-string reports once and is then uninstalled, with every open list restored to the default rendering.

_{Defined in vimfn.lua.}

btv.qf.parse(src)

btv.qf.parse(src): parse the lines of build output into quickfix entries with a Lua block instead of 'errorformat', or restore 'errorformat' with nil.

src is a string of Lua source — a function body, not a value — because it runs in the bounded compute sandbox: a second, pure VM with a wall-clock deadline, no editor state and no btv.*. A closure cannot cross between VMs, so the source crosses instead and is compiled there. It is a body rather than a single expression because a parser matches and then builds a record, so it ends in its own return.

Two names are in scope, and the block returns one entry table (or nil):

line    the output line to parse
lnum    its 1-based position in the output, not in any file

btv.qf.parse([[
  local file, ln, col, msg = line:match("^(%S+)%((%d+),(%d+)%): (.*)$")
  if not file then return nil end
  return {
    filename = file, lnum = tonumber(ln), col = tonumber(col), text = msg,
    type = msg:find("^error") and "E" or "W",
  }
]])

btv.qf.parse(nil)   -- back to 'errorformat'

The entry may set filename, bufnr, module, lnum, end_lnum, col, end_col, vcol, nr, pattern, text, type and valid — the keys btv.qf.getqflist() returns. Any other key is an error, not an ignored one: a parser that writes line where it meant lnum would otherwise quietly produce entries that cannot be jumped to. valid defaults to vim’s rule (an entry with a line number is jumpable).

Returning nil declines the line, which is not the same as dropping it: like 'errorformat', a line no pattern matched is kept as an invalid entry carrying its raw text, which is what makes :copen show a build’s prose alongside its errors.

It applies wherever 'errorformat' does — :cbuffer, :cfile, :cexpr, setqflist{ lines = … }, :make, :grep — and replaces that pass rather than layering on it, because two parsers disagreeing about one line has no sensible answer.

What it cannot do. The sandbox is stateless: the block sees one line and carries nothing between calls. That rules out errorformat’s multi-line entries (%A/%C/%Z) and its directory stack (%D/%X) — exactly the features that need an accumulator. 'errorformat' stays for those, and stays the default. The trade is readability everywhere else, and output no errorformat can describe at all.

A block that errors, exceeds its deadline, or returns a malformed entry reports once, is uninstalled, and 'errorformat' parses the input instead.

_{Defined in vimfn.lua.}