diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index 6c9e833a80..8e0511f69d 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -226,6 +226,17 @@ autocommands, this doesn't happen. You can use the 'eventignore' option to ignore a number of events or all events. +Events that provide |event-data| have a matching `vim.event..data` type +defined in `runtime/lua/vim/_meta/events.lua`. You can use @cast to narrow +`ev.data` for type-checking and completion: >lua + + vim.api.nvim_create_autocmd('LspAttach', { + callback = function(ev) + ---@cast ev {data: vim.event.lspattach.data} + local client = vim.lsp.get_client_by_id(ev.data.client_id) + end, + }) +< *events* *{event}* Nvim recognizes the following events. Names are case-insensitive. @@ -780,10 +791,11 @@ MarkSet After a |mark| is set by |m|, |:mark|, and mark name (e.g. `[ab]` matches `a` or `b`, `*` matches all). - The |event-data| has these keys: + The |event-data| has these keys (type: `vim.event.markset.data`): - name: Mark name (e.g. "a") - line: Mark line. - col: Mark column. + See `vim.event.markset.data`. *MenuPopup* MenuPopup Just before showing the popup menu (under the @@ -831,6 +843,7 @@ Progress *Progress* made for this progress item data: arbitaray data sent with progress message + See `vim.event.progress.data`. Usage example: >lua vim.api.nvim_create_autocmd('Progress', { @@ -1107,6 +1120,7 @@ TermRequest When a |:terminal| child process emits an OSC, position of the cursor when the sequence was received (line number may be <= 0 if the position is no longer in the buffer) + See `vim.event.termrequest.data`. This is triggered even when inside an autocommand defined without |autocmd-nested|. @@ -1117,6 +1131,7 @@ TermResponse When Nvim receives a DA1, OSC, DCS, or APC response from |event-data| is a table with the following fields: - sequence: the received sequence + See `vim.event.termresponse.data`. This is triggered even when inside an autocommand defined without |autocmd-nested|. diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index bf7489814e..1ce60693ae 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -690,7 +690,7 @@ EVENTS *lsp-events* LspAttach *LspAttach* After an LSP client performs "initialize" and attaches to a buffer. The |autocmd-pattern| is the buffer name. The client ID is passed in the - Lua handler |event-data| argument. + Lua handler |event-data| argument. See `vim.event.lspattach.data`. Example: >lua vim.api.nvim_create_autocmd('LspAttach', { @@ -723,7 +723,7 @@ LspAttach *LspAttach* LspDetach *LspDetach* Just before an LSP client detaches from a buffer. The |autocmd-pattern| is the buffer name. The client ID is passed in the Lua handler |event-data| - argument. + argument. See `vim.event.lspdetach.data`. Example: >lua vim.api.nvim_create_autocmd('LspDetach', { @@ -747,7 +747,7 @@ LspNotify *LspNotify* LSP server. The client_id, LSP method, and parameters are sent in the Lua handler - |event-data| table argument. + |event-data| table argument. See `vim.event.lspnotify.data`. Example: >lua vim.api.nvim_create_autocmd('LspNotify', { @@ -775,7 +775,7 @@ LspProgress *LspProgress* The Lua handler |event-data| argument has `client_id` and `params` properties, where `params` is the request params sent by the server (see - `lsp.ProgressParams`). + `lsp.ProgressParams`). See `vim.event.lspprogress.data`. Examples: @@ -814,6 +814,7 @@ LspRequest *LspRequest* request (described at |vim.lsp.Client|, {requests} field). If the request type is `complete`, the request will be deleted from the client's pending requests table after processing the event handlers. + See `vim.event.lsprequest.data`. Example: >lua vim.api.nvim_create_autocmd('LspRequest', { @@ -842,7 +843,7 @@ LspTokenUpdate *LspTokenUpdate* when an existing token becomes visible for the first time. The |autocmd-pattern| is the buffer name. The Lua handler |event-data| argument has the client ID and token (see - |vim.lsp.semantic_tokens.get_at_pos()|). + |vim.lsp.semantic_tokens.get_at_pos()|). See `vim.event.lsptokenupdate.data`. Example: >lua vim.api.nvim_create_autocmd('LspTokenUpdate', { diff --git a/runtime/doc/pack.txt b/runtime/doc/pack.txt index f5e2c2fc6e..dce61f8a93 100644 --- a/runtime/doc/pack.txt +++ b/runtime/doc/pack.txt @@ -369,6 +369,8 @@ Each event populates the following |event-data| fields: • `spec` - plugin's specification with defaults made explicit. • `path` - full path to plugin's directory. +See `vim.event.packchanged.data` and `vim.event.packchangedpre.data`. + These events can be used to execute plugin hooks. For example: >lua local hooks = function(ev) -- Use available |event-data| diff --git a/runtime/lua/vim/_meta/events.lua b/runtime/lua/vim/_meta/events.lua new file mode 100644 index 0000000000..6f70794cf9 --- /dev/null +++ b/runtime/lua/vim/_meta/events.lua @@ -0,0 +1,56 @@ +--- @meta +error('Cannot require a meta file') + +--- @class vim.event.lspattach.data +--- @field client_id integer + +--- @class vim.event.lspdetach.data +--- @field client_id integer + +--- @class vim.event.lspnotify.data +--- @field client_id integer +--- @field method string +--- @field params table + +--- @class vim.event.lspprogress.data +--- @field client_id integer +--- @field params lsp.ProgressParams + +--- @class vim.event.lsprequest.data +--- @field client_id integer +--- @field request_id integer +--- @field request table + +--- @class vim.event.lsptokenupdate.data +--- @field client_id integer +--- @field token table + +--- @class vim.event.markset.data +--- @field name string +--- @field line integer +--- @field col integer + +--- @class vim.event.packchanged.data +--- @field active boolean +--- @field kind string +--- @field spec vim.pack.Spec +--- @field path string + +--- @class vim.event.packchangedpre.data : vim.event.packchanged.data + +--- @class vim.event.progress.data +--- @field id any +--- @field text string[] +--- @field data? table +--- @field percent? integer +--- @field source? string +--- @field status? string +--- @field title? string + +--- @class vim.event.termrequest.data +--- @field sequence string +--- @field terminator string +--- @field cursor integer[] + +--- @class vim.event.termresponse.data +--- @field sequence string diff --git a/runtime/lua/vim/pack.lua b/runtime/lua/vim/pack.lua index 60b1680f7f..ad48d6ce7d 100644 --- a/runtime/lua/vim/pack.lua +++ b/runtime/lua/vim/pack.lua @@ -175,6 +175,8 @@ ---- `spec` - plugin's specification with defaults made explicit. ---- `path` - full path to plugin's directory. --- +---See `vim.event.packchanged.data` and `vim.event.packchangedpre.data`. +--- --- These events can be used to execute plugin hooks. For example: ---```lua ---local hooks = function(ev)