commit 2affb8373f3f52ff3dba45508ff0fe4e6d1eda6b
parent 9c3099f0cf0d1e9aa4edba13c5b5f6d3575aa18d
Author: Justin M. Keyes <justinkz@gmail.com>
Date: Tue, 26 Aug 2025 19:33:16 -0400
docs: api events
Diffstat:
7 files changed, 133 insertions(+), 70 deletions(-)
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
@@ -255,19 +255,6 @@ The idea is "versionless evolution", in the words of Rich Hickey:
- Strengthening a promise should be a compatible change.
==============================================================================
-Global events *api-global-events*
-
-When a client invokes an API request as an async notification, it is not
-possible for Nvim to send an error response. Instead, in case of error, the
-following notification will be sent to the client:
-
- *nvim_error_event*
-nvim_error_event[{type}, {message}]
-
-{type} is a numeric id as defined by `api_info().error_types`, and {message} is
-a string with the error message.
-
-==============================================================================
Buffer update events *api-buffer-updates*
API clients can "attach" to Nvim buffers to subscribe to buffer update events.
@@ -554,6 +541,38 @@ and deleting extmarks is not a buffer change, thus new undo states are not
created for extmark changes.
==============================================================================
+Global Events *api-events*
+
+nvim_error_event({type}, {msg}) *nvim_error_event*
+ Emitted on the client channel if an async API request responds with an
+ error.
+
+ Attributes: ~
+ |RPC| only
+
+ Parameters: ~
+ • {type} (`integer`) Error type id as defined by
+ `api_info().error_types`.
+ • {msg} (`string`) Error message.
+
+nvim_ui_term_event({event}, {value}) *nvim_ui_term_event*
+ Emitted by the TUI client to signal when a host-terminal event occurred.
+
+ Supports these events:
+ • "termresponse": The host-terminal sent a DA1, OSC, DCS, or APC response
+ sequence to Nvim. The payload is the received response. Sets
+ |v:termresponse| and fires |TermResponse|.
+
+ Attributes: ~
+ |RPC| only
+ Since: 0.10.0
+
+ Parameters: ~
+ • {event} (`string`) Event name
+ • {value} (`any`) Event payload
+
+
+==============================================================================
Global Functions *api-global*
nvim_chan_send({chan}, {data}) *nvim_chan_send()*
@@ -3660,22 +3679,6 @@ nvim_ui_set_option({name}, {value}) *nvim_ui_set_option()*
• {name} (`string`)
• {value} (`any`)
-nvim_ui_term_event({event}, {value}) *nvim_ui_term_event()*
- Tells Nvim when a host-terminal event occurred.
-
- Supports these events:
- • "termresponse": The host-terminal sent a DA1, OSC, DCS, or APC response
- sequence to Nvim. The payload is the received response. Sets
- |v:termresponse| and fires |TermResponse|.
-
- Attributes: ~
- |RPC| only
- Since: 0.10.0
-
- Parameters: ~
- • {event} (`string`) Event name
- • {value} (`any`) Event payload
-
nvim_ui_try_resize({width}, {height}) *nvim_ui_try_resize()*
Attributes: ~
diff --git a/src/gen/gen_api_dispatch.lua b/src/gen/gen_api_dispatch.lua
@@ -395,6 +395,7 @@ output:write([[
#include "nvim/api/buffer.h"
#include "nvim/api/command.h"
#include "nvim/api/deprecated.h"
+#include "nvim/api/events.h"
#include "nvim/api/extmark.h"
#include "nvim/api/options.h"
#include "nvim/api/tabpage.h"
diff --git a/src/gen/gen_vimdoc.lua b/src/gen/gen_vimdoc.lua
@@ -1,5 +1,8 @@
#!/usr/bin/env -S nvim -l
---- Generates Nvim :help docs from Lua/C docstrings
+--- Generates Nvim :help docs from Lua/C docstrings.
+---
+--- Usage:
+--- make doc
---
--- The generated :help text for each function is formatted as follows:
--- - Max width of 78 columns (`TEXT_WIDTH`).
@@ -106,6 +109,7 @@ local config = {
filename = 'api.txt',
section_order = {
-- Sections at the top, in a specific order:
+ 'events.c',
'vim.c',
'vimscript.c',
@@ -126,11 +130,22 @@ local config = {
['vim.c'] = 'Global',
},
section_fmt = function(name)
+ if name == 'Events' then
+ return 'Global Events'
+ end
+
return name .. ' Functions'
end,
helptag_fmt = function(name)
return fmt('api-%s', name:lower())
end,
+ fn_helptag_fmt = function(fun)
+ local name = fun.name
+ if vim.endswith(name, '_event') then
+ return name
+ end
+ return fn_helptag_fmt_common(fun)
+ end,
},
lua = {
filename = 'lua.txt',
diff --git a/src/nvim/api/events.c b/src/nvim/api/events.c
@@ -0,0 +1,76 @@
+#include <assert.h>
+#include <inttypes.h>
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "klib/kvec.h"
+#include "nvim/api/events.h"
+#include "nvim/api/private/converter.h"
+#include "nvim/api/private/defs.h"
+#include "nvim/api/private/helpers.h"
+#include "nvim/api/private/validate.h"
+#include "nvim/api/ui.h"
+#include "nvim/assert_defs.h"
+#include "nvim/autocmd.h"
+#include "nvim/autocmd_defs.h"
+#include "nvim/channel.h"
+#include "nvim/channel_defs.h"
+#include "nvim/eval.h"
+#include "nvim/globals.h"
+#include "nvim/main.h"
+#include "nvim/map_defs.h"
+#include "nvim/memory.h"
+#include "nvim/memory_defs.h"
+#include "nvim/msgpack_rpc/channel.h"
+#include "nvim/msgpack_rpc/channel_defs.h"
+#include "nvim/msgpack_rpc/packer.h"
+#include "nvim/msgpack_rpc/packer_defs.h"
+#include "nvim/types_defs.h"
+#include "nvim/ui.h"
+
+/// Emitted on the client channel if an async API request responds with an error.
+///
+/// @param channel_id
+/// @param type Error type id as defined by `api_info().error_types`.
+/// @param msg Error message.
+void nvim_error_event(uint64_t channel_id, Integer type, String msg)
+ FUNC_API_REMOTE_ONLY
+{
+ // TODO(bfredl): consider printing message to user, as will be relevant
+ // if we fork nvim processes as async workers
+ ELOG("async error on channel %" PRId64 ": %s", channel_id, msg.size ? msg.data : "");
+}
+
+/// Emitted by the TUI client to signal when a host-terminal event occurred.
+///
+/// Supports these events:
+///
+/// - "termresponse": The host-terminal sent a DA1, OSC, DCS, or APC response sequence to Nvim.
+/// The payload is the received response. Sets |v:termresponse| and fires
+/// |TermResponse|.
+///
+/// @param channel_id
+/// @param event Event name
+/// @param value Event payload
+/// @param[out] err Error details, if any.
+void nvim_ui_term_event(uint64_t channel_id, String event, Object value, Error *err)
+ FUNC_API_SINCE(12) FUNC_API_REMOTE_ONLY
+{
+ if (strequal("termresponse", event.data)) {
+ if (value.type != kObjectTypeString) {
+ api_set_error(err, kErrorTypeValidation, "termresponse must be a string");
+ return;
+ }
+
+ const String termresponse = value.data.string;
+ set_vim_var_string(VV_TERMRESPONSE, termresponse.data, (ptrdiff_t)termresponse.size);
+
+ MAXSIZE_TEMP_DICT(data, 1);
+ PUT_C(data, "sequence", value);
+ apply_autocmds_group(EVENT_TERMRESPONSE, NULL, NULL, true, AUGROUP_ALL, NULL, NULL,
+ &DICT_OBJ(data));
+ }
+}
diff --git a/src/nvim/api/events.h b/src/nvim/api/events.h
@@ -0,0 +1,8 @@
+#pragma once
+
+#include <stdint.h> // IWYU pragma: keep
+
+#include "nvim/api/keysets_defs.h" // IWYU pragma: keep
+#include "nvim/api/private/defs.h" // IWYU pragma: keep
+
+#include "api/events.h.generated.h"
diff --git a/src/nvim/api/ui.c b/src/nvim/api/ui.c
@@ -567,37 +567,6 @@ void nvim_ui_pum_set_bounds(uint64_t channel_id, Float width, Float height, Floa
ui->pum_pos = true;
}
-/// Tells Nvim when a host-terminal event occurred.
-///
-/// Supports these events:
-///
-/// - "termresponse": The host-terminal sent a DA1, OSC, DCS, or APC response sequence to Nvim.
-/// The payload is the received response. Sets |v:termresponse| and fires
-/// |TermResponse|.
-///
-/// @param channel_id
-/// @param event Event name
-/// @param value Event payload
-/// @param[out] err Error details, if any.
-void nvim_ui_term_event(uint64_t channel_id, String event, Object value, Error *err)
- FUNC_API_SINCE(12) FUNC_API_REMOTE_ONLY
-{
- if (strequal("termresponse", event.data)) {
- if (value.type != kObjectTypeString) {
- api_set_error(err, kErrorTypeValidation, "termresponse must be a string");
- return;
- }
-
- const String termresponse = value.data.string;
- set_vim_var_string(VV_TERMRESPONSE, termresponse.data, (ptrdiff_t)termresponse.size);
-
- MAXSIZE_TEMP_DICT(data, 1);
- PUT_C(data, "sequence", value);
- apply_autocmds_group(EVENT_TERMRESPONSE, NULL, NULL, true, AUGROUP_ALL, NULL, NULL,
- &DICT_OBJ(data));
- }
-}
-
static void flush_event(RemoteUI *ui)
{
if (ui->cur_event) {
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
@@ -2222,15 +2222,6 @@ DictAs(eval_statusline_ret) nvim_eval_statusline(String str, Dict(eval_statuslin
return result;
}
-/// @nodoc
-void nvim_error_event(uint64_t channel_id, Integer lvl, String data)
- FUNC_API_REMOTE_ONLY
-{
- // TODO(bfredl): consider printing message to user, as will be relevant
- // if we fork nvim processes as async workers
- ELOG("async error on channel %" PRId64 ": %s", channel_id, data.size ? data.data : "");
-}
-
/// EXPERIMENTAL: this API may change in the future.
///
/// Sets info for the completion item at the given index. If the info text was shown in a window,
