diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 067e147145..7a04bb47f0 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -254,19 +254,6 @@ The idea is "versionless evolution", in the words of Rich Hickey: - Relaxing a requirement should be a compatible change. - 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* @@ -553,6 +540,38 @@ Extmark positions changed by an edit will be restored on undo/redo. Creating 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* @@ -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 index e27d322f5a..b62f1bfeb6 100644 --- 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 index ba96008cef..0450c46f62 100755 --- 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 new file mode 100644 index 0000000000..077f04bda3 --- /dev/null +++ b/src/nvim/api/events.c @@ -0,0 +1,76 @@ +#include +#include +#include +#include +#include +#include +#include + +#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 new file mode 100644 index 0000000000..fca73b6b08 --- /dev/null +++ b/src/nvim/api/events.h @@ -0,0 +1,8 @@ +#pragma once + +#include // 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 index 654da61187..b56e329847 100644 --- 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 index 097300edff..400298af35 100644 --- 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,