From 49a7585981cdf7403e76a614558e602a98e64301 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Fri, 23 Jun 2023 12:16:55 +0200 Subject: [PATCH] docs: autocmds, misc --- runtime/doc/api.txt | 6 ++-- runtime/doc/autocmd.txt | 59 +++++++++++++++++++------------------ runtime/doc/builtin.txt | 2 +- runtime/doc/lsp.txt | 20 ++++++++----- runtime/doc/lua-guide.txt | 4 +-- runtime/doc/lua.txt | 8 +++-- runtime/doc/various.txt | 4 +-- runtime/doc/vim_diff.txt | 5 ++-- runtime/lua/vim/_editor.lua | 2 ++ runtime/lua/vim/lsp.lua | 2 +- scripts/gen_vimdoc.py | 2 +- src/nvim/api/buffer.c | 2 +- src/nvim/api/extmark.c | 2 +- 13 files changed, 64 insertions(+), 54 deletions(-) diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 8c79279361..3a3d939cd7 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -209,7 +209,7 @@ any of these approaches: nvim --api-info | python -c 'import msgpack, sys, yaml; yaml.dump(msgpack.unpackb(sys.stdin.buffer.read()), sys.stdout)' < 3. Use the |api_info()| Vimscript function. >vim - :lua print(vim.inspect(vim.fn.api_info())) + :lua vim.print(vim.fn.api_info()) < Example using |filter()| to exclude non-deprecated API functions: >vim :new|put =map(filter(api_info().functions, '!has_key(v:val,''deprecated_since'')'), 'v:val.name') @@ -2030,7 +2030,7 @@ whether a buffer is loaded. nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* Activates buffer-update events on a channel, or as Lua callbacks. - Example (Lua): capture buffer updates in a global `events` variable (use "print(vim.inspect(events))" to see its contents): >lua + Example (Lua): capture buffer updates in a global `events` variable (use "vim.print(events)" to see its contents): >lua events = {} vim.api.nvim_buf_attach(0, false, { on_lines=function(...) table.insert(events, {...}) end}) @@ -2554,7 +2554,7 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts}) local ms = api.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {}) -- Get all marks in this buffer + namespace. local all = api.nvim_buf_get_extmarks(0, ns, 0, -1, {}) - print(vim.inspect(ms)) + vim.print(ms) < Parameters: ~ diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index a782be65e7..ffa7d6282a 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -212,28 +212,27 @@ events. Nvim recognizes the following events. Names are case-insensitive. *BufAdd* -BufAdd Just after creating a new buffer which is - added to the buffer list, or adding a buffer - to the buffer list, a buffer in the buffer - list was renamed. - Not triggered for the initial buffers created - during startup. +BufAdd After adding a new buffer or existing unlisted + buffer to the buffer list (except during + startup, see |VimEnter|), or renaming a listed + buffer. Before |BufEnter|. - NOTE: Current buffer "%" may be different from - the buffer being created "". + NOTE: Current buffer "%" is not the target + buffer "", "". || *BufDelete* BufDelete Before deleting a buffer from the buffer list. The BufUnload may be called first (if the buffer was loaded). Also used just before a buffer in the buffer list is renamed. - NOTE: Current buffer "%" may be different from - the buffer being deleted "" and "". + NOTE: Current buffer "%" is not the target + buffer "", "". || Do not change to another buffer. *BufEnter* -BufEnter After entering a buffer. Useful for setting - options for a file type. Also executed when - starting to edit a buffer. +BufEnter After entering (visiting, switching-to) a new + or existing buffer. Useful for setting + filetype options. Compare |BufNew| which + does not trigger for existing buffers. After |BufAdd|. After |BufReadPost|. *BufFilePost* @@ -248,8 +247,8 @@ BufHidden Before a buffer becomes hidden: when there are the buffer is not unloaded or deleted. Not used for ":qa" or ":q" when exiting Vim. - NOTE: current buffer "%" may be different from - the buffer being unloaded "". + NOTE: Current buffer "%" is not the target + buffer "", "". || *BufLeave* BufLeave Before leaving to another buffer. Also when leaving or closing the current window and the @@ -260,12 +259,14 @@ BufLeave Before leaving to another buffer. Also when BufModifiedSet After the `'modified'` value of a buffer has been changed. *BufNew* -BufNew Just after creating a new buffer. Also used - just after a buffer has been renamed. When - the buffer is added to the buffer list BufAdd - will be triggered too. - NOTE: Current buffer "%" may be different from - the buffer being created "". +BufNew After creating a new buffer (except during + startup, see |VimEnter|) or renaming an + existing buffer. Unlike |BufEnter|, visiting + (switching to) an existing buffer will not + trigger this again. + NOTE: Current buffer "%" is not the target + buffer "", "". || + See also |BufAdd|, |BufNewFile|. *BufNewFile* BufNewFile When starting to edit a file that doesn't exist. Can be used to read in a skeleton @@ -298,8 +299,8 @@ BufUnload Before unloading a buffer, when the text in Before BufDelete. Triggers for all loaded buffers when Vim is going to exit. - NOTE: Current buffer "%" may be different from - the buffer being unloaded "". + NOTE: Current buffer "%" is not the target + buffer "", "". || Do not switch buffers or windows! Not triggered when exiting and v:dying is 2 or more. @@ -319,8 +320,8 @@ BufWinLeave Before a buffer is removed from a window. Not when it's still visible in another window. Also triggered when exiting. Before BufUnload, BufHidden. - NOTE: Current buffer "%" may be different from - the buffer being unloaded "". + NOTE: Current buffer "%" is not the target + buffer "", "". || Not triggered when exiting and v:dying is 2 or more. *BufWipeout* @@ -330,8 +331,8 @@ BufWipeout Before completely deleting a buffer. The buffer list). Also used just before a buffer is renamed (also when it's not in the buffer list). - NOTE: Current buffer "%" may be different from - the buffer being deleted "". + NOTE: Current buffer "%" is not the target + buffer "", "". || Do not change to another buffer. *BufWrite* *BufWritePre* BufWrite or BufWritePre Before writing the whole buffer to a file. @@ -597,8 +598,8 @@ FileChangedShell When Vim notices that the modification time of prompt is not given. |v:fcs_reason| indicates what happened. Set |v:fcs_choice| to control what happens next. - NOTE: Current buffer "%" may be different from - the buffer that was changed "". + NOTE: Current buffer "%" is not the target + buffer "" and "". || *E246* *E811* Cannot switch, jump to or delete buffers. Non-recursive (event cannot trigger itself). diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt index 1cbc9135d3..c8d1d0b25b 100644 --- a/runtime/doc/builtin.txt +++ b/runtime/doc/builtin.txt @@ -656,7 +656,7 @@ api_info() *api_info()* Returns Dictionary of |api-metadata|. View it in a nice human-readable format: > - :lua print(vim.inspect(vim.fn.api_info())) + :lua vim.print(vim.fn.api_info()) append({lnum}, {text}) *append()* When {text} is a |List|: Append each item of the |List| as a diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index 9b168cb9cd..42600e405c 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -154,16 +154,17 @@ The `vim.lsp.buf_…` functions perform operations for all LSP clients attached to the given buffer. |lsp-buf| LSP request/response handlers are implemented as Lua functions (see -|lsp-handler|). The |vim.lsp.handlers| table defines default handlers used -when creating a new client. Keys are LSP method names: >vim - - :lua print(vim.inspect(vim.tbl_keys(vim.lsp.handlers))) -< +|lsp-handler|). *lsp-method* -Methods are the names of requests and notifications as defined by the LSP -specification. These LSP requests/notifications are defined by default in the -Nvim LSP client (but depends on server support): +Requests and notifications defined by the LSP specification are referred to as +"LSP methods". The Nvim LSP client provides default handlers in the global +|vim.lsp.handlers| table, you can list them with this command: >vim + + :lua vim.print(vim.tbl_keys(vim.lsp.handlers)) +< +They are also listed below. Note that handlers depend on server support: they +won't run if your server doesn't support them. - callHierarchy/incomingCalls - callHierarchy/outgoingCalls @@ -190,8 +191,11 @@ Nvim LSP client (but depends on server support): - window/showDocument - window/showMessageRequest - workspace/applyEdit +- workspace/configuration +- workspace/executeCommand - workspace/inlayHint/refresh - workspace/symbol +- workspace/workspaceFolders *lsp-handler* LSP handlers are functions that handle |lsp-response|s to requests made by Nvim diff --git a/runtime/doc/lua-guide.txt b/runtime/doc/lua-guide.txt index 22f51ce8c7..af7f22304d 100644 --- a/runtime/doc/lua-guide.txt +++ b/runtime/doc/lua-guide.txt @@ -218,7 +218,7 @@ Vimscript are automatically converted: print(vim.fn.printf('Hello from %s', 'Lua')) local reversed_list = vim.fn.reverse({ 'a', 'b', 'c' }) - print(vim.inspect(reversed_list)) -- { "c", "b", "a" } + vim.print(reversed_list) -- { "c", "b", "a" } local function print_stdout(chan_id, data, name) print(data[1]) @@ -261,7 +261,7 @@ Data types are converted automatically. For example: key2 = 300 } - print(vim.inspect(vim.g.some_global_variable)) + vim.print(vim.g.some_global_variable) --> { key1 = "value", key2 = 300 } < You can target specific buffers (via number), windows (via |window-ID|), or diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index c3eaf1ae39..822ce4e85a 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -14,7 +14,7 @@ INTRODUCTION *lua-intro* The Lua 5.1 script engine is builtin and always available. Try this command to get an idea of what lurks beneath: >vim - :lua print(vim.inspect(package.loaded)) + :lua vim.print(package.loaded) Nvim includes a "standard library" |lua-stdlib| for Lua. It complements the "editor stdlib" (|builtin-functions| and |Ex-commands|) and the |API|, all of @@ -423,7 +423,7 @@ is unnecessary. You can peek at the module properties: >vim - :lua print(vim.inspect(vim)) + :lua vim.print(vim) Result is something like this: > @@ -1414,6 +1414,7 @@ inspect({object}, {options}) *vim.inspect()* Gets a human-readable representation of the given object. See also: ~ + • |vim.print()| • https://github.com/kikito/inspect.lua • https://github.com/mpeterv/vinspect @@ -1538,6 +1539,7 @@ print({...}) *vim.print()* See also: ~ • |vim.inspect()| + • |:=| region({bufnr}, {pos1}, {pos2}, {regtype}, {inclusive}) *vim.region()* Get a table of lines with start, end columns for a region marked by two @@ -3172,7 +3174,7 @@ Iter:find({self}, {f}) *Iter:find()* any Iter:fold({self}, {init}, {f}) *Iter:fold()* - Fold an iterator or table into a single value. + Fold ("reduce") an iterator or table into a single value. Examples: >lua diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt index 4e2ee14537..1b1dca321b 100644 --- a/runtime/doc/various.txt +++ b/runtime/doc/various.txt @@ -171,8 +171,8 @@ g8 Print the hex values of the bytes used in the Like ":z" or ":z!", but number the lines. *:=* -:= Without arg: Print the last line number. - with args: equivalent to `:lua ={expr}`. see |:lua| +:= [args] Without [args]: prints the last line number. + With [args]: equivalent to `:lua ={expr}`. see |:lua| :{range}= Prints the last line number in {range}. For example, this prints the current line number: > diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index c44595f237..686905537d 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -459,8 +459,9 @@ Lua interface (|lua.txt|): - `:lua print("a\0b")` will print `a^@b`, like with `:echomsg "a\nb"` . In Vim that prints `a` and `b` on separate lines, exactly like `:lua print("a\nb")` . -- `:lua error('TEST')` emits the error “E5105: Error while calling Lua chunk: - [string ""]:1: TEST”, whereas Vim emits only “TEST”. +- `:lua error('TEST')` emits the error: > + E5108: Error executing lua: [string ""]:1: TEST +< whereas Vim emits only "TEST". - Lua has direct access to Nvim |API| via `vim.api`. - Lua package.path and package.cpath are automatically updated according to 'runtimepath': |lua-require|. diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua index e2ed0d980e..ab20c36b17 100644 --- a/runtime/lua/vim/_editor.lua +++ b/runtime/lua/vim/_editor.lua @@ -184,6 +184,7 @@ end --- Gets a human-readable representation of the given object. --- +---@see |vim.print()| ---@see https://github.com/kikito/inspect.lua ---@see https://github.com/mpeterv/vinspect local function inspect(object, options) -- luacheck: no unused @@ -870,6 +871,7 @@ end --- --- --- @see |vim.inspect()| +--- @see |:=| --- @return any # given arguments. function vim.print(...) if vim.in_fast_event() then diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua index 970bb56478..a8e75c4dc9 100644 --- a/runtime/lua/vim/lsp.lua +++ b/runtime/lua/vim/lsp.lua @@ -2457,7 +2457,7 @@ end --- buffer number as arguments. Example: --- 
lua
 ---               vim.lsp.for_each_buffer_client(0, function(client, client_id, bufnr)
----                 print(vim.inspect(client))
+---                 vim.print(client)
 ---               end)
 ---
---@deprecated use lsp.get_active_clients({ bufnr = bufnr }) with regular loop diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py index b40f8526ea..96db0d1aad 100755 --- a/scripts/gen_vimdoc.py +++ b/scripts/gen_vimdoc.py @@ -2,7 +2,7 @@ """Generates Nvim :help docs from C/Lua docstrings, using Doxygen. Also generates *.mpack files. To inspect the *.mpack structure: - :new | put=v:lua.vim.inspect(v:lua.vim.mpack.unpack(readfile('runtime/doc/api.mpack','B'))) + :new | put=v:lua.vim.inspect(v:lua.vim.mpack.decode(readfile('runtime/doc/api.mpack','B'))) Flow: main diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c index 4c3faf8d8b..c1aef53dc0 100644 --- a/src/nvim/api/buffer.c +++ b/src/nvim/api/buffer.c @@ -84,7 +84,7 @@ Integer nvim_buf_line_count(Buffer buffer, Error *err) /// Activates buffer-update events on a channel, or as Lua callbacks. /// /// Example (Lua): capture buffer updates in a global `events` variable -/// (use "print(vim.inspect(events))" to see its contents): +/// (use "vim.print(events)" to see its contents): /// 
lua
 ///   events = {}
 ///   vim.api.nvim_buf_attach(0, false, {
diff --git a/src/nvim/api/extmark.c b/src/nvim/api/extmark.c
index a101e1bbf1..0608a8961d 100644
--- a/src/nvim/api/extmark.c
+++ b/src/nvim/api/extmark.c
@@ -320,7 +320,7 @@ ArrayOf(Integer) nvim_buf_get_extmark_by_id(Buffer buffer, Integer ns_id,
 ///   local ms  = api.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {})
 ///   -- Get all marks in this buffer + namespace.
 ///   local all = api.nvim_buf_get_extmarks(0, ns, 0, -1, {})
-///   print(vim.inspect(ms))
+///   vim.print(ms)
 ///
/// /// @param buffer Buffer handle, or 0 for current buffer