btv.autocmd

btv.autocmd.create(event, opts)

btv.autocmd.create(event, opts) -> id [alias nvim_create_autocmd]: run something whenever event fires. Returns the autocmd’s numeric id (pass it to btv.autocmd.del to remove it). event is an event name ("FileType", "BufEnter", …) or a list of names to share one handler — see the autocommand events reference for the events bemtvi emits and what each carries. neovim aliases ("BufRead" -> BufReadPost, "BufWrite" -> BufWritePre, "BufCreate" -> BufAdd, "FileEncoding" -> EncodingChanged) are accepted and canonicalized to the real event.

opts fields:

• callback — a function run when the event fires; OR command — an ex-command string queued instead. Provide one of the two.
• pattern — a glob (or list of globs) the event’s match string is tested against (e.g. "*.lua", { "*.c", "*.h" }). Omitted / "*" matches all.
• group — an augroup, by numeric id or by name (see btv.augroup.create). Ties this autocmd to the group so a later clear of that group drops it.
• buffer — make it buffer-local: it then fires only for that buffer (and pattern is ignored). 0 resolves to the current buffer at registration time.
• once — fire once, then auto-remove. desc — a human description.
• timeout — how many milliseconds the editor waits for this handler’s returned promise before warning and moving on (default 500). It bounds the wait, never the delivery: the work keeps running and late subscribers are still served. Raise it for a handler you know is slow (a first LSP spawn) so it does not warn on every open. Ignored by the hot-path events, whose handlers must be synchronous.

The callback receives one table describing the event: { id, event, match, buf, file, data } — id this autocmd’s id, event the event name, match the matched pattern string, buf the buffer number, file its name, and data an event-specific payload (e.g. LspAttach carries { client_id = … }), nil for most events.

An invalid glob in pattern raises here, at registration, naming the pattern and the reason — an autocmd that could never match is a typo, and the alternative is one that silently never fires for the rest of the session.

btv.autocmd.create("FileType", {
  pattern = "markdown",
  callback = function(ev)
    btv.bo[ev.buf].textwidth = 80
  end,
})

_{Defined in autocmd.lua.}

btv.autocmd.del(id)

btv.autocmd.del(id) [alias nvim_del_autocmd]: remove the autocmd with this id, so it stops firing.

_{Defined in autocmd.lua.}

btv.autocmd.pending()

btv.autocmd.pending() -> the autocmd handler promises still in flight past their settle budget, as { event, buf, site, elapsed_ms, budget } entries. A handler that hangs forever never settles and so never warns on completion — this is where it stays visible. Inspect with :lua print(vim.inspect(btv.autocmd.pending())).

_{Defined in autocmd.lua.}

btv.autocmd.exec(event, opts)

btv.autocmd.exec(event, opts) [alias nvim_exec_autocmds]: fire event (or a list of events) manually. opts.pattern (string or list) is matched as in registration; opts.buffer supplies the buffer context (defaulting to the current snapshot buffer), and the callback’s args.file is the snapshot name when firing for it. opts.data is an arbitrary payload delivered to each handler as args.data (e.g. btv.autocmd.exec("User", { pattern = "MyEvent", data = … })).

opts.group (an augroup id or name) narrows the fire to THAT group’s handlers. Reach for it when a plugin needs to re-run its own handlers for a buffer — a late-loading plugin catching up on a FileType that already fired, say — without re-broadcasting the event to every other subscriber (the LSP dispatcher, treesitter, the user’s own autocmds), which would make them redo work they have already correctly done. An unknown group name fails loud.

_{Defined in autocmd.lua.}

btv.autocmd.get(opts)

btv.autocmd.get(opts) [alias nvim_get_autocmds]: introspect the registered autocmds — a debugging affordance for confirming what clear/del left behind. Returns a list of {id, event, group, group_name, pattern, buffer, command, site} entries — site being the "src:line" the autocmd was registered at — optionally filtered by opts.event (string or list) and opts.group (id or name). Run it interactively as :lua print(vim.inspect(btv.autocmd.get({}))).

_{Defined in autocmd.lua.}

btv.autocmd.clear(opts)

btv.autocmd.clear(opts) [alias nvim_clear_autocmds]: remove every autocmd matching the filter — the bulk analogue of btv.autocmd.del. opts.event (string/list), opts.group (id or name), opts.buffer, and opts.pattern (string/list) all narrow the set; an empty opts clears everything. Mirrors btv.autocmd.get’s matching.

_{Defined in autocmd.lua.}